• -canRemove lets you specify whether the item can be removed by the user from the toolbar. Possible values are 0 or 1 (default is 1). If the -canRemove option is set to 0, the Remove item command is disabled in the contextual menu associated with the item (this is the menu which pops up when clicking on the item with the control key down).

toolbar new ?-autosave (0|1)? ?-locked (0|1)? ?-allowed list? ?-default list?

The -autosave and -lock options have the same meaning as with the [toolbar configure] command:

These options can be modified later with the [toolbar configure] command.

The -allowed option lets you specify a list of tokens of allowed items: these are the items which will be displayed in the customization dialog and which the user can choose to insert in the toolbar or not. If this option is not specified, AlphaX will use all the currently known toolbar items.

The -default option lets you specify a list of tokens of default items: these are the items which constitute the default layout of the toolbar, used if the user has not yet customized the toolbar. They are displayed as a block at the bottom of the customization dialog. If this option is not specified, AlphaX provides a default layout containing the popup menus, and the "customize" and "print" items.

• -canRemove lets you specify whether the item can be removed from the toolbar by the user. Possible values are 0, 1, or -1.
• -enable lets you specify whether the item is enabled or not. Possible values are 0, 1, or -1.
• -select lets you specify whether the item is in selected state or not. Possible values are 0, 1, or -1.

When the -enable, -canRemove and -select properties are set globally on the toolbar, the possible values for these options are 0 or 1 (to unset or set the property respectively). When these options are used per-window (with the -w option), the possible values are 0, 1 or -1 with the following meaning:

• 0 means that the property is unset for this particular window, no matter what the global setting is at the tollbar's level. This is an override.
• 1 means that the property is set for this particular window, no matter what the global setting is at the tollbar's level. This is the opposite override.
• -1 means that any override installed on this window should be removed so that the window uses the toolbar's global setting for the property.

core commands support a -bar option which lets you specify the

If the -bar option is not specified, the window is created with

     new -n "some window" -bar $tbar

     edit -bar $tbar $someFile

• The [customize] subcommand
• The [delete] subcommand
• The [hide] subcommand
• The [index] subcommand
• The [items] subcommand
• The [list] subcommand
• The [new] subcommand
• The [present] subcommand
• The [remove] subcommand
• The [search] subcommand
• The [set] subcommand
• The [show] subcommand
• The [visible] subcommand
• The [which] subcommand

• Built-in toolbar items
• Icon codes
  • Registered custom codes
  • Predefined codes
• Attaching a toolbar
• Toolbar visibility
• Examples

The [toolbar] command lets you interact with the toolbar located at

of this toolbar, to show or hide it, to modify its contents by adding or removing items, to modify the properties of each item, etc.

AlphaX provides some predefined toolbar items (print button, search field, separators, etc.) but it is also possible to create programmatically (i-e from a Tcl script) new custom items to insert in the toolbar. These items work as ordinary clickable toolbar buttons. Different options let you customize the appearance of an item (label, icon, help string) and the Tcl proc to execute when this item is clicked.

AlphaX provides a default toolbar but, since version 8.2b8, it is also possible, with the [toolbar] command, to create new toolbars and attach them to some windows instead of the default toobar.

subcommand, various arguments and options can be additionnally specified. Many of the subcommands take a token argument to designate a toolbar item. This is either the token returned by the [toolbar create] command if it refers to a custom item, or the symbolic name of a built-in item. New toolbars are also identified by a unique token which is attributed by the [token new] command. Some of the subcommands accept a -bar option to specify on which toolbar they operate. If this option is not specified, the subcommand will apply to the default toolbar. The documentation, in the following sections, takes care of using different terms (itemToken and toolbarToken respectively) to clearly make the distinction between the two kinds of tokens.

toolbar add itemToken ?-index value? ?-bar toolbarToken?

Here is the meaning of the possible options:

• -index specifies the position index where to insert the new toolbar item. The leftmost position is at index 0. If this option is unspecified, the toolbar item is appended at the right of the toolbar.
• -bar specifies the toolbar in which to add the item

toolbar configure ?-bar toolbarToken? option

toolbar configure ?-bar toolbarToken? option value ?option value...?

• the -bar option lets you specify the toolbar whose properties you want to get or set.

