Showing & Hiding the ToolBar
The ToolBar class exposes the Visible property that allows you to show or hide a selected ToolBar in the chart. The Boolean property may be used as follows:
chart1.setToolBar(true); chart1.setMenuBar(true);
chart1.getToolBarObj().setVisible(true); chart1.getMenuBarObj().setVisible(true);
|
Note: Please note that you can also use the properties dialog to configure this setting at design time.
Positioning the ToolBar
The ToolBar class exposes several members that allow you to position the ToolBar in the chart's bounding rectangle. By default, the position of the ToolBar is docked to the top margin. However, by using the Docked property you can position the selected ToolBar anywhere in the chart. For example, if you want to dock the ToolBar to the left margin programmatically, you can use the Docked property as follows:
chart1.getToolBarObj().setDocked(Docked.LEFT);
|
Removing Items from a ToolBar
You may want to remove buttons in the ToolBar as a result of a specific condition in your application. For example, you may not want the end user to switch between 2D and 3D modes therefore you can remove that button in the ToolBar. Or you may not want to allow users to save or open chart files. In this case, you can remove those buttons from the Chart FX ToolBar.
The ToolBar class supports the removeAt method to remove one or more items in the ToolBar. When using this method, please be aware that removed buttons will no longer exist in the ToolBar and all the indexes will be recalculated by Chart FX. For example, if you remove the first button in the ToolBar using the removeAt method, the index of the second button will become index 0, the index of the third button will become index 1, etc.
The removeAt method accepts 2 parameters; the first parameter receives the position from where to start removing items and the second parameter specifies the number of items to remove. Also, be aware that vertical separators count as additional ToolBar items, so if you plan to remove several buttons and they are separated, you must include the separators when calling the removeAt method. To remove the first two buttons in the ToolBar, you may call the removeAt method as follows:
chart1.getToolBarObj().removeAt(0, 2);
|
Changing Functions of Existing ToolBar Items
Chart FX exposes a wide variety of pre-defined commands that you can use to overwrite the functionality of buttons on the default ToolBar. New buttons can also be added to the ToolBar and configured to perform such actions. Not only can you use the existing commands Chart FX includes, but you can also cretate custom commands that can be processed internally by your application.
The CommandID constants allows you to easily overwrite the default actions performed by a ToolBar button (item) with any of the pre-defined Chart FX commands. For example, the Print button in the Chart FX ToolBar allows the end user to print the chart. This button prompts the user with a dialog where they select the number of copies and their printer. There may be a case where you do not want the users prompted by this dialog. The Chart FX pre-defined commands include a print command that will print a chart without prompting the user for any additional settings.
In the following sample, the default "Print with Printer dialog" command for the Chart FX ToolBar will be changed to the "Print without Printer dialog" command. Before you can change the command, you must determine the index of the print button item in the ToolBar.

As you can see, the print icon in the ToolBar is the third item visible; therefore the index of the item is 2. Now that we have established the index of the print button in the ToolBar, we can now assign the "Print without Printer dialog" command to that position. The following code will set the third item in the ToolBar to the Chart FX pre-defined print command:
chart1.getToolBarObj().setItem(2,CommandID.PRINT);
|
To change the command back to the default, you would do the following:
chart1.getToolBarObj().setItem(2,CommandID.PRINT_DIALOG);
|
Inserting Items in the ToolBar
There may be a situation where you want to include additional items in a selected ToolBar. To allow this the ToolBar class exposes the insertAt method. This method allows you to insert additional command buttons to the ToolBar that can be configured to execute existing Chart FX commands or a custom command that you may want to include in your application.
Chart FX exposes a wide variety of pre-defined commands through the CommandID constants. As stated earlier, these commands can be used to overwrite the functionality of existing buttons in the ToolBar or to assign actions to newly added buttons.
When adding buttons please be aware that the Chart FX ToolBar can handle up to 32 items (including buttons and separators), so when adding buttons in the ToolBar please be careful not to exceed that limit.
Let's suppose you want to limit the number of available gallery types that the end users may select from in a particular chart. The only gallery types that you want to grant access to are the Line, Area or Bar types. You decide that you want to remove the default gallery command from the ToolBar, and add three additional buttons in the ToolBar to select from the desired chart types.
The first thing you need to do is remove the gallery selector by using the removeAt method, covered earlier in the "Removing Buttons from a ToolBar" section. The gallery selector is the third item in the ToolBar, so to remove it we can use the removeAt method as follows:
chart1.getToolBarObj().removeAt(2, 1);
|
Once you have removed the gallery selector from the ToolBar, you will want to insert the desired gallery commands into the ToolBar. In order not to overwrite other commands in the ToolBar, you will need to insert some "place-holders" for the additional gallery commands. The ToolBar class provides the insertAt method that allows you to specify the index of where you would like to insert items into the ToolBar as well as the number of items you would like to add. The following code will insert 3 additional items into the ToolBar, and then assign those items the tree gallery commands:
chart1.getToolBarObj().insertAt(0); chart1.getToolBarObj().insertAt(0); chart1.getToolBarObj().insertAt(0); chart1.getToolBarObj().setItem(0,CommandID.BAR); chart1.getToolBarObj().setItem(1,CommandID.AREA); chart1.getToolBarObj().setItem(2,CommandID.LINE);
|
Please note that when you use the insertAt method, the indexes for other buttons in the ToolBar will be recalculated appropriately. In other words, because we have added 3 buttons at the beginning of the ToolBar, the index for the button that used to be in the first position is no longer 0 but 3 and the buttons that we have added will have indexes 0,1 and 2 respectively.
Important Note: Modifying just the ToolBar is no guarantee that the end user can only switch to those 3 chart types. The above example shows how to use the insertAt method to add buttons to the ToolBar. If you really want to prevent the end user from switching to other chart types, you have to modify the Commands list appropriately so those chart types may not be accessed from another tool in the Chart FX UI.
Modifying ToolTips
A ToolTip is text that appears when the user positions the mouse over any button in the ToolBar. This is very helpful as it informs the end user about the functionality of the button, without actually pressing it and performing the action.
You may think this ToolTip is part of the ToolBar, however, this text is also used in other parts of the Chart FX UI and therefore is controlled by the Commands class. This means that when you change the ToolTip associated with a particular command, this change will be consistent through out the Chart FX UI. Another point to keep in mind when changing ToolTips is that the text can be displayed somewhere else such as the MenuBar or context menus. Therefore, you must be careful not to make ToolTip strings too long or they will not be readable elsewhere.
To change the ToolTip associated with a particular command, you must first identify the command ID for the command you wish to modify. For example, if you want to change the ToolTip for the Gallery selector, you would reference the gallery enumeration (CommandID.Gallery). Once the desired command is referenced, you can set the text property for the command to modify the ToolTip:
chart1.getCommands((int) CommandID.BAR). setText("Bar Chart Custom ToolTip");
|
Changing ToolBar Icons
The entire collection of Chart FX tools shares the same icons used in the ToolBar, therefore the Commands class controls them. When you change an icon for a particular command, that change will be reflected in all of the other tools that allow access to that command. For example, the Data Editor icon is used in the ToolBar as well as the right-click context menus. When you change the icon associated with the Data Editor command, both tools will reflect the change.
Any command may be assigned a pre-defined Chart FX icon from the icon list or a custom icon that you add to the pre-defined list. This section will explain how to do both.
Selecting a Pre-Defined Icon
Chart FX provides a pre-defined list of 16x15 icons that are used for all the pre-defined commands. You can assign these pre-defined icons to other commands throughout the Chart FX user interface. To do this, the Commands class supports the setPicture property. Setting this property to the index of a desired icon in the icon list will assign that icon image to the referenced CommandID. Below is an example of the pre-defined icon list:

To change the Bar Chart command icon to the 'File' icon (index 1 in commands picture), you would use the following code:
chart1.getCommands((int) CommandID.BAR).setPicture(1);
|
Adding & Replacing Command Icons
Selecting an icon from the pre-defined list is not particularly useful because most of them are used by other Chart FX commands. This can cause confusion for the end user because the icons will not be unique to the function of a particular command. The addPicture and changePicture methods may be used to add and replace icons in the pre-defined icon list.
The addPicture method is particularly useful when you are adding custom commands to the Chart FX UI. This method will append one or more icons to the pre-defined icons list that you can use to assign to existing or new commands.
The changePicture method is most useful when you want to change icons that are already being used by Chart FX. This method allows you to replace all or part of the existing icon list.
When adding or replacing any image in the icon list, it is important that your custom icons have the proper dimensions (16 X 15 pixels). When adding multiple icons you must ensure there are no spaces between the custom icon images.
Working with Subcommands
Although most buttons in the Chart FX user interface (ToolBar, menu bar, etc) perform a specific action when pressed, there are other buttons that present a list of subcommands, one of which may be selected. For example, the Personalization button in the Chart FX ToolBar presents a list that allows the user to select personalization preferences, as depicted in the following figure:

These are called Subcommands lists and you can create or modify existing subcommands lists in the Chart FX user Interface. For this purpose, the Commands class exposes the getSubCommandID property as well as the removeSubCommand and removeAllSubCommands methods.
Removing Existing Subcommands
In the figure shown above, you can see how the Personalization Options command presents a list of subcommands that allow the end user to select which preference to apply to the chart. Let's suppose you want to remove end user access to the 'Restore Defaults' subcommand selection. You can easily remove that option from the Personalization Options subcommand list by invoking the removeSubCommand method as follows:
chart1.getCommands((int) CommandID. PERSONALIZED_OPTIONS).removeSubCommand(3);
|
Please note that when you remove a particular subcommand from the subcommand list, the indexes will be shifted to the actual number of subcommands available in the command. For example, if you wanted to remove the 'Remove Defaults' subcommand and the separator above it, you would need to remove the same index twice:
chart1.getCommands((int) CommandID. PERSONALIZED_OPTIONS).removeSubCommand(2); chart1.getCommands((int) CommandID. PERSONALIZED_OPTIONS).removeSubCommand(2);
|
You can also remove all subcommands from a command list by using the removeAllSubCommands method:
You can also remove all subcommands from a command list by using the removeAllSubCommands method:
chart1.getCommands((int) CommandID. PERSONALIZED_OPTIONS).removeAllSubCommands();
|
By removing a subcommand from the list, you will also remove this option from other tools that may use the same command ID.
Adding Subcommands
To add a subcommand to a list you will use the setSubCommandID property. If you are adding subcommands to a specific command you must make sure to keep the indexes in order as non-consecutive indexes may cause unpredictable results.
This feature is particularly useful when you are working with custom commands. So please refer to the "Adding Custom Commands" chapter, where we show a custom command that contains several subcommands.
Working with Selectors
A selector is a command that contains a list of subcommands that when pressed will show a list of images (icons) for selection and when closed will show the current selection. In Chart FX, the gallery icon in the ToolBar is a selector as shown in the following figure:

The only notable difference between selectors and subcommand lists is that the style for the subcommand has been set to 'Selector'. For more information on controlling the style for a particular command, please refer to the setStyle property in the commands class.
|