Class Documentation

Name:ToolBar
Version:1.0
ID:ID_TOOLBAR
Status:Beta
Category:GUI
Date:November 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  The ToolBar class is used to create and manage groups of toolbars.



Description

The ToolBar class creates and manages the use of toolbars in application interfaces. A toolbar is a horizontal or vertical strip of items, each of which performs a specific function. Each item is presented as a button that contain an icon image, text string or combination of both.

The definitions for the toolbar are loaded by default from the environment file "templates:toolbardef.xml". You can change the template file prior to initialisation by setting the Template field. Note that any values set in the template will override your original field settings for the toolbar.

Items can be added to the toolbar using XML (recommended for scripting) or the AddToolItem method. Once you have built the toolbar structure, it will become functional as soon as you display it. The following example illustrates how you might create a toolbar using DML code:

  <toolbar x="[owner.leftmargin]" y="[owner.topmargin]" xoffset="[owner.rightmargin]"
    height="24">
    <xml-translate>
      <item text="Cut" tip="Cut" icon="tools/cut">
        <action object="[fileview]" method="cutfiles"/>
      </item>

      <item text="Copy" tip="Copy" icon="tools/copy">
        <action object="[fileview]" method="copyfiles"/>
      </item>

      <item text="Paste" tip="Paste" icon="tools/paste">
        <action object="[fileview]" method="pastefiles"/>
      </item>
    </xml-translate>
  </toolbar>

Actions

The ToolBar class supports the following actions:

Activate  Activates the currently selected item in the toolbar.
Disable  Turns the entire toolbar off.
Enable  Turns the toolbar on if it has been disabled.
Focus  Sets the focus on the toolbar and activates keyboard monitoring.
Hide  Removes the toolbar from the display.
LostFocus  Removes the focus from the toolbar and disables key monitoring.
MoveToBack  Moves the toolbar to the back of the display area.
MoveToFront  Moves the toolbar to the front of the display area.
Redimension  Changes the size and position of the toolbar.
Resize  Alters the size of the toolbar.
Show  Puts the toolbar on display.
UserClick  Emulates a user click on the toolbar.
UserClickRelease  Emulates a user click-release on the toolbar.
UserMovement  Emulates user movement over the toolbar.

Methods

The ToolBar class implements the following methods:

AddToolItem  Adds a new item to the toolbar.
DisableItem  Disables a toolbar item.
EnableItem  Enables a toolbar item that has been earlier disabled.
RemoveItem  Removes an item from the toolbar.

Structure

The ToolBar object consists of the following public fields:

Bottom  The bottom coordinate of the toolbar.
Drawable  The drawable that will contain the toolbar graphic.
Flags  Optional flags may be set here.
Height  Defines the height of a toolbar.
Highlight  String-based field for setting the toolbar highlight.
HighlightRGB  Defines border highlight of the toolbar, in RGB format.
Right  The right coordinate of the toolbar.
Shadow  String-based field for setting the toolbar shadow.
ShadowRGB  Defines border shadow of the toolbar, in RGB format.
TabFocus  Setting this field to a valid TabFocus object will cause the toolbar to add itself to the tab list.
Template  Defines the makeup of the toolbar using a pre-defined template.
Thickness  The thickness of the toolbar border.
Width  Defines the width of a toolbar.
XCoord  The horizontal position of a toolbar.
XOffset  The horizontal offset of a toolbar.
YCoord  The vertical position of a toolbar.
YOffset  The vertical offset of a toolbar.
Method:AddToolItem()
Synonym:AddItem
Short:Adds a new item to the toolbar.
Arguments:
STRING Name  The name or text to display for the item.
STRING Tip  A tool-tip to display for the item when the user's pointer hovers over it.
STRING Icon  The icon to use for the item.
STRING Script  A script statement to be executed when the item is clicked by the user.

New items can be added to the toolbar by calling this method. At a minimum you are required to specify a Name for the new item. The Name will double-up as the item text that is displayed in the toolbar. Set the Tip string if you would like a tool-tip to be displayed when the mouse pointer is positioned over the item.

The Icon parameter allows icons to be displayed instead of text inside the toolbar. The icon string should reference an image from the icon database, using the format "category/icon". You may specify a custom icon image if you wish - the routine will detect this if it determines that you have specified a complete file path in the Icon string.

To execute a script statement when the user clicks on the item, set the Script field. The string that you provide must be in a recognisable script format, such as DML code. If you would like to execute a script file when the item is activated, use the string format 'script src="path:file"'. Note: Your script must not create static objects that could linger after the script has been executed.

Result
ERR_Okay  The new item was added successfully.
ERR_Args  Invalid arguments (the Name must be specified at a minimum).
ERR_ArrayFull  No more items can be added because the toolbar is at maximum capacity.

Method:DisableItem()
Short:Disables a toolbar item.
Arguments:
STRING Name  The name of the item to be disabled.

Individual toolbar items can be disabled by calling this method. You are required to provide the name of the item that you want to disable. If multiple items share the same name, they will all be disabled. The toolbar will be automatically redrawn as a result of calling this method.

A disabled item can be re-enabled by calling the EnableItem() method.

Result
ERR_Okay  The item was either disabled or does not exist.
ERR_Args  A valid Name was not specified.

Method:EnableItem()
Short:Enables a toolbar item that has been earlier disabled.
Arguments:
STRING Name  The name of the item to be enabled.

Items that have been disabled can be re-enabled by calling this method. You are required to provide the name of the item that you want to enable. If multiple items share the same name, they will all be enabled.

Result
ERR_Okay  The item was either enabled or does not exist.
ERR_Args  A valid Name was not specified.

Method:RemoveItem()
Short:Removes an item from the toolbar.
Arguments:
STRING Name  The name of the item that you want to remove.

This method will remove items from the toolbar. You need to provide the name of the item that you want to remove. If items matching the name that you provide will be deleted.

The toolbar will be automatically redrawn as a result of calling this method.

Result
ERR_Okay  The item was removed.
ERR_Args  A valid Name parameter was not specified.

Field:Bottom
Short:The bottom coordinate of the toolbar.
Type:LONG
Status:Get

The bottom coordinate of the toolbar (calculated as YCoord + Height) is readable from this field.


Field:Drawable
Short:The drawable that will contain the toolbar graphic.
Type:OBJECTID
Status:Read/Init

The drawable that will contain the toolbar graphic is set here. If this field is not set prior to initialisation, the toolbar will attempt to scan for the correct drawable by analysing its parents until it finds a suitable candidate.


Field:Flags
Short:Optional flags may be set here.
Type:LONG
Status:Read/Init

Optional flags that may be set against a toolbar object are as follows:

FlagDescription
HIDEThis flag may be set on initialisation in order to hide the toolbar on its creation (applies to script usage only).
DISABLEDThis readable flag is automatically set when the toolbar is disabled. You may set it on initialisation if the toolbar is to be disabled on creation.
LOCALBy default, the toolbar will send messages to its child objects when the toolbar state changes. If you set the LOCAL option, the toolbar will execute the objects within its own process space.

Field:Height
Short:Defines the height of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A toolbar can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


Field:Highlight
Short:String-based field for setting the toolbar highlight.
Type:STRING
Status:Set

The border highlight of a toolbar is set by writing to this field. The colour must be in hexadecimal or separated-decimal format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


Field:HighlightRGB
Short:Defines border highlight of the toolbar, in RGB format.
Type:RGB
Status:Read

The border highlight of the toolbar can be read in RGB format from this field.


Field:Right
Short:The right coordinate of the toolbar.
Type:LONG
Status:Get

The right coordinate of the toolbar (calculated as XCoord + Width) is readable from this field.


Field:Shadow
Short:String-based field for setting the toolbar shadow.
Type:STRING
Status:Set

The border shadow of a toolbar is set by writing to this field. The colour must be in hexadecimal or separated-decimal format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


Field:ShadowRGB
Short:Defines border shadow of the toolbar, in RGB format.
Type:RGB
Status:Read

The border shadow of the toolbar can be read in RGB format from this field.


Field:TabFocus
Short:Setting this field to a valid TabFocus object will cause the toolbar to add itself to the tab list.
Type:OBJECTID
Status:Set

The TabFocus field provides a convenient way of adding the toolbar to a TabFocus object, so that it can be focussed on via the tab key. Simply set this field to the ID of the TabFocus object that is managing the tab-list for the application window.


Field:Template
Short:Defines the makeup of the toolbar using a pre-defined template.
Type:STRING
Status:Init

Setting the Template field allows a toolbar defintion to be loaded from a pre-defined template file. The template may contain settings for all of the field values of a toolbar object, as well as a customised graphics script for building the look and feel of the toolbar. The template must be provided as an XML file that can contain two possible root tags - 'value' and 'graphics'. The value tag contains a list of field values for setting against the toolbar, while the graphics tag contains the graphical makeup of the toolbar. The following example illustrates how a customised toolbar can be created:

<?xml version="1.0"?>

<values>
  <exitframe value="1"/>
  <clickframe value="2"/>
  <enterframe value="3"/>
  <releaseframe value="1"/>
</values>

<graphics>
  <box frame="1" boxes="(r0,0,!0,!0) (r1,1,!1,!1)" colour="230,230,230"
    highlight(0)="120,120,120" highlight(1)="255,255,255" shadow(0)="80,80,80"
    shadow(1)="200,200,200"/>
</graphics>

Field:Thickness
Short:The thickness of the toolbar border.
Type:LONG
Status:Read/Write

This field specifies the thickness of the toolbar border, expressed in pixels. By default the thickness is set to a value of 2.


Field:Width
Short:Defines the width of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A toolbar can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:The horizontal position of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a toolbar can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:The horizontal offset of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

If set in conjunction with an X coordinate then the toolbar will be drawn from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the ToolBar is dynamically calculated in relation to the width of the container.

If the XOffset field is set in conjunction with a fixed or relative width then the toolbar will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - ToolBarWidth - XOffset".


Field:YCoord
Short:The vertical position of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of a ToolBar can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:The vertical offset of a toolbar.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

If set in conjunction with a Y coordinate then the toolbar will be drawn from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the toolbar is dynamically calculated in relation to the height of the container.

If the YOffset field is set in conjunction with a fixed or relative height then the toolbar will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - ToolBarHeight - YOffset".