Reference Guide > W Routines > WwToolBox Function
  

WwToolBox Function
Creates an array of graphic buttons (icons).
Usage
toolb = WwToolBox(parent, labels, callback)
Input Parameters
parent — The widget ID of the parent widget.
labels — A string array of icon file names.
callback — A string containing the name of the callback routine that is executed when a button is selected.
Returned Value
toolb — The ID of the tool box widget. If only one button is requested, that button’s widget ID is returned.
Input Keywords
Border — Specifies the width in pixels of the tool box and icon borders. The default is 0.
Center — An array specifying the position of the left and right edge of buttons as a percentage of tool box width. By default, buttons are spaced evenly in the box.
Form — When present and nonzero, buttons are placed in a form layout and all specified attachment keywords are honored (i.e., /Left, /Right, /Top, /Bottom). By default, buttons are placed in a row/column layout.
Horizontal — When present and nonzero, creates a horizontally aligned row of buttons (the default).
Layout_name — Names the Form widget (if Form is specified), or the RowColumn widget (if Horizontal or Vertical is specified). (Default: tools)
Measure — If you create a horizontal box, then measure specifies the number of rows into which the buttons will be divided. For a vertical box, this keyword specifies the number of columns in which to divide the buttons.
Nofmany — Used in conjunction with the Radio keyword. If nonzero, creates nonexclusive radio buttons where any number of buttons can be selected at once.
Oneofmany — Used in conjunction with the Radio keyword. If nonzero, creates exclusive radio buttons where only one button can be selected at a time. (Refer to the note regarding the callback input parameter in the Discussion section for more information on using Oneofmany.)
Position — If the tool box widget is to be placed in a bulletin board layout, use this keyword to specify the x, y coordinates of the tool box widget within the bulletin board.
Radio — If nonzero, uses radio (toggle) buttons. (Default: push buttons.)
ShadowThickness — (UNIX only) If specified and nonzero, sets the shadow thickness of the button in pixels. (Default: 2)
Spacing — Specifies the space in pixels between buttons. The default is 0.
Tab_WinOff — (Windows only) If this keyword is present and nonzero, the tab navigation feature is turned off for this widget.
Vertical — If nonzero, creates a vertically aligned column of buttons.
Output Keywords
Tools — Returns an array of graphical button (icon) widget IDs.
Color/Font Keywords
Background — Specifies the background color name.
Basecolor — Specifies the base color.
Font — Specifies the name of the font used for button text.
MSFont — Adds support for Windows fonts.
Foreground — Specifies the foreground color name.
Attachment Keywords
Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the tool box widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the tool box widget is attached to the bottom of the parent widget.
Left — If a widget ID is specified (for example, Left=wid), then the left side of the tool box widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the tool box widget is attached to the left side of the parent widget.
Right — If a widget ID is specified (for example, Right=wid), then the right side of the tool box widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the tool box widget is attached to the right side of the parent widget.
Top — If a widget ID is specified (for example, Top=wid), then the top of the tool box widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the tool box widget is attached to the top of the parent widget.
Get/Set Value
getvalue — Icon (pixmap) ID.
setvalue — The icon file name.
Callback Parameters
Any toolbox callback procedure must have these parameters:
wid — Button widget ID.
index — Index of the button pushed (1 – n).
Discussion
This function creates a box containing iconic buttons arranged in rows and/or columns. If you only create a single button, then the box widget is not created — only the button widget is created.
 
note
The callback procedure is called twice if the Oneofmany keyword is specified. It is called once when the previously selected button is deselected and again for the newly selected button. Use WwGetValue to determine if a button is currently selected or deselected.
Example
This example creates a box containing graphical buttons (a toolbox). The callback routine, PickedCB, is executed when one of the toolbox buttons is selected.
Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt (or enter them in a command file and run them with the @ command. To dismiss the tool box, select the appropriate function (such as Close) from the window manager menu.
Callback Procedure
PRO PickedCB, wid, which
   CASE which OF
      1: PRINT,'Search Selected'
      2: PRINT,'Toc Selected'
      3: PRINT,'Topics Selected'
      4: PRINT,'Quit Selected'
   ENDCASE
END
Widget Commands
top = WwInit('ww_ex37', 'Examples', layout, height=300, $
   width=600)
pixmaps = [GETENV('WAVE_DIR')+ $
   '/xres/wxpm_btn_help_search', GETENV('WAVE_DIR')+ $
   '/xres/wxpm_btn_help_toc', GETENV('WAVE_DIR')+ $
   '/xres/wxpm_btn_help_topics', GETENV('WAVE_DIR')+ $
   '/xres/wxpm_btn_help_quit']
dbox = WwToolBox(layout, pixmaps, 'PickedCB', /Vertical, $
   Spacing=20, Measure=2)
status = WwSetValue(top, /Display)
WwLoop
 
note
In the preceding code, you must change the icon names as follows: change wxpm to wxbm and add the extension .bmp. For example, change wxpm_btn_help_search to wxbm_btn_help_search.bmp.
See Also
For detailed information on GUI development, refer to the PV‑WAVE Application Developer’s Guide.
For more information about how to write an application program based on PV‑WAVE Widgets, refer to Using Wave Widgets in the PV‑WAVE Application Developer’s Guide.
For additional information on the color and font keywords, see "Setting Colors and Fonts" in the PV‑WAVE Application Developer’s Guide.
For additional information on attachment keywords, see "Form Layout: Attachments" in the PV‑WAVE Application Developer’s Guide.
For information on Get and Set values, see "Setting and Getting Widget Values" in the PV‑WAVE Application Developer’s Guide.

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.