The toolbar routines enable you to create and manipulate an application window toolbar. The toolbar is a variable-size rectangle containing buttons that the user can select with a mouse. Toolbars are used as extensions to—or replacements for—the menu bar, providing an alternative method for invoking functions within an application. Toolbars are supported only on Windows.
Horizontal toolbars occlude the entire width of the top or bottom of the application window. Similarly, vertical toolbars blank out the entire vertical area of the application window on the specified side. Toolbars are sized to the full extent of the application window with respect to the border where they are defined.
A toolbar button can display either text or a graphic. See Toolkit button graphics for more information. You can apply 3-D borders to toolbar buttons by setting the SYN_3D_TOOLBAR environment variable to 1.
Selecting a toolbar button can trigger the simulation of one or more characters pressed on the keyboard, or it can invoke an entire subroutine. A common approach is to have a function key invoke a particular action such as Find, Select, Page Up, and so forth. It’s also common to use %M_SIGNAL as the button method to signal the name of the button as a menu entry. Toolbar button actions are specified at runtime when the button is loaded onto the toolbar.
A special type of button, the numeric bar, contains the numbers 0 through 9. To load the numeric bar, pass “#NUMBER”, a special reserved name, to %TB_BUTTON.
Toolbars and toolbar buttons can be managed by Toolkit’s environment control. There are two ways to do this: creating the toolbar with %TB_TKCREATE, or create the toolbar with %TB_TOOLBAR and then use %TB_TKLOG to log the toolbar with Toolkit. When you log a toolbar with an environment, the following are controlled by the environment:
- Deletion of the toolbar when its environment is exited
- Placement of the toolbar
- The state of toolbar buttons, including enablement and forced-down state. Toolbar buttons created in an environment will be deleted when the environment is exited, but no button deleted in an environment will be restored when that environment is exited.
When using toolbars, you must use Toolkit environment processing consistently or not at all. Once a toolbar has been logged with Toolkit, you must leave the management of the toolbar to Toolkit, and you must use TB_TKDEL to explicitly delete the toolbar.
You may use TB_PUSHSTATE and TB_POPSTATE when you create a toolbar with %TB_TOOLBAR, but we recommend that you don’t use them for toolbars that are under environment control, as it may confuse Toolkit.