• the -autosave option lets you enable automatic recording of a customized layout chosen by the user. The values for this option are 0 (disable autosave) or 1 (enable autosave). The default value is 1.

toolbar count ?-bar toolbarToken?

Here is the meaning of the possible options:

• -canRemove lets you specify whether the item can be removed by the user from the toolbar. Possible values are 0 or 1 (default is 1). If the -canRemove option is set to 0, the Remove item command is disabled in the contextual menu associated with the item (i-e the menu which pops up when clicking on the item with the control key down).

The [customize] subcommand

This command displays the sheet dialog which lets the user modify the layout and the contents of the toolbar. The syntax is:

toolbar customize ?-w win? If the -w option is not specified, the command applies to the frontmost window. If there is no window, the command returns silently.

The [delete] subcommand

toolbar delete itemToken

The [hide] subcommand

If the -w option is not specified, the command applies to the frontmost document window. If there is no window, the command returns silently.

The [index] subcommand

toolbar index itemToken ?-bar toolbarToken? ?-all?

If the item designated by itemToken is not currently present in

In case the toolbar item has multiple instances in the toolbar and the option -all is specified, the command returns the list of all the matching indices. Otherwise only the first index found is returned. For instance, there could be multiple space or separator items.

The [items] subcommand

toolbar items ?-bar toolbarToken? ?-all?

With the -all option the command returns a list of tokens for all the registered toolbar items: built-in items as well a custom items created with the [toolbar add] command are included in this list. All the existing items are reported in the list, no matter whether they are inserted in the toolbar or not. The tokens are in creation order.

Otherwise, this command returns a list of tokens corresponding to the current layout of the toolbar specified by the -bar option or the default toolbar is there is no -bar option. This is the list of items inserted in the toolbar in the left to right order.

The -bar option is irrelevant when the -all option is specified.

The [list] subcommand

This command returns the list of all the existing toolbar tokens. The syntax is:

toolbar list The default toolbar always corresponds to the first token of the list.

The [new] subcommand

This command lets you create a new toolbar. The syntax is:

toolbar new ?-autosave (0|1)? ?-locked (0|1)? It returns a unique token for the toolbar which can be used as the value of the -bar option supported by other subcommands. The -autosave and -lock options have the same meaning as with the [toolbar configure] command.

• when -autosave is set to 1, allow the toolbar to save its configuration automatically. The default value is 0.
• when -locked is set to 1, the user cannot bring up the configuration palette. The default value is 0.

These options be modified later with the [toolbar configure] command.

The [present] subcommand

This command tells whether a toolbar item is present in a toolbar. The

toolbar present itemToken ?-bar toolbarToken?

If the item designated by itemToken is not currently present in the toolbar, the command returns 0. Otherwise it returns 1.

The [toolbar present] command applies to both built-in items and

The [remove] subcommand

toolbar remove itemToken ?-bar toolbarToken?

toolbar remove -index num ?-bar toolbarToken?

the -canRemove option had been specified with value 1 to make the item non removable. The -canRemove option is intended to make an item non removable for the user: the item can still be removed programmatically by the [toolbar remove] command.

The [search] subcommand

The [set] subcommand

toolbar set itemToken ?-w win? ?-bar toolbarToken? option

toolbar set itemToken ?-w win? ?-bar toolbarToken? option value ?option value...?

item: only the -help, -label, -enabled, and -canRemove options

• the -bar option lets you specify the toolbar containing the item whose properties you want to get or set.
• the -w option lets you specify a particular window so that only the item in this window will be affected. Note that only the -enable, -canRemove and -select properties can be set on a per-window basis.

• -canRemove lets you specify whether the item can be removed from the toolbar by the user. Possible values are 0 or 1.
• -select lets you specify whether the item is in selected state or not. Possible values are 0 or 1.

The -command and the -icon options cannot be set on built-in items.

When both the -bar and the -w options are specified, they must correspond to each other, i-e the toolbar must be attached to this specific window, otherwise the command raises an error. If only the -w option is specified, the toolbar will be, by default, this window's toolbar: if the window has no toolbar, the command returns an error. If neither the -bar option, nor the -w option are specified, the command applies to the default toolbar and affects the item in all the windows containing this toolbar.

The [show] subcommand

frontmost document window. If there is no window, the command returns silently.

The [visible] subcommand

frontmost document window. If the window does not have a toolbar or if no

