Create and manipulate a toolbar
|
WSupported on Windows
|
|
|
|
status = %TB_TOOLBAR(function, id, [orientation], [width][, height])
or
xcall TB_TOOLBAR(function, id, [orientation], [width][, height])
Return value
status
On Windows, the status of the operation: TB_SUCCESS (1) or TB_FAILURE (0). On Unix and OpenVMS, always returns false. (^VAL)
Arguments
function
The toolbar function to perform: (n)
Creates the toolbar. It does not display the toolbar on the application window. (To display the toolbar, use TB_PLACE.)
Deletes the toolbar.
Disables a toolbar.
Enables a disabled toolbar.
Places (shows) the toolbar.
Restores a previously saved state of the toolbar.
Saves the present state of the toolbar.
Removes (hides) the toolbar.
id
The toolbar identifier; the value of id is returned on TB_CREATE and passed on all other toolbar functions. (n)
orientation
(optional) The application window side where the toolbar will be placed: TBC_TOP (default), TBC_BOTTOM, TBC_LEFT, TBC_RIGHT. Used with TB_CREATE. (n)
width
(optional) Used with TB_CREATE. Width defines the width of the toolbar in pixels. If orientation is TBC_TOP or TBC_BOTTOM, this argument is optional and ignored since the toolbar will be created the full width of the window. (n)
height
(optional) Used with TB_CREATE. Height defines the height of the toolbar in pixels. If orientation is TBC_LEFT or TBC_RIGHT, this argument is optional, ignored, and defaults to the full height of the window. (n)
Discussion
%TB_TOOLBAR enables you to create and manipulate an application-window toolbar. You must include the file WND:toolbar.def to use this function.
TB_CREATE creates a toolbar, but does not display it on the application window or assign it to an environment. To display the toolbar, use TB_PLACE. To create a toolbar and assign it to an environment, use %TB_TKCREATE. (You can also use TB_TKLOG to assign a toolbar to an environment if you create it with TB_TOOLBAR.)
TB_DELETE deletes a toolbar that’s not assigned to an environment. If a toolbar is assigned to an environment, use TB_TKDEL; if you use TB_DELETE, a fatal error will occur on the next call to E_ENTER or E_EXIT.
You can place up to four toolbars per application window: one at the top, left, right, and bottom of the window. (You can create up to 256 toolbars per application.) The toolbars will be displayed in the order in which they were placed (with TB_PLACE). When placed, the toolbars will blank out the entire width (or height) of that area of the screen. If you place a toolbar on a side where another toolbar is already placed, the original toolbar is removed, though if it’s logged with Toolkit, a subsequent call to E_EXIT could remove the new toolbar and replace it with the original.
If TB_DISABLE is passed, the toolbar remains on the screen, but nothing happens if a button is selected. Disabling a toolbar disables all of its buttons.
TB_PUSHSTATE saves the current state of a Toolbar by pushing it onto a stack, enabling you to save a state, make changes to it, and then restore it with TB_POPSTATE. The stack follows normal last-on, first-off behavior; the only limit to the size of the stack is available memory. If you pass TB_POPSTATE and there’s no saved state for the toolbar, status will be TB_FAILURE, and nothing will happen to the toolbar. TB_PUSHSTATE and TB_POPSTATE may be used for toolbars created with %TB_TOOLBAR. We do not recommend using them for toolbars that are under environment control, as it may confuse Toolkit.
Examples
See the %TB_BUTTON Examples.
