On Windows systems, you can add buttons to a window, list, or tab set. Buttons are a standard way of enabling users to terminate input (OK and Cancel buttons are typical examples) or signify that any action should take place. Note the following:
- Every button must be part of a button set, and there can be only one button set per window, list, or tab set.
- A button can display either text or a graphic on its face. (See Toolkit button graphics for supported graphic formats.)
- When a button has focus, a thin dotted line surrounds the text portion of the button, and the button can be “pressed” using the spacebar or the Enter key. A button can be clicked with the mouse whether it has focus or not. You can use I_NEXT to move focus to a button.
- When a button is pressed or clicked, a method subroutine is invoked or a menu entry is signaled. If a menu entry is signaled, g_select is set to true, and g_entnam is set to the name of the button. (G_select and g_entnam, global variables defined in tools.def, are automatically set by Toolkit when a menu entry is signaled.)
- When in I_INPUT for a window or tab set, buttons are included in the container’s tabbing order. (This is not true of buttons in a list.) Tab moves forward and Shift+Tab moves backward through the buttons.
- The maximum number of buttons allowed in a container is 127. A fatal error occurs if this maximum is exceeded.
Except for %B_INFO, these button routines can be used only for buttons on a window or tab set. For buttons on a list, see L_BUTTON, L_BUTTONSET, and %L_BUTTONSTATE.
Creating buttons
To create buttons, use the .BUTTON script command or, to create them at runtime, use B_BUTTON, IB_BUTTON, or L_BUTTON.
- The .BUTTON script command creates buttons on windows.
- The B_BUTTON routine creates buttons on windows and tab sets at runtime. (You can use IB_BUTTON to create buttons on input windows at runtime, and you can use the DTS_BUTTON subfunction to %TS_TABSET to create buttons on tab sets at runtime, but B_BUTTON works for tab sets and all windows.)
- The L_BUTTON routine creates buttons on lists.
Defining button placement and the default button
You can define a button set’s location within a window (bottom or right), its justification, the maximum number of buttons per row or column, and the default button. To do this, use the .BUTTON_SET script command or, at runtime, use B_BUTTONSET, IB_BUTTONSET, or L_BUTTONSET. (To define a button’s location in the button set, use B_BUTTON.)
- Use the .BUTTON_SET script command for button sets on windows. For more information, see .BUTTON_SET.
- Use B_BUTTONSET for button sets on windows and tab sets. (Alternatively, you can use IB_BUTTONSET for button sets on input windows and the DTS_BUTTONSET subfunction to %TS_TABSET for button sets on tab sets, but B_BUTTONSET can be used in both of these situations.)
- Use L_BUTTONSET for button sets on lists.
You can use these routines to specify a default button, but the default won’t be applied unless you also pass E_STATE with the D_ON and D_RETURNBTN options. See the E_STATE Discussion for more information.
Enabling and disabling buttons
In general, the buttons for a window are enabled when the window is being processed, and they are disabled when the window is not being processed. (For details and exceptions, see the .BUTTON Discussion.)
To enable or disable a button, use %B_ENABLE and %B_DISABLE for buttons on windows and tab sets. Use %L_BUTTONSTATE for buttons on lists. For information on how buttons can be automatically enabled and disabled, see the .BUTTON Discussion.
Modifying and deleting buttons
To modify a button on a window or tab set, use the DSB_MODIFY subfunction of %B_BUTTON. For buttons on lists, use the DSB_MODIFY subfunction of %L_BUTTON.
To delete a button on a window or tab set, use the DSB_DELETE subfunction of %B_BUTTON. For buttons on lists, use the DSB_DELETE subfunction of %L_BUTTON.
Getting information on buttons
You can get information on buttons and button sets for a window, tab set, or list by using %B_INFO. This function has subfunctions that return the number of buttons, the index for the default button, the enabled state of a button, method information, and so forth. See %B_INFO.