The [which] subcommand

This subcommand is the opposite of the [hide] subcommand. It lets you display the toolbar if it is hidden.

toolbar which ?-w win? ?toolbarToken?

If the -w option is not specified, the command applies to the frontmost document window. If there is no window, the command returns silently.

If the last argument toolbarToken is not specified, the command returns the token of the toolbar currently attached to the window or an empty string if there is no toolbar. If toolbarToken is specified and is the token of an existing toolbar, the toolbar currently attached to the window (if any) is removed and replaced by the new one. As a special case, one can specify an empty string for the toolbarToken argument in order to just detach the current toolbar from the window.

Built-in toolbar items

They are referred to as built-in toolbar items because they are not created programmatically with the [toolbar create] command. They all have a symbolic name to use in place of the itemToken argument expected by some toolbar subcommands. Here is the list of symbolic names:

The browse, print, and search items have predefined commands which cannot be modified with [toolbar set]. The corresponding procs are respectively toolbar::doBrowse, toolbar::doPrint, and toolbar::doSearch. These procs are defined by AlphaTcl in the file Tcl/SystemCode/toolbar.tcl.

Icon codes

Registered custom codes

available in the [Commands.IconrefCommand] page on this wiki.

Predefined codes

Attaching a toolbar

Since version 8.2b8 of AlphaX, the [new] and the [openFile] core commands support a -toolbar option which lets you specify the token of a toolbar to attach to the window they create. This option is also available with the [edit] proc. If the -toolbar option is not specified, the window is created with the default toolbar defined by AlphaX, unless there is an -attr option containing the No Toolbar attribute (see the WindowAttributes page).

Toolbar visibility

The Toolbar Visible global preference lets you specify if the toolbar attached to a window should be initially visible. If this preference is set to 0, a newly created window will not display the toolbar: in order to make the toolbar visible, one must click on the oval button located at the right of the title bar of the window. The Toolbar Visible preference can be found in the Window panel of the preferences dialog displayed by the AlphaX >Preferences > Global Preferences command. The oval button can be used to hide or display the toolbar attached to a window. Pressing the option key while clicking in this button toggles the tollbar's visibility for all the windows and not only for the current one. Pressing the command key while clicking in this button lets you modify the size and the display mode of the toolbar. Programmatically, it is also possible to create windows which do not have a toolbar at all. See the WindowAttributes page.

Examples

     toolbar configure -mode label
     toolbar configure -mode default

     toolbar configure -locked 
     toolbar configure -locked 1
     toolbar configure -locked 0

     toolbar customize -w $w

To create a new toolbar and add a few toolbar items to it:

 
     set tbar [toolbar new]
     toolbar add browse -bar $tbar
     toolbar add flexible -bar $tbar
     toolbar add print -bar $tbar

To create a new window with this toolbar:

 
     new -n "some window" -toolbar $tbar

To edit a file in a window with the new toolbar:

 
     edit -toolbar $tbar $someFile

To disable the "print" toolbar item only in a given window:

 
     toolbar set print -w $someWindow -enable 0

To prevent the "search" field to be removed from a toolbar which contains it:

 
     toolbar set search -canRemove 0

If this property must be set only on a particular window:

 
     toolbar set search -canRemove 0 -w $someWindow

noletocadom

oloccvar

available in the IconrefCommand page on this wiki.

(:title The [toolbar] command:)

• -description concerns the text to be displayed in the text field when the field does not have focus and contains no user entered text. The documentation designates it as the descriptive text. The search field item must be present in the toolbar for this option to apply otherwise the command raises an error.

• -text is the search string. It can be used to get or set programmatically the string to search. The search field item must be present in the toolbar for this option to apply otherwise the command raises an error.

properties of the Search Field toolbar item.

• -description concerns the text to be displayed in the text field when the field does not have focus and contains no user entered text. The documentation designates it as the descriptive text. The search field item must present in the toolbar for this option to apply otherwise the command raises an error.

• -text is the search string. It can be used to get or set programmatically the string to search. The search field item must present in the toolbar for this option to apply otherwise the command raises an error.

• The [search] subcommand
• The [set] subcommand
• The [show] subcommand
• The [visible] subcommand

• Built-in toolbar items
• Icon codes
  • Registered custom codes
  • Predefined codes
