Toolbar Items
Introduction
In order to build toolbars, a number of new objects have been created to represent icons (actions), text, fills and space. This topic describes those objects and how to use them. All of these items inherit from fToolbarItem but this object does not have any properties or methods of its own. When examining a toolbar, each of the items will be one of these types. Note that toolbar groups, returns and dialogs are not yet supported in the Formatting Object Model.
Toolbar Actions
Toolbar Actions are the main building blocks of toolbars. They have as a minimum a name, an icon and something to do when the icon is clicked — an action.
The fApplication object has two methods for working with Toolbar Actions:
• fApplication.getToolbarAction() — this method returns the fToolbarAction object named. If there isn’t a Toolbar Action of that name, nothing will be returned.
• fApplication.createToolbarAction() — this method will create a new Toolbar Action of the specified name and return that fToolbarAction object.
So, to create a new Toolbar Action, use something like this:
var myAction = application.getToolbarAction("myAction");
if (!myAction) {
myAction = application.createToolbarAction("myAction");
}
This follows the standard Layout Developer FOM pattern of testing to see if something exists before trying to create one.
The fToolbarAction object has a number of properties. You will want to set the icon and action properties, but the others are also useful for creating usable toolbars.
• fToolbarAction.action — is a string which is the action to run if the icon is clicked. The string can be either a macro or JavaScript. If it is JavaScript, the code should be within braces, for example myToolbar.action = “{application.alert(‘HELLO WORLD’);}”. Otherwise, the string will be executed as a macro.
• fToolbarAction.description — another string which should be the text which appears in the status bar when the mouse is over the icon
• fToolbarAction.greyTestString — the string to use for the grey test. If the test evaluates to true or a non-zero value, the icon will be active. It is a good idea to look at other toolbar actions for hints on how to write these
• fToolbarAction.icon — the name of the icon to use
• fToolbarAction.selectedTestString — the string to use to show the icon as used. For example, if the action changes mode, this test would test the current more and if true, show the icon as selected
• fToolbarAction.text — the text to display for the action instead of or under the icon (if the toolbar is displaying text).
So, as an example, to create a new toolbar item use something like this:
var myAction = application.getToolbarAction("myTestJSAction");
if (!myAction) myAction = application.createToolbarAction("myTestJSAction");
myAction.action = 'boxit "HELLO WORLD"'
myAction.icon = "ald12_tedit_icon";
myAction.description = "CLICK ME!!";
myAction.text = "ALERT";
myAction.greyTestString = "(^[doc.window.id])";
myAction.selectedTestString = "";
Toolbar Actions are saved when the toolbars are saved into siconusr.3ic. These are the only one of the toolbar items which can be saved.
|
|
Icons are not yet represented in the FOM so must be declared in the siconusr.3ic file separately. Do not forget that from 12.0.0.0 PNG icons can be used rather than the hand-drawn native ones.
|
Text on Toolbars
Text can be used on toolbars to indicate the role or group of icons. To add text to a toolbar, use the constructor to create the fToolbarText object and add it.
To add text to a toolbar, use something like this:
var myText = new fToolbarText();
myText.text = "My Label: ";
myToolbar.addItem(myText);
Fill on Toolbars
Fills are used on toolbars to push a set of icons to the end of the toolbar. The fill will ensure enough space is added so that users don’t have to guess. So, if you want to push a set of icons to the far right of a toolbar at the top of the interface, use a fill before those icons.
To add a fill, use something like this:
var myFill = new fToolbarFill();
myToolbar.addItem(myFill);
Adding Space on Toolbars
Space is used to separate icons on a toolbar. Sometimes this is handy to imply a group of icons is separate from another. The width of the space can be set.
Use something like this to add space between icons:
var mySpace = new fToolbarSpace();
mySpace.width = 5;
myToolbar.addItem(mySpace);
Toolbar items
The fToolbar object has a property (fToolbar.items) which will return a list of the items on that toolbar.
The following script can be used to loop over all the active toolbars and their items, giving an alert of the toolbar name and information on each of the items:
var currentToolbars = application.activeToolbars;
application.alert("\n\nCURRENT TOOLBARS\n\n");
for (var t = 0; t < currentToolbars.length; t++) {
var tool = currentToolbars[t];
application.alert("Name " + currentToolbars[t].name + " Location " + currentToolbars[t].location);
application.alert(" Toolbar has " + tool.items.length + " items");
var items = tool.items;
for (var i = 0; i < items.length; i++) {
var item = items[i];
if (item instanceof fToolbarAction) { application.alert(" Action " + item.name);
}
else if (item instanceof fToolbarSpace) {
application.alert(" Space " + item.width);
}
else if (item instanceof fToolbarText) {
application.alert(" Text " + item.text);
}
else if (item instanceof fToolbarFill) {
application.alert(" Fill");
}
}
}
The ‘instanceof’ tests can be used to test which type of toolbar item is being handled.
