In previous topics you learned the API provided by the ToolBar and Commands classes to add, remove or modify the Chart FX pre-defined list of commands. This was useful as you were able to customize the default Chart FX ToolBar, by removing existing commands, changing the icons and other important aspects related to the Chart FX User Interface.
Chart FX allows not only the customization of the default ToolBar with pre-defined Chart FX commands, but also the addition of custom commands that you can process internally in your application.
Let's say, for example, you want to add a button in the Chart FX ToolBar that when pressed loads another chart with new data and new visual attributes. It is clear that Chart FX will not provide this functionality as a pre-defined command because it will not know how to react when end users actually press such a button. Therefore, you'll need to add a custom command that will give you the desired results.
As a matter of fact, not only can you create custom buttons but groups of buttons, lists and selectors that will seamlessly integrate into your application. This section explains the necessary steps to add custom commands to the Chart FX User Interface.
Adding a custom command to the ToolBar means setting the correct attributes using the Commands class and then using the properties and methods provided in the ToolBar class to physically add (or replace) that button in the ToolBar.
The following are the steps you need to follow to add a custom command to the Chart FX ToolBar:
1. Add a Custom Commands' ID to the Chart FX Commands List
The first step in adding one or more custom commands to the Chart FX UI is adding each ID to the Chart FX Commands list. You do this with the addCommand method supported by the Commands class.
The ID is an integer that Chart FX will use to identify the command when the user presses or interacts with it. This is a unique ID that will be associated to the custom command and should never be duplicated for use with another command. Chart FX defines its pre-defined IDs between 'CommandID.FIRST' (29440) and 'CommandID.LAST' (29951), so please make sure you don't use a number in this range as it will cause unpredictable results. You can add a custom command with ID 4 as follows:
chart1.getCommands().addCommand(4);
|
2. Setting the Visual Attributes of the Custom Command
Once the Command ID has been added to the list, you must instruct Chart FX how to display this command in the UI (is it a button or a list?, what icon is it going to use?, what text is it going to display?, is it enabled?). There is a property for each particular attribute in the commands object as follows:
Style. The Style property allows you to tell Chart FX if the command you're adding is a two-state button, a list, a selector or member of a group. If you do not set the Style property, the custom command is added as a regular button. If you want to create a two-state button you can set the Style property as follows:
chart1.getCommands(4).setStyle(CommandStyle.TWO_STATE);
|
Picture. The Picture property allows you to specify the icon to be used in the button. Please note that you can add your own buttons as described in the "Changing/Adding icons" section. Here is a sample of how to set the picture to the pre-defined icon with the index 2:
chart1.getCommands(4).setPicture(2);
|
Text. The Text property allows you to set the ToolTip to be displayed or the text if the command is to be shown in the MenuBar. For example, to set a new ToolTip for the button you can set the Text property as follows:
chart1.getCommands(4).setText("New ToolTip");
|
3. Adding the Custom Command to the ToolBar
To add the CommandID 4 to the ToolBar, you can use the insertAt method and the CommandID properties exposed by the ToolBar class, as follows:
chart1.getToolBarObj().insertAt(3);
chart1.getToolBarObj().setItem(3,4);
|
4. Processing the Custom Command
Now that you have added a Custom command to the Chart FX commands list and added a button to the ToolBar, you need a mechanism to add your custom code that processes that particular command. The UserCommand Event is posted to your application when the user clicks or interacts with the custom command you have added. So if you want to change the chart gallery to lines when the user presses the button, you will process the UserCommand event as follows:
Private Sub Chart1_UserCommand(ByVal sender As Object, ByVal e As SoftwareFX.ChartFX.CommandUIEventArgs) Handles Chart1.UserCommand If (e.ID = 4) Then Chart1.Gallery = Gallery.Lines End If End Sub
|
|