• Examples

The [search] subcommand

The [toolbar search] command lets you get or set the value of certain properties of the Search Field toolbar item. It assumes that the search field item is present in the toolbar otherwise it raises an error.

toolbar search option

toolbar search option value ?option value...?

The first form returns the value of the option specified as the third

• -description concerns the text to be displayed in the text field when the field does not have focus and contains no user entered text. The documentation designates it as the descriptive text.
• -menu concerns the menu attached to the search field. This menu is indicated by a small triangle added to the search icon (the magnifying glass). It can be used, for instance, to keep a history of the most recent strings entered in the text field. The value of this option is a Tcl list containing the items inserted in this menu.
• -text is the search string. It can be used to get or set programmatically the string to search.

When an item is selected in the menu attached to the search field, the [toolbar::searchMenuProc] proc is invoked with the index of the selected item as argument. To reset the menu, just pass an empty list like this:

 
     toolbar search -menu {}

The [set] subcommand

The [toolbar set] command lets you get or set the value of certain properties of a custom toolbar item previously created by a [toolbar add] command.

There are two forms for the syntax of this subcommand:

toolbar set token option

toolbar set token option value ?option value...?

The [toolbar set] command applies to both built-in items and custom items but not all options are supported when applied to a built-in item: only the -help, -label, -enabled, and -remove options can be set for built-in items; the -icon and -command options are ignored.

The first form returns the value of the option specified as the fourth argument. The second form lets you set the value of various options.

Here is the description of the currently available options:

The [show] subcommand

The [visible] subcommand

visible. If the window has no toolbar, false is returned.

topmost document window. If the window does not have a toolbar or if no window is open, the command returns 0.

Built-in toolbar items

Icon codes

Registered custom codes

Predefined codes

Examples

visible. If the window has no toolbar, or if no window is open, 0 is returned.

topmost document window.

• The [visible] subcommand

• Built-in toolbar items
• Icon codes
  • Registered custom codes
  • Predefined codes
• Examples

The [visible] subcommand

This subcommand returns whether the toolbar (if any) attached to a window is visible. If the window has no toolbar, false is returned.

toolbar visible ?-w win?

If the -w option is not specified, the command applies to the topmost document window. If the window does not have a toolbar or if no window is open, the command returns 0.

Built-in toolbar items

Icon codes

Registered custom codes

Predefined codes

Examples

• Introduction
• Synopsis
  • The [add] subcommand
  • The [configure] subcommand
  • The [count] subcommand
  • The [create] subcommand
  • The [delete] subcommand
  • The [hide] subcommand
  • The [index] subcommand
  • The [items] subcommand
  • The [present] subcommand
  • The [remove] subcommand
  • The [set] subcommand
  • The [show] subcommand
• Built-in toolbar items
• Icon codes
  • Registered custom codes
  • Predefined codes
• Examples

Introduction

(label, icon) and the Tcl proc to execute when the item is clicked.

There are two kinds of toolbar items:

• built-in toolbar items provided by the core. They are identified by a symbolic name. See the Built-in toolbar items section below.
• toolbar items created programmatically with the [toolbar create] command. They are identified by a token attributed at creation time.

Both kinds of toolbar items can be added to or removed from the toolbar.

Synopsis

The possible subcommands are described below. Depending on the subcommand, various arguments and options can be specified additionnally. Many of the subcommands take a token argument. This is either the token returned by the [toolbar create] command if it refers to a custom item, or the symbolic name of a built-in item.

The [add] subcommand

The [toolbar add] command applies to both built-in items and custom items.

The [configure] subcommand

• icon indicates that only the image should be displayed
• label indicates that only the label should be displayed

The [count] subcommand

This command returns the number of items currently installed in the toolbar, including spaces, flexible spaces and separators. The syntax is:

toolbar count

The [create] subcommand

The [delete] subcommand

Built-in toolbar items cannot be deleted with [toolbar delete].

The [hide] subcommand

The [index] subcommand

This command returns the index of a toolbar item in the toolbar. The syntax is:

toolbar index token

The [toolbar index] command applies to both built-in items and custom items.

If the item designated by token is not currently present in the toolbar, the command returns -1. Otherwise it returns the position of the item in the left to right order. The leftmost position is at index 0.

The [items] subcommand

