29.4 Specifying the Toolbar

In order to specify the contents of a toolbar, set one of the specifier variables default-toolbar, top-toolbar, bottom-toolbar, left-toolbar, or right-toolbar. These are specifiers, which means you set them with set-specifier and query them with specifier-specs or specifier-instance. You will get an error if you try to set them using setq. The valid instantiators for these specifiers are toolbar descriptors, as described above. See Specifiers, for more information.

Most of the time, you will set default-toolbar, which allows the user to choose where the toolbar should go.

Specifier: default-toolbar

The position of this toolbar is specified in the function default-toolbar-position. If the corresponding position-specific toolbar (e.g. top-toolbar if default-toolbar-position is top) does not specify a toolbar in a particular domain, then the value of default-toolbar in that domain, of any, will be used instead.

Note that the toolbar at any particular position will not be displayed unless its thickness (width or height, depending on orientation) is non-zero and its visibility status is true. The thickness is controlled by the specifiers top-toolbar-height, bottom-toolbar-height, left-toolbar-width, and right-toolbar-width, and the visibility status is controlled by the specifiers top-toolbar-visible-p, bottom-toolbar-visible-p, left-toolbar-visible-p, and right-toolbar-visible-p (see Other Toolbar Variables).

Function: set-default-toolbar-position position

This function sets the position that the default-toolbar will be displayed at. Valid positions are the symbols top, bottom, left and right. What this actually does is set the fallback specifier for the position-specific specifier corresponding to the given position to default-toolbar, and set the fallbacks for the other position-specific specifiers to nil. It also does the same thing for the position-specific thickness and visibility specifiers, which inherit from one of default-toolbar-height or default-toolbar-width, and from default-toolbar-visible-p, respectively (see Other Toolbar Variables).

Function: default-toolbar-position

This function returns the position that the default-toolbar will be displayed at.

You can also explicitly set a toolbar at a particular position. When redisplay determines what to display at a particular position in a particular domain (i.e. window), it first consults the position-specific toolbar. If that does not yield a toolbar descriptor, the default-toolbar is consulted if default-toolbar-position indicates this position.

Specifier: top-toolbar

Specifier for the toolbar at the top of the frame.

Specifier: bottom-toolbar

Specifier for the toolbar at the bottom of the frame.

Specifier: left-toolbar

Specifier for the toolbar at the left edge of the frame.

Specifier: right-toolbar

Specifier for the toolbar at the right edge of the frame.

Function: toolbar-specifier-p object

This function returns non-nil if object is a toolbar specifier. Toolbar specifiers are the actual objects contained in the toolbar variables described above, and their valid instantiators are toolbar descriptors (see Toolbar Descriptor Format).