From AlphaWiki

Commands: ToolbarCommand

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


Introduction

The [toolbar] command lets you interact with the toolbar located at the top of the document windows. It is possible to modify the attributes 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.

There are two kinds of toolbar items:

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

Synopsis

The formal syntax of the [toolbar] command is:

toolbar subcommand ?options?

The possible subcommands are described below. Depending on the 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.

The [add] subcommand

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.

The general syntax of this subcommand is:

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

Here is the meaning of the possible options:

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

The [configure] subcommand

There are two forms for the syntax of this subcommand:

toolbar configure ?-bar toolbarToken? option

toolbar configure ?-bar toolbarToken? 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 [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 [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 ?-bar toolbarToken?

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...?

Here is the meaning of the possible options:

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 [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

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

toolbar delete itemToken

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].

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

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 frontmost document window. If there is no window, the command returns silently.

The [index] subcommand

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

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

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

If the item designated by itemToken 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.

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

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

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)? ?-allowed list? ?-default list?

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:

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.

The [present] subcommand

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

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 custom items. The item could have been removed from the toolbar programmatically with the [toolbar remove] command, or manually by the user.

The [remove] subcommand

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

toolbar remove itemToken ?-bar toolbarToken?

toolbar remove -index num ?-bar toolbarToken?

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.

Note that this command will remove an item from the toolbor even if 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 [toolbar search] command lets you get or set the value of certain properties of the Search Field toolbar item.

There are two forms for the syntax of this subcommand:

toolbar search option

toolbar search 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 various options.

Here is the description of the currently available options:

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 itemToken ?-w win? ?-bar toolbarToken? option

toolbar set itemToken ?-w win? ?-bar toolbarToken? 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 -canRemove 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 -command and the -icon options cannot be set on built-in items.

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:

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

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 frontmost document window. If there is no window, the command returns silently.

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 frontmost document window. If the window does not have a toolbar or if no window is open, the command returns 0.

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

The AlphaX application provides several useful 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:

NameDescription
browsesegmented button with left and right arrow
customizebutton to display the toolbar customization dialog
encodingthe Encodings popup menu
fileinfothe File Info popup menu
flexibleflexible space item
fontsstandard Fonts floating window
modeinfothe Modes popup menu
printthe Print button
searchthe Search field
separatorvertical separator item
spacespace item

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

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.

Generic Finder iconsCode
Clipboard Icon'CLIP'
Desktop Icon'desk'
Finder Icon'FNDR'
Computer Icon'root'
Font Suitcase Icon'FFIL'
Full Trash Icon'ftrh'
Generic Application Icon'APPL'
Generic CDROM Icon'cddr'
Generic Control Panel Icon'APPC'
Generic Document Icon'docu'
Generic Edition File Icon'edtf'
Generic Extension Icon'INIT'
Generic File Server Icon'srvr'
Generic Font Icon'ffil'
Generic Hard Disk Icon'hdsk'
Generic Removable Media Icon'rmov'
Generic Preferences Icon'pref'
Generic Query Document Icon'qery'
Generic RAM Disk Icon'ramd'
Generic Shared Libary Icon'shlb'
Generic Stationery Icon'sdoc'
Generic Suitcase Icon'suit'
Generic URL Icon'gurl'
International Resources Icon'ifil'
Keyboard Layout Icon'kfil'
Sound File Icon'sfil'
System Suitcase Icon'zsys'
Trash Icon'trsh'
True Type Font Icon'tfil'
Internet locationsCode
Internet Location Generic Icon'ilge'
Internet Location HTTP Icon'ilht'
Internet Location FTP Icon'ilft'
Internet Location File Icon'ilfi'
Internet Location Mail Icon'ilma'
Internet Location News Icon'ilnw'
FoldersCode
Generic Folder Icon'fldr'
Drop Folder Icon'dbox'
Mounted Folder Icon'mntd'
Open Folder Icon'ofld'
Owned Folder Icon'ownd'
Private Folder Icon'prvf'
Shared Folder Icon'shfl'
Users and Groups iconsCode
User Folder Icon'ufld'
Workgroup Folder Icon'wfld'
Guest User Icon'gusr'
User Icon'user'
Owner Icon'susr'
Group Icon'grup'
Special foldersCode
Applications Folder Icon'apps'
Application Support Folder Icon'asup'
Color Sync Folder Icon'prof'
Contextual Menu Items Folder Icon'cmnu'
Documents Folder Icon'docs'
Extensions Folder Icon'extn'
Favorites Folder Icon'favs'
Fonts Folder Icon'font'
Public Folder Icon'pubf'
Recent Documents Folder Icon'rdoc'
System Folder Icon'macs'
Alert iconsCode
Alert Note Icon'note'
Alert Caution Icon'caut'
Alert Stop Icon'stop'
MiscellaneousCode
Apple Logo Icon'capl'
Apple Menu Icon'sapl'
Backward Arrow Icon'baro'
Forward Arrow Icon'faro'
Grid Icon'grid'
Help Icon'help'
Locked Icon'lock'
No Files Icon'nfil'
No Folder Icon'nfld'
No Write Icon'nwrt'
Recent Items Icon'rcnt'
Shortcut Icon'shrt'
Unlocked Icon'ulck'
Connect To Icon'cnct'
Generic Window Icon'gwin'
Question Mark Icon'ques'
Eject Media Icon'ejec'
Burning Icon'burn'
Right Container Arrow Icon'rcar'

Attaching a toolbar

Since version 8.2b8 of AlphaX, the [new] and the [openFile] core commands support a -bar 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 -bar 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

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 -locked 
     toolbar configure -locked 1
     toolbar configure -locked 0

     toolbar hide
     toolbar show

     set w "some window"
     toolbar hide -w $w
     toolbar show -w $w
     toolbar customize -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. 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" -bar $tbar

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

 
     edit -bar $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

Retrieved from http://alphatcl.sourceforge.net/wiki/pmwiki.php/Commands/ToolbarCommand
Page last modified on February 05, 2009, at 01:45 PM