The [toolbar] command.

Introduction

The toolbar command lets you create and manage toolbars located at the top of document windows. It is possible to modify the attributes of a toolbar, to show or hide it, to modify its contents by adding or removing items, etc.
Alpha defines a default toolbar for document windows but it is also possible, with the [toolbar create] command, to create new toolbars and attach them to some windows instead of the default toolbar.
Alpha provides some predefined toolbar items (print, fonts, colors etc.) but new custom items can be created. See the [toolbarItem] command.

Synopsis

The formal syntax of the [toolbar] command is:

toolbar subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.
All the toolbars and 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 toolbar token or a toolbar item token.

The [attach] subcommand

This subcommand attaches a toolbar to a window. The complete syntax is:

    toolbar attach bartoken (-w win | -root token)

The toolbar can be attached either to a document window specified by the -w argument or to a window created with the [view root] command and specified by its view token. The -w and -root options are mutually exclusive.
One can also attach a toolbar to a document window created with the [openWindow] or the [openFile] commands using their -bar argument.

The [configure] subcommand

This subcommand is used to get or set properties of a toolbar. The complete syntax is:

    toolbar configure bartoken option ?value (option value)*?

One must specify a valid toolbar token. The available options are described in the Toolbar options section.
The standard toolbar items cannot be configured (see the Built-in and standard toolbar items section).
Note that the settings made with this command concern the toolbar considered as a template: the individual toolbars contained in the document windows are copies of this template. This means that some changes may apply only to future toolbars. To modify properties of an already existing toolbar instance, use the [toolbar set] command.

The [count] subcommand

This subcommand returns the number of items in the toolbar. The complete syntax is:

    toolbar count ?-w win?

The -w option indicates the window in which you want to count the items. If it is not specified, the command applies to the frontmost document window. It raises an error if no document window is opened or if the window does not have a toolbar.

The [create] subcommand

This subcommand is used to create a new toolbar. The complete syntax is:

    toolbar create name ?(option value)*?

The name argument must be a unique name which is used to identify the newly created object. This name is used as a token for the toolbar in other commands.
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 [toolbar configure] command: see the Toolbar options section.

The [customize] subcommand

This subcommand is used to display the customization palette. The complete syntax is:

    toolbar customize ?-w win?

The -w option tells the window you want the toolbar palette to be attached to. If it is not specified, the command applies to the frontmost document window. It raises an error if no document window is opened or if the window does not have a toolbar.

The [delete] subcommand

This subcommand is used to delete a toolbar template previously defined with [toolbar create]. The syntax is:

    toolbar delete bartoken

The built-in document window toolbar cannot be deleted.

The [detach] subcommand

This subcommand detaches a toolbar from a window. The complete syntax is:

    toolbar detach (-w win | -root token)

The toolbar can be detached either from a document window specified by the -w argument, or from a window created with the [view root] command and specified by its view token. The -w and -root options are mutually exclusive.

The [insert] subcommand

This subcommand is used to insert a toolbar item in a given toolbar. The complete syntax is:

    toolbar insert ?-w win? tbitoken ?index?

The index argument can be used to specify the position of the item in the toolbar. If it is not specified, the default value is 0 which designates the leftmost item in the toolbar.
Note that this also inserts the item in all the toolbars that share the same token. The system assumes all toolbars with the same identifier are the same, and automatically synchronizes changes.

The [items] subcommand

This subcommand returns the items present in a window's toolbar. The complete syntax is:

    toolbar items ?-w win?

The returned value is a list of tokens of all the items present in the toolbar of the window specified with the -w option. If -w is not specified, it applies to the frontmost document window. The items are returned in the left to right order. The command raises an error if no document window is opened or if the window does not have a toolbar.

The [list] subcommand

This subcommand returns a list of tokens. The syntax is:

    toolbar list

The returned value is a list of all the currently defined toolbar tokens.

The [remove] subcommand

This subcommand is used to remove an item from a window's toolbar. The syntax is:

    toolbar remove ?-w win? index

The item to remove is designated by its index. The index is 0-based: the leftmost item is at index 0. If -w is not specified, the command applies to the frontmost document window. It raises an error if no document window is opened or if the window does not have a toolbar. It also raises an error if the index is out of bounds.
Note that this also removes the item from all the toolbars that share the same token. The system assumes all toolbars with the same identifier are the same, and automatically synchronizes changes.
A toolbar item can also be removed manually by dragging it out of the toolbar with the command key (⌘) pressed, provided the toolbar is not locked.

The [set] subcommand

This subcommand is used to get or set toolbar properties for a specific window. The complete syntax is:

    toolbar set ?-w win? option ?value (option value)*?

The available options are described in the Toolbar options section but the -allowed and -default options concern the toolbar template defined with [toolbar create] and can only be modified via the [toolbar configure] command.

Toolbar options

The following options can be used when a toolbar token is specified:

-allowed: this is a list of the toolbar item tokens which are allowed to be inserted in the toolbar. It specifies the contents and the order of the items in the configuration palette. Every allowed item must be explicitly listed, even the standard ones. This list should include all the items specified with the -default option. If this option is empty, Alpha allows all the currently defined items.
-autosave: when this option is enabled, the toolbar settings are automatically written to user defaults if the toolbar configuration changes.
-default: this is a list of toolbar item tokens specifying the contents and the order of the items which constitute the default toolbar configuration.
-locked: if the toolbar is locked, then the Customize Toolbar... menu item is disabled and it is not possible to modify the toolbar. The default value for this option is 0.
-mode: this option is a numeric value specifying the display mode of the toolbar. See the possible values below.
-selected: this option specifies the token of the currently selected item. Pass an empty string in order to deselect all the items.
-showSeparator: this option is a boolean value specifying whether the toolbar draws a separator between the toolbar and the main window contents. The default value is 1.
-size: this option is a numeric value specifying the size mode of the toolbar. See the possible values below.
-visible: this option is a boolean value specifying whether the toolbar is visible or not. The default value is 1.

The possible values for the -mode option are:

Name	Value
Default	0
Icon And Label	1
Icon Only	2
Label Only	3

The possible values for the -size option are:

Name	Value
Default	0
Regular	1
Small	2

Built-in toolbar

There is a default toolbar built by the application and used, by default, by the document windows. This toolbar is designated by the token doctoolbar. It is built-in and cannot be deleted by the [toolbar delete] command. Note that it is possible to attach another toolbar to document windows as explained in the next section.

Attaching a toolbar

The [openWindow] and the [openFile] core commands defined by Alpha 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 built-in toolbar defined by Alpha, unless there is an -attr option containing the No Toolbar attribute (see the Window Attributes page in the Alpha Manual).

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