Only custom toolbar items created with the [toolbar add] command are included in this list. All the existing custom items are reported in the list, no matter whether they are inserted in the toolbar or not. The built-in items are not present in the list because they are always defined by the core and cannot be deleted.

The [present] subcommand

This command returns whether a toolbar item is present in the toolbar. The syntax is:

toolbar present token

The [toolbar index] command applies to both built-in items and custom items. The item could have been removed from the toolbar programmatically with the [toolbar remove] command, or manually by the user.

If the item designated by token is not currently present in the toolbar, the command returns 0. Otherwise it returns 1.

The [remove] subcommand

This command removes an item inserted in the toolbar. The syntax has two forms:

toolbar remove -index num

The first form uses the token of the item. The second one lets you remove an item at a specified index: the index is the position of the item in the toolbar in the left to right order. The leftmost item is at index 0. This can be useful in order to remove a separator, a space or a flexible space, since these items do not have a token.

The [toolbar remove] command applies to both built-in items and custom items.

The [set] subcommand

The [toolbar set] command applies to both built-in items and custom items but not all options are supported when applied to a built-in item: only the -help, -label, -enabled, and -remove options can be set for built-in items; the -icon and -command options are ignored.

The [show] subcommand

Built-in toolbar items

The AlphaX application provides several useful toolbar items. They are referred to a built-in toolbar items because they are not created programmatically with the [toolbar create] command. They all have a symbolic name to use in place of the token argument expected by some toolbar subcommands. Here is the list of symbolic names:

The browse, print, and search items are linked to the toolbar::doBrowse, toolbar::doPrint, and toolbar::doSearch Tcl procs respectively. These procs are defined by AlphaTcl in the file Tcl/SystemCode/toolbar.tcl.

Icon codes

The -iconref option available in the [toolbar create] and [toolbar set] commands to attach an icon to a toolbar item expects a four character code as its value. One can use one of the predefined icon codes provided by the system: the most common ones are given in the table below. Additionnally, AlphaTcl packages have the possibility of declaring new types using the [iconref] command as explained in the next section.

Registered custom codes

There is a new [iconref] command introduced in Alpha 8.1 which lets you register custom icons to use with the -iconref option. This command is used to declare and register a new type with the Icon Services. Once it is registered, one can use this type in any command supporting an -iconref option. More info about the [iconref] command is available in the [Commands.IconrefCommand] page on this wiki.

Predefined codes

The predefined four character codes provided by the system are defined in the header file Icons.h found in the HIServices framework. For convenience, here is a list of the main icons with their corresponding code. Note that the single quotes are not part of the code and should not be passed to the -iconref option.

Examples

 	toolbar configure -mode label
 	toolbar configure -mode default

     toolbar configure -autosave 
     toolbar configure -autosave 1
     toolbar configure -autosave 0

• iconlabel indicates to display the image as well as the label of the toolbar items

• normal indicates to use a larger text and icon size

     toolbar configure -mode label
     toolbar configure -mode default

set tbi1 [toolbar create -label "Query" -icon "help" -command tb::doquery] toolbar add $tbi1 set tbi1 [toolbar create -label "Desktop" -icon "desk" -command file::revealDesktop] toolbar add $tbi2

(label, icon) and the Tcl proc to execute when the item is clicked. The AlphaTcl library takes advantage of the techniques explained below in its always-on toolbar package: more info about this in the ToolbarPackage page.

• The [create] subcommand
• The [delete] subcommand

It is also possible to create programmatically, from a Tcl script, simple custom items to insert in the toolbar. These items work as an ordinary clickable toolbar button. Different options let you customize the appearance of the button (label, icon) and the Tcl proc to execute when the item is clicked.

various arguments and options can be specified additionnally.

This command lets you instantiate an item previously created with the [toolbar create] command. It is equivalent to choosing this item from the customization sheet and dragging it to the toolbar.

toolbar add token ?-index value?

• -index specifies the position index where to insert the new toolbar item. The leftmost position is at index 0. If this option is unspecified, the toolbar item is appended at the right of the toolbar.

The token argument is the value returned by the '''[toolbar create]''' command.

 ** iconlabel indicates to display the image as well as the label of the toolbar items 

 ** normal indicates to use a larger text and icon size 

