Just as a MainMenu object defines a menubar and is a container for menu items, a ToolBar object defines a toolbar and is a container for tool buttons. The toolbar itself is pointless without at least one tool button.

The ToolBar class defines many of the same properties that are defined for MainMenu. For example, a toolbar is by default at the top of a window, just under the menubar if one is present. But if a toolbar's Movable property is true, the user can move the toolbar elsewhere, by grabbing its move handle. You can also position a toolbar via the DockedPosition property. A toolbar's use of DockedPosition and Movable is identical to a menubar's use of those two properties. Also identical is the treatment of captions: a toolbar can have a caption, but it is normally not seen by the user. The caption is visible only when the toolbar is undocked. DockedPosition, Movable, and Captions are described in Section 4.2.1.

A window can have multiple toolbars. In this way, toolbars are very different from menubars: a window has at most a single menubar. If two menubars are defined for a window, the second is ignored. But a window can have many toolbars. Each toolbar is defined with its own ToolBar object. If there are two ToolBar objects that are both children of a window, there will be two toolbars on the window. By default, the toolbars will be at the top of the window, just under the menubar, and the first one defined will be above the second.

Figure 4.16. A toolbar and tool buttons

The individual icons on a toolbar are instances of the ToolButton class. In Figure 4.16, each of the eight icons (, , , and so on) is a ToolButton. Example 4.11 shows how the leftmost of the icons——is defined.

<object name="SaveAllT" class="ToolButton" parent="ToolBar">
  <property name="Caption" value=""/>
  <property name="Hint" value="Save All"/>
  <property name="DefaultImage" value="SaveAllImage"/>
  <property name="HotImage" value="HotSaveAllImage"/>
  <method name="LeftClick" action="SaveEverything"/>
</object>
<file name="SaveAllImage" server="iconserver" 
    hostfilename="book/examples/windowsetc/images/SaveAll.gif" 
    preload="true"/>
<file name="HotSaveAllImage" server="iconserver" 
    hostfilename="book/examples/windowsetc/images/HotSaveAll.gif" 
    preload="true"/>
	

The order of the definition of the tool button objects determines the placement of the tool buttons on the toolbar. The first one defined in a toolbar is at the left; the second one defined is second from the left, and so on. In this way tool buttons are again like menu items (see Section 4.2.2) and unlike most I³ML objects, whose placement and location are independent of the order of definition.

In Example 4.11, the DefaultImage property sets the image shown for the SaveAllT tool button. This image is defined by the file object to be a GIF found in an external file. (I³ML also supports BMPs and ICOs for tool button images.) Files are described in more detail in Chapter 12.

Often tool buttons have only a default image, a single image that is always shown for the tool button. But like many I³ML objects, tool buttons can be disabled, by setting their Enabled property to false. If a tool button is ever disabled, it is useful to visually display its disabledness, to remind the user that she cannot press it now.

I³ML supports a property to set a separate disabled image for the tool button: DisabledImage. If a disabled image is defined for a tool button, then when the tool button object is disabled, its display switches to that disabled image. Typically a disabled tool button image is a greyed out version of the default image, greyed out so the user can better recognize both the original icon and appreciate that the functionality is currently disabled. Figure 4.16 shows two disabled tool buttons. If no disabled image is defined for a tool button (as in Example 4.11), the button looks the same whether it is enabled or disabled.

A third image can also be defined for a tool button, a hot image. Hot images are shown when the mouse rolls over the button. (Hot images are different from hot keys. The latter are a kind of keyboard shortcut for a menu items, as described in Section 4.2.5.) Hot images are useful to remind the user that something will happen when a button is pressed, that is is active and ready. Example 4.11 shows the HotImage property as it is used to define a hot image for the tool button. If no hot image is defined for a tool button, nothing special happens when the mouse rolls over it. Either a hot image or a disabled image can be defined for a tool button, or both can be defined, or neither. They are independent properties.

Figure 4.16 also shows three separators, vertical bars that separate some of the tool buttons from others. Separators serve to organize the tool buttons in ways that are easier for the user to understand, grouping related tool buttons together. A separator is defined as a tool button with a Separator property of true, as shown in Example 4.12. Of course a separator does not function a tool button: it does not respond to a mouse click and it does not support images. Its only purpose is to organize (other) tool buttons.

<object name="ToolSep1" class="ToolButton" parent="ToolBar">
  <property name="Separator" value="True"/>
</object>
	

A tool button exists to trigger an action. For example, when the user presses the icon, a modal search window appears, as shown in Figure 4.17.

Figure 4.17. After pressing the find tool button

This works much like menu actions, a described in Section 4.2.7. When the user clicks on a tool button, the LeftClick action of the tool button is invoked. Example 4.13 shows how the tool button is defined, with the LeftClick action shown in bold. (The details of the action that display the modal window are not shown in Example 4.13, but can be found online at I3ML Examples.)

<object name="FindT" class="ToolButton" parent="ToolBar">
  <property name="Caption" value=""/>
  <property name="Hint" value="Find"/>
  <property name="DefaultImage" value="FindImage"/>
  <property name="HotImage" value="HotFindImage"/>
  <method name="LeftClick" action="FindWindow"/>
</object>
	

Figure 4.18. A toolbar with captions

Figure 4.18 shows the same window as Figure 4.16, but with text below each tool button. The text is there because each tool button has a value for its Caption property. For example, the tool button has the caption "Cut", as shown in Example 4.14.

<object name="CutT" class="ToolButton" parent="ToolBar">
  <property name="Caption" value="Cut"/>
  <property name="Hint" value="Cut"/>
  <property name="DefaultImage" value="CutImage"/>
  <property name="DisabledImage" value="DisabledCutImage"/>
  <property name="HotImage" value="HotCutImage"/>
</object>
	

The captions can be at the right of the buttons instead of below them, as shown in Figure 4.19. The TextOnRight property determines the placement of the tool button captions. If the value of TextOnRight is true, the text will be shown to the right, and if its value is false—the default—it will be shown below.

TextOnRight is a property of the toolbar as a whole, not of the individual tool buttons. Either each caption of every tool button is shown to the right of its button, or each is shown below, depending on the value of TextOnRight. Of course a window can have multiple toolbars, and one toolbar can have its tool button captions on the right while the other has captions below. (The merits of such a design is left to the judgment of the reader.)

Tool button captions can be formatted: you can specify that captions are to be in a bold Garamond font. All of the usual font formatting properties are available: FontName, FontSize, FontBold, FontItalic, FontUnderline, FontStrikeout, and FontColor. As with TextOnRight, these seven are properties of the toolbar as a whole, not of the individual tool buttons. All of the tool button captions in a toolbar must be in bold, or none will be in bold. The seven font properties are described in more detail in Section 3.4.2.

Figure 4.19. Big tool buttons, with captions on the right

Figure 4.19 is different in another way from Figure 4.18 and the other toolbars seen so far: the tool buttons are bigger. Tool button size is defined with a pair of properties: ImageHeight and ImageWidth. ImageHeight expresses the how tall the tool buttons are, and ImageWidth expresses their width. Both measures are expressed in pixels. The large buttons in Figure 4.19 are 24 pixels tall and 24 wide (24x24), as defined in Example 4.15.

<object name="ToolBar" class="ToolBar" parent="PIMWindow">
  <property name="Caption" value="Palmlike Toolbar"/>
  <property name="Color" value="c0c0c0"/>
  <property name="ImageHeight" value="24"/>
  <property name="ImageWidth" value="24"/>
  <property name="Movable" value="true"/>
  <property name="TextOnRight" value="true"/>
</object>
	

ImageHeight and ImageWidth are properties of the toolbar itself. All the tool buttons on the toolbar must be the same size. That is good: a toolbar with buttons of different sizes would look odd.

Most applications have tool buttons that are 16x16: that is by far the most common size for tool buttons, both for I³ML applications, and for applications more generally. The tool buttons in Figure 4.18 are 16x16, and in fact most of the windows in this book have 16x16 tool buttons.

24x24 is also a common size for tool buttons. Oblong 16x24 buttons are occasionally seen, as are very large 32x32 tool buttons. Other sizes are rare, but I³ML supports all sizes.

There are three styles of tool buttons: button, checked, and checkgroup. The style determines what happens visually when the button is pressed: does it pop back up, or does it stay down? Figure 4.20 shows a window that has tool buttons of each of the three styles. All of the tool buttons change the font of the text shown in the Preview pane: some change the font size, some the style, and some the color.

Consider first the size changing buttons: and . These buttons are of the button style. When pressed, they do their work and pop back up to where they were. They never stay down. All the tool buttons we have seen so far have been of the button style, and it is the default style for tool buttons.

Figure 4.20. Changing the font with tool buttons

The tool button exhibits the checked style. When it is pressed, it stays down until and unless it is pressed again. This is appropriate for its purpose in Figure 4.20: it changes the text to an italic font. In Figure 4.20 the button is already depressed: it is visually below the tool button to its right. And the text is already in italics. If the user presses the button again, the button will pop back up and the italicization will be turned off. Checked tool buttons are useful for user interfaces aspects (e.g. italicization) that can be in one of two states. The button gives the user a visual clue about which state the the UI is in.

Three other tool buttons in Figure 4.20 are also defined with a checked style: for bolding the text, for underlining the text, and for striking out the text. Each controls something that can be be in one of two states. For example the text can either be underlined or not.

Tool button style is defined with the Style property. Example 4.16 shows how the checked style is defined for the italic tool button.

<object name="UnderlineButton" class="ToolButton" 
      parent="FormatToolbar">
  <property name="Caption" value=""/>
  <property name="Style" value="Checked"/>
  <property name="Hint" value="Underline text"/>			
  <property name="NextValue" value="True"/>
  <property name="DefaultImage" value="UnderlineImage"/>
  <method name="LeftClick" action="ToggleUnderline"/>
</object>

In Figure 4.20, the user can change the font from Arial to Corsiva by pressing the tool button. When he presses the Corsiva button, it stays down, and the button pops up. The font names are all part of a checkgroup: like radio buttons only one of them can be selected at a time. This behavior is appropriate for font names, which are mutually exclusive; the text cannot be in both Arial and Corsiva at the same time.

Example 4.17 shows the Arial tool button. Its Style property is "CheckGroup". Note also that its Selected property is true. A tool button can be selected either by the user (with the mouse) or by you (with the Selected property); Selected is a dual active property. Selected is also defined for tool buttons that are not part of a checkgroup, that have a Style of "checked" instead.

<object name="ArialButton" class="ToolButton" parent="FontNameToolbar">
  <property name="Caption" value=""/>
  <property name="style" value="CheckGroup"/>
  <property name="hint" value="Arial text"/>
  <property name="selected" value="true"/>
  <property name="DefaultImage" value="ArialImage"/>
  <method name="LeftClick" action="MakeArial"/>
</object>
	

There are two different checkgroups in Figure 4.20, one for font names and the other for font colors. These need to be distinct groups. When the user selects to make her text red, the tool button should stay selected. The text cannot be both Corsiva and Arial at the same time, but it can be both Corsiva and red.

In I³ML, all the checkgroup tool buttons in a single toolbar are part of the same checkgroup. In other words, if you want to have separate checkgroups, you must put them in separate toolbars. The font names and font colors in Figure 4.20 are in fact in different toolbars.