The [toolbarItem] command.

Introduction

The toolbarItem command lets you create and manage toolbar items. It is possible to modify the definition or the attributes of a toolbar item. Different options let you customize the appearance of an item (label, icon, help string) and the Tcl proc executed when the item is clicked. You can also attach to a toolbar item a view created with the [view] command. For operations concerning toolbars, see the [toolbar] command.
Alpha provides some predefined toolbar items (print, fonts, colors etc.) but the toolbarItem command makes it possible to create new custom items that can later be inserted in a toolbar.
There are two kinds of toolbar items:

Synopsis

The formal syntax of the [toolbarItem] command is:
toolbarItem subcommand ?options?
The possible subcommands are described below. Depending on the subcommand, some options may be specified.
The toolbar items are identified by a unique token. In the case of a built-in toolbar item, the token is identical to the symbolic name of the item.
The documentation of the commands syntax, in the next sections, uses the terms bartoken and tbitoken to designate respectively a toobar token or a toolbar item token.

The [configure] subcommand

This subcommand is used to get or set properties of a toolbar item. The complete syntax is:
    toolbarItem configure tbitoken option ?value (option value)*?
One must specify a valid toolbar item token obtained via the
[toolbarItem create] command. For the available options, see the Toolbar item options section.
Note that the standard toolbar items cannot be configured with this subcommand (see the Built-in and standard toolbar items section).

The [create] subcommand

This subcommand is used to create a new toolbar item template for a given toolbar. The complete syntax is:
    toolbarItem create name bartoken ?(option value)*?
The name argument is a string to uniquely identify the newly created object for the specified toolbar. This object is considered as a template: each time the system needs to insert this toolbar item in a toolbar (or in the customization palette), it makes a copy of the template.
The bartoken argument specifies the toolbar the item belongs to: a toolbar item can only be in one toolbar. The command returns a token which is built using the name argument and the toolbar token and is used by other subcommands.
The command can also contain option/value pairs to set some properties of the new object. The possible options are the same as with the
[toolbarItem configure] command: see the Toolbar item options section.

The [delete] subcommand

This subcommand is used to delete a toolbar item template created with [toolbarItem create]. The syntax is:
    toolbarItem delete tbitoken
The built-in document window toolbar cannot be deleted. Built-in and standard toolbar items cannot be deleted either.

The [list] subcommand

This subcommand returns a list of tokens. The complete syntax is:
    toolbarItem list
The returned value is a list of all the currently defined toolbar item tokens.

The [set] subcommand

This subcommand is used to get or set toolbar item properties for a specific window. The complete syntax is:
    toolbarItem set ?-w win? index option ?value (option value)*?
The available options are described in the
Toolbar item options section.

Toolbar item options

The following options are supported to set the properties of a toolbar item token:
-command
this option is used to set the name of the Tcl proc which is executed when the item is clicked. Passing an empty string removes the command associated with the toolbar item. See the Toolbar items action section below for more information about how these commands work.
-duplicate
this option is a boolean value specifying whether the item can have multiple instances in the toolbar. The default value is 0.
-enabled
this option is a boolean value specifying whether the item is enabled. The default value is 1.
-help
this option sets the help string displayed when the mouse hovers over the item.
-image
this option specifies an image attached to the toolbar item. The value is an image token obtained with the [imageRef create] command.
-label
this option specifies the label which normally appears in the toolbar (when it is in Text or Icon&Text mode) and in the overflow menu.
-max
this option specifies the maximum size occupied by the toolbar item. The value is a two elements list containing the width and the height dimensions.
-menu
this option specifies a default menu form representation for the toolbar item. The value is a menu token obtained with the [menuRef create] command.
-min
this option specifies the minimum size occupied by the toolbar item. The value is a two elements list containing the width and the height dimensions.
-palette
this option specifies the label that appears when the receiver is in the customization palette.
-priority
this option is a numeric value specifying the visibility priority for the toolbar item. See the possible values below. The default value is 0.
-tag
this option defines a numeric value attached to the toolbar item. It can be useful for identification purpose.
-view
this option specifies a view attached to the toolbar item. The value is a view token obtained with the [view create] command.

The possible values for the -priority option are:
NameValue
Standard0
Low -1000
High 1000
User 2000
Items with low priority are the first items to be pushed to the overflow menu. Items with high priority are less inclined to be pushed to the overflow menu. Items with user priority are the last to be pushed to the overflow menu.

Toolbar items action

An action can be associated with a toolbar item using the -command option. The value of this option is the name of a Tcl proc which is executed when the item is clicked. When this Tcl proc is invoked, the token of the toolbar item is appended to the arguments. For instance, suppose you define a new toolbar item and you declare a command like this:
    set bartoken [toolbar new]
    set tbitoken [toolbar item foo $bartoken]
    toolbarItem configure $tbitoken -command myTbiProc
Then the prototype of the proc myTbiProc must be
    proc myTbiProc {token} {
       # your code here
    }
and the value of the token argument is the token of the toolbar item.

Built-in and standard toolbar items

There is a default toolbar built by the application and used by the document windows. This toolbar can be designated by the token doctoolbar. It is built-in and cannot be deleted by the [toolbar delete] command. This toolbar has built-in toolbar items also provided by the application. They have a symbolic name to use in place of the tbitoken argument expected by toolbar subcommands. Here is the list of the built-in names:
NameDescription
fileinfothe File Info popup menu
modeinfothe Modes popup menu

Alpha also gives access to several useful toolbar items defined by the Cocoa framework. They are referred to as standard toolbar items because they are not created programmatically with the [toolbarItem create] command. They all have a symbolic name to use in place of the tbitoken argument expected by some [toolbar] subcommands. Here is the list of symbolic names:
NameDescription
colorsthe colors selection palette
flexiblea flexible space item
fontsthe standard Fonts floating window
printthe print button
spacea space item
The standard toolbar items are available for all the toolbars. They cannot be configured with the [toolbarItem configure] or [toolbarItem set] commands, nor deleted with the [toolbarItem delete] command.

Last updated 2017-02-12 12:05:37