• the -lock option lets you lock or unlock the toolbar. Locking the toolbar prevents the user from making modifications and customizing the layout. The values for this option are 0 (unlock) or 1 (lock). The default value is 0.
• the -autosave option lets you enable automatic recording of a customized layout chosen by the user.The values for this option are 0 (disable autosave) or 1 (enable autosave). The default value is 1.

The [toolbar configure] command concerns properties of the toolbar object itself: to modify the properties of a particular item in the toolbar, use the [toolbar set] command instead.

The [create] subcommand

This is the command used to declare a new toolbar item and to set its initial properties.

The general syntax of this subcommand is:

toolbar create ?option value? ?option value...?

Possible options are:

• -label sets the label of the item displayed in Text or Icon&Text modes. If this option is not specified, the default label is "Button".
• -help sets the help string displayed when the mouse stays over the item. If this option is not specified, there will be no help text.
• -command sets the name of the Tcl proc which will be executed when the item is clicked.
• -enable lets you specify whether the item is enabled or not. Possible values are 0 or 1 (default is 1).
• -remove lets you specify whether the item can be removed by the user from the toolbar. Possible values are 0 or 1 (default is 1). If the -remove option is set to 0, the Remove item command is disabled in the contextual menu associated with the item (i-e the menu which pops up when clicking on the item with the control key down).
• -icon lets you specify a four char code corresponding to a system icon reference. See some possible values in the section Icon codes below. If this option is not specified, the Unknown FSObject Icon (code 'unfs') will be used instead.

The [toolbar create] command returns a token which can be used later in other commands, such as the [toolbar add], the [toolbar remove] or the [toolbar set] commands.

Note that this command does not insert the toolbar item in the toolbar. It just declares a new type of custom toolbar item. To insert one in the toolbar one must use the [toolbar add] command with the token returned by the [toolbar create] command. All the items created with the [toolbar create] command are displayed in the customization dialog so that an user can insert them manually into the toolbar.

The [delete] subcommand

This command deletes an item previously created with the [toolbar create] command). The syntax is:

toolbar delete token

Once deleted this item will not be displayed in the customization dialog anymore and the token associated with it will not be valid anymore. If an instance of the item has been previously inserted in the toolbar (for instance with the [toolbar add] command or as a result of an user action), it will be removed from the toolbar. If you only want to remove an item from the toolbar, use the [toolbar remove] command instead of [toolbar delete].

[toolbar create] command). The syntax is:

Note that this command will remove an item from the toolbor even if the -remove option had been used with value 1 to make the item non removable. The -remove option is intended to make an item non removable for the user: the item can still be removed programmatically by the [toolbar remove] command.

• -remove lets you specify whether the item can be removed from the toolbar by the user. Possible values are 0 or 1.
• -icon lets you specify a four char code corresponding to a system icon ref. See some possible values in the section Icon codes below.

If the -w option is not specified, the command applies to the topmost document window.

 
     toolbar configure -size
     toolbar configure -size small
     toolbar configure -size default

     toolbar configure -mode
     toolbar configure -mode iconlabel
     toolbar configure -mode icon
 	toolbar configure -mode label
 	toolbar configure -mode default

     toolbar configure -autosave 
     toolbar configure -autosave 1
     toolbar configure -autosave 0

     toolbar configure -lock 
     toolbar configure -lock 1
     toolbar configure -lock 0

     toolbar hide
     toolbar show

     set w "some window"
     toolbar hide -w $w
     toolbar show -w $w

To create a new toolbar item:

 
     set tbi [toolbar create -label "Desktop" -help "Reveal the desktop" \
                          -icon "desk" -command file::revealDesktop]

The tbi variable contains the token designating the new toolbar item. At this point, this item is displayed in the customization sheet (invoked by clicking on the Customize toolbar item or by invoking the ''Customize toolbar'' command in the contextual menu associated with the toolbar). It can be inserted in the toolbar manually by dragging it from the customization dialog and dropping it on the toolbar, or programmatically like this:

 
     toolbar add $tbi

One can modify certain properties of a toolbar item using the ''[toolbar set]'' command. The following example modifies both the label and the icon of the previous item:

 
     toolbar set $tbi -label "Finder" -icon "help"

To remove the item from the toolbar:

 
     toolbar remove $tbi

To reinsert it, use [toolbar add $tbi] again. To destroy it entirely:

 
     toolbar delete $tbi

