SaToolbar(TCL_ADM)
SaToolbar: SaToolbar, SaToolbarButtonSetSensitive, SaToolbarGetKeys, SaToolbarMenuOptions, SaToolbarGet, SaToolbarLoad, SaToolbarStore --
SCO Visual Tcl interface for graphical toolbars
Syntax
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(TCL_ADM).
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.
Errors
The Load and Store procedures may throw errors from the underlying
SaScreenPolicy interfaces and should be handled with
ErrorCatch.
Limitations
Currently, SaToolbar supports only one toolbar per application.
Notes
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.
See also
SaScreenPolicy(TCL_ADM),
SCO Visual Tcl Programmer's Guide and Reference in SCO Visual Tcl Programmer's Guide and Reference.
16 September 2002
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003