|
WikiDoc |
The [toolbar] commandnoletocadom
IntroductionThe [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. 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. There are two kinds of toolbar items:
Both kinds of toolbar items can be added to or removed from the toolbar. SynopsisThe 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 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] subcommandThis 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 token ?-index value? Possible options are:
The [toolbar add] command applies to both built-in items and custom items. The [configure] subcommandThere 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 [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] subcommandThis command returns the number of items currently installed in the toolbar, including spaces, flexible spaces and separators. The syntax is: toolbar count The [create] subcommandThis 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:
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] subcommandThis 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]. Built-in toolbar items cannot be deleted with [toolbar delete]. The [hide] subcommandThis 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 [index] subcommandThis 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] subcommandThis 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. 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] subcommandThis 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] subcommandThis command removes an item inserted in the toolbar. The syntax has two forms: toolbar remove token 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. 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. The [search] subcommandThe [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] subcommandThe [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] subcommandThis 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. The [visible] subcommandThis 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 itemsThe 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 codesThe -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 codesThere 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 IconrefCommand page on this wiki. Predefined codesThe 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.
ExamplesHere 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 -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. |
|
Edit -
History -
Print -
Recent Changes -
Search
Page last modified on November 04, 2007, at 09:52 PM
|
Hosted on
|