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:

built-in toolbar items provided by the application. They are identified by a symbolic name. See the Built-in and standard toolbar items section below.
toolbar items created programmatically with the [toolbarItem create] command. They are identified by a unique token attributed when they are created. These items work as ordinary clickable toolbar buttons.

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:

Name	Value
Standard	0
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 simple 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.
In the case of a toolbar item which is not a simple button but contains a view (specified with the -view option), one must use the view's -command option instead. In other words, the Tcl proc must be attached to the view and not to 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.
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:

Name	Description
flexible	a flexible space item
space	a 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.

Examples

See examples of toolbar items in the file toolbar.tcl. For instance:

toolbarItem create Desktop doctoolbar \
  -label "Desktop" -palette "Desktop" \
  -help "Show Desktop Folder in Finder" \
  -image [imageRef create -type "desk"] \
  -command {toolbar::showDesktop}

This commands creates a new toolbar item in the built-in document toolbar. Its token (returned by this command) is doctoolbar.Desktop.

Last updated 2019-10-17 13:29:36