SaToolbar(3tlib)


SaToolbar: SaToolbar, SaToolbarButtonSetSensitive, SaToolbarGetKeys, SaToolbarMenuOptions, SaToolbarGet, SaToolbarLoad, SaToolbarStore -- SCO Visual Tcl interface for graphical toolbars

Synopsis

SaToolbar name attachment icons commands default [shorthelpCB] [visibility] [current] [frame] [sensitizeCB] [customizeCB]
SaToolbarButtonSetSensitive key state
SaToolbarGetKeys

SaToolbarMenuOptions menu options [shorthelpCB]
SaToolbarGet visibilityVar [currentVar] [frameVar]
SaToolbarLoad client visibilityVar [currentVar] [frameVar]
SaToolbarStore client visibilityVar [currentVar] [frameVar] [required]

Description

The SaToolbar interface enables applications to provide a user configurable graphical tool bar for quick access to commonly used tasks. Widely used in a number of graphical environments, a toolbar is a row of pushbuttons, labeled with icons, each of which duplicates a common task provided in the pulldown menus above. Each pushbutton may be supplemented with a brief point help text string providing a verbal explanation for the task.

If the toolbar configuration menu options are provided by the application, a user may hide the toolbar or customize its appearance by adding or deleting tool bar buttons and controlling the spacing between buttons for logical groupings. Toolbars need not be configurable, especially when they are simple, with few buttons, and without additional buttons that might be added at the user's discretion. Non-configurable toolbars will be referred to as static toolbars. Although a static toolbar itself may not change, the application should still allow the user to hide it.

The interfaces may be divided into two groups:

  1. basic toolbar creation and handling

  2. end-user Toolbar customization

Basic toolbar creation and handling


SaToolbar
creates a toolbar. SaToolbar arguments divide into two groups, those for basic static toolbars and an optional group used with customizable toolbars.

SaToolbarButtonSetSensitive
Like menu options and standard push buttons, applications will typically need to stipple certain toolbar buttons when tasks are unavailable, inappropriate, unauthorized, etc. SaToolbarButtonSetSensitive can set the sensitivity of the specified button to sensitive (1) or insensitive (0). When insensitive, a toolbar button is "stippled" or unavailable. Toolbar buttons are specified using a symbolic "key" as defined in the toolbar structure and returned by SaToolbarGetKeys.

Although the set of actual buttons or "keys" on a configurable toolbars can dynamically change, applications need not worry about whether the "key" refers to an actual button or whether the toolbar itself is visible. If the "key" does not map to an actual toolbar button, SaToolbarButtonSetSensitive simply returns.


SaToolbarGetKeys
returns a Tcl list of the current set of tool bar button keys. Since these can change for configurable toolbars, the list of keys may not be the same as those in the toolbar data structures.

Additional Interfaces for Customizable Toolbars


SaToolbarMenuOptions
attach standard toolbar menu options to application pulldown menu.

menu
specified application menu where options will be attached

options
list of one or more options

show/hide toggle

toolbar customization dialog option

shortHelpCB
non-standard point help callback. Default to SaShortHelpCB.

SaToolbarGet

SaToolbarLoad

SaToolbarStore
these three provide the interface for loading and storing the user customized visibility and toolbar so that changes persist across multiple invocations. They use SaScreenPolicy(3tlib).

The application may chose to deal only with visibility (showing and hiding the toolbar) in which case the current toolbar and its frametype can be omitted. Fully customizable toolbars require all arguments. For efficiency, all three toolbar components are passed by reference rather than value, so the variable names themselves are passed.


SaToolbarGet
loads the variables with current toolbar values in preparation for storing them. This must be called after the user's last opportunity to configure the toolbar and before the call to SaToolbarStore.

SaToolbarStore
stores the user's toolbar values until the application is used again. This is typically called from the application's exit procedure after the user's last opportunity to configure the toolbar. client is a string that uniquely identifies the application among all other SCOadmin applications. Must conform to the rules for Stanza section names.

SaToolbarLoad
loads the user's toolbar values from the previous store. This loads the values that may then be passed to SaToolbar. client is a string that uniquely identifies the application among all other SCOadmin applications. Must conform to the rules for Stanza section names.

Diagnostics

The Load and Store procedures may throw errors from the underlying SaScreenPolicy interfaces and should be handled with ErrorCatch.

References

SaScreenPolicy(3tlib).

Notices

Currently, SaToolbar supports only one toolbar per application.

All application callbacks are auto locked. See SCO Visual Tcl and -autoLock.

Graphical toolbars are only supported in the X environment. All SaToolbar procedures may be called under CHARM but have no effect. Applications need not use special case coding.


25 April 2004
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004