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:

basic toolbar creation and handling
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.

required arguments for all toolbars

name
SCO Visual Tcl widget name for the new toolbar.

attachment
widget above the toolbar to which the toolbar will be attached. This is typically the menu bar. This is required to support toolbar hiding.

icons
a Tcl list of full pathnames for icon pixmap files. This list is essentially a lookup table referred to by toolbar strings (see default and current) using a numerical index starting with 0.

commands
a Tcl list of lists where each list represents a command. This list is essentially a lookup table referred to by toolbar strings (see default and current) using a numerical index starting with 0.
Each command is a list of three elements:

key
unique name to distinguish the button from all others

callback
application callback to implement button task

text
point help textstring associated with the button

default
the default toolbar string. A toolbar string defines the set of icons and commands that constitute the toolbar. It is a list of lists where each list is a toolbar entity composed of two elements:

icon
numerical index into icons list.

command
numerical index into commands list.
Each command may appear only once in a toolbar string.
A special command index ``S'' may be used to represent a space versus a toolbar button. In this case, the icon index should be {}.
Optional arguments

shorthelpCB
non-default point help callback. Defaults to SaShortHelpCB.

visibility
boolean specifying current visibility: 1 = visibile. The application should first load the current value with SaToolbarLoad.
Arguments for customizable toolbars
current
currently configured (e.g. user configured) toolbar string. The application should first load the current value with SaToolbarLoad.

frame
currently configured (e.g. user configured) toolbar frame. The application should first load the current value with SaToolbarLoad.

sensitizeCB
application callback to reconfigure button sensitivity. When a user customizes the toolbar and adds a new button, its proper sensitivity is unknown. This callback is a request from the toolbar package to set proper sensitivity for such buttons. The application will typically use SaToolbarGetKeys and loop through the set of buttons configuring their sensitivity.
sensitizeCB must accept a callback structure (cbs).

customizeCB
Application callback invoked by the toolbar package at the beginning and the end of a customization session. This is useful for applications that may wish to suspend auto refresh callbacks or other automatic processing while the user interacts with the toolbar dialog.
customizeCB accepts two arguments: a boolean (1=enter, 0=exit) and a callback structure (cbs):
```
   proc customizeCB { state cbs }
```

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.