After a [toolbar delete] command, the $tbi token is not valid anymore and the item will not show anymore in the customization sheet.

Here are two instructions which will create two custom toolbar items. They are associated respectively with some hypothetical tb::doquery and file::revealDesktop Tcl procs which must be defined somewhere.

toolbar add -label "Query" -icon "help" -command tb::doquery toolbar add -label "Desktop" -icon "desk" -command file::revealDesktop

• iconlabel indicates to display the image as well as the label of the toolbar items

• normal indicates to use a larger text and icon size

Here are two instructions which will create two custom toolbar items. They are associated respectively with some hypothetical tb::doquery and file::revealDesktop Tcl procs which must be defined somewhere.

Here are two instructions which will create two custom toolbar items. They are associated respectively with some hypothetical tb::doquery and file::revealDesktop Tcl procs which must be defined somewhere.

toolbar add -label "Query" -help "Call the query info dialog" -iconref "help" -command tb::doquery
toolbar add -label "Desktop" -help "kDesktopIcon" -iconref "desk" -command file::revealDesktop

The result is shown on the image below: http://alphatcl.sourceforge.net/wiki/pub/images/tollbarItems.png

If you are looking for basic information about the toolbar graphic interface and user interaction, see the AlphaToolbar page on this Wiki.

@]

• -iconref lets you specify a four char code corresponding to a system icon ref. See some possible values in the section Icon codes below. The first form of the command does not work with this option.

• -iconref lets you specify a four char code corresponding to a system icon ref. See some possible values in the section Icon codes? below. The first form of the command does not work with this option.

Here is a list a short commands which can be executed from the Tcl shell in AlphaX:

toolbar configure -size toolbar configure -size small toolbar configure -size default

toolbar configure -mode toolbar configure -mode iconlabel toolbar configure -mode icon toolbar configure -mode label toolbar configure -mode default

toolbar configure -autoconfig toolbar configure -autoconfig 1 toolbar configure -autoconfig 0

toolbar configure -lock toolbar configure -lock 1 toolbar configure -lock 0

toolbar hide toolbar show

set w "some window" toolbar hide -w $w toolbar show -w $w

toolbar add -label "Query" -help "Call the query info dialog" -iconref "qery" -command tb::doquery

toolbar add -label "Desktop" -help "kDesktopIcon" -iconref "desk" -command file::revealDesktop

This file documents the [toolbar] command introduced in version 8.1 of AlphaX.

• Introduction
• Synopsis
  • The [add] subcommand
  • The [configure] subcommand
  • The [hide] subcommand
  • The [items] subcommand
  • The [remove] subcommand
  • The [set] subcommand
  • The [show] subcommand
• Icon codes
• Examples

Introduction

The [toolbar] command lets you interact with the Toolbar object located at the top of the document windows. It is possible to modify the attributes of this toolbar, to show or hide it and also to create new custom toolbar items.

Synopsis

The formal syntax of the [toolbar] command is:

toolbar subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be specified additionnally.

The [add] subcommand

It is possible to create programmatically from a Tcl script simple custom items to insert in the toolbar. These items work as an ordinary clickable toolbar button. Different options let you customize the appearance of the button (label, icon) and the Tcl proc to execute when the item is clicked.

The general syntax of this subcommand is:

toolbar add ?option value? ?option value...?

Possible options are:

• -index spedifies the position index where to insert the new toolbar item. The leftmost position is at index 0. If this option is unspecified, the toolbar item is appended at the right of the toolbar.
• -label sets the label of the item displayed in Text or Icon&Text modes. If this option is not specified, the default label is "Button".
• -help sets the help string displayed when the mouse stays over the item. If this option is not specified, there will be no help text.
• -command sets the name of the Tcl proc which will be executed when the item is clicked.
• -enable lets you specify whether the item is enabled or not. Possible values are 0 or 1 (default is 1).
• -iconref lets you specify a four char code corresponding to a system icon ref. See some possible values in the section Icon codes? below. If this option is not specified, the Unknown FSObject Icon (code 'unfs') will be used.

The [toolbar add] command returns a token which can be used later in other commands, such as the [toolbar remove] and the [toolbar set] commands.

Note that these custom toolbar items cannot be removed from the toolbar by the user using the Remove Item command in the contextual menu: you can remove them only programmatically with the [toolbar remove] command.

The [configure] subcommand

There are two forms for the syntax of this subcommand:

toolbar configure option

toolbar configure option value ?option value...? The first form returns the value of the option specified as the third argument. The second form lets you set the value of different options. Here is the description of the currently available options:

• the -mode option lets you specify the display mode. The possible values for this option are iconlabel, icon, label, and default:

 ** iconlabel indicates to display the image as well as the label of the toolbar items 

• icon indicates that only the image should be shown
• label indicates that only the label should be shown
• default indicates to use the default display mode. Currently, this is defined as being both icon and label, but could change in the future.

• the -size option lets you specify the display size. The possible values for this option are normal, small, and default:

 ** normal indicates to use a larger text and icon size 

• small indicates to use a smaller text and icon size
• default indicates to use the default display size. Currently, this is defined as using 32 x 32 icons, which is the normal size.

• the -lock option lets you lock or unlock the toolbar. Locking the toolbar prevents the user from making modifications and customizing the layout. The values for this option are 0 (unlock) or 1 (lock).
• the -autosave option lets you enable automatic recording of a customized layout chosen by the user.The values for this option are 0 (disable autosave) or 1 (enable autosave).

The [hide] subcommand

This command lets you hide the toolbar for a particular window. This is the same as clicking on the top right oval button located in the titlebar (not toolbar) of the window. The syntax is:

toolbar hide ?-w win?

If the -w option is not specified, the command applies to the topmost document window.

The [items] subcommand

This command returns the list of the custom toolbar items. The syntax is:

toolbar items

Only custom toolbar items created with the [toolbar add] command are included in this list.

The [remove] subcommand

This command removes an item inserted in the toolbar. Its unique argument is the token designating the toolbar item (and which was returned by the [toolbar add] command). The syntax is:

toolbar remove token

Only toolbar items created with the [toolbar add] command can be removed. The info menus and position indicators are not removeable.

The [set] subcommand

The [toolbar set] command lets you get or set the value of certain properties of a custom toolbar item previously created by a [toolbar add] command.

There are two forms for the syntax of this subcommand:

toolbar set token option

toolbar set token option value ?option value...?

The token argument is the token returned by the [toolbar add] command when the toolbar item was created. The first form returns the value of the option specified as the fourth argument. The second form lets you set the value of various options.

Here is the description of the currently available options:

• -label sets the label of the item displayed in Text or Icon&Text modes.
• -help sets the help string displayed when the mouse stays over the item. If this option is not specified, there will be no help text.
• -command sets the name of the Tcl proc which will be executed when the item is clicked.
• -enable lets you specify whether the item is enabled or not. Possible values are 0 or 1.
• -iconref lets you specify a four char code corresponding to a system icon ref. See some possible values in the section Icon codes? below. The first form of the command does not work with this option.

Note that these custom toolbar items cannot be removed from the toolbar by the user using the Remove Item command in the contextual menu: you can remove them only programmatically with the [toolbar remove] command.

The [show] subcommand

This subcommand is the opposite of the [hide] subcommand. It lets you display the toolbar if it is hidden.

toolbar show ?-w win?

If the -w option is not specified, the command applies to the topmost document window.

Icon codes

The four char codes corresponding to the various system icons which can be used with the -iconref in the [toolbar add] command are defined in the header file Icons.h found in the HIServices framework. For convenience, here is a list of the main icons with the corresponding code. Note that the single quotes are not part of the code and should not be passed to the -iconref option.

Examples

 
     toolbar configure -size
     toolbar configure -size small
     toolbar configure -size default

     toolbar configure -mode
     toolbar configure -mode iconlabel
     toolbar configure -mode icon
 	toolbar configure -mode label
 	toolbar configure -mode default

     toolbar configure -autoconfig 
     toolbar configure -autoconfig 1
     toolbar configure -autoconfig 0

     toolbar configure -lock 
     toolbar configure -lock 1
     toolbar configure -lock 0

     toolbar hide
     toolbar show

     set w "some window"
     toolbar hide -w $w
     toolbar show -w $w

     toolbar add -label "Query" -help "Call the query info dialog" -iconref "qery" -command tb::doquery

     toolbar add -label "Desktop" -help "kDesktopIcon" -iconref "desk" -command file::revealDesktop