The CW_BGROUP function creates a widget base of buttons. It handles the details of creating the proper base (standard, exclusive, or non-exclusive) and filling in the desired buttons. Events for the individual buttons are handled transparently, and a CW_BGROUP event returned. This event can return any one of the following:
Only buttons with textual names are handled by this widget. Bitmaps are not understood.
This routine is written in the IDL language. Its source code can be found in the file cw_bgroup.pro in the lib subdirectory of the IDL distribution.
Result = CW_BGROUP( Parent, Names [, BUTTON_UVALUE=array] [, COLUMN=value] [, EVENT_FUNC=string] [{, /EXCLUSIVE | , /NONEXCLUSIVE} | [, SPACE=pixels] [, XPAD=pixels] [, YPAD=pixels]] [, FONT=font] [, FRAME=width] [, IDS=variable] [, /LABEL_LEFT=string | , /LABEL_TOP=string] [, /MAP] [, /NO_RELEASE] [, /RETURN_ID | , /RETURN_INDEX | , /RETURN_NAME] [, ROW=value] [, /SCROLL] [, X_SCROLL_SIZE=width] [, Y_SCROLL_SIZE=height] [, SET_VALUE=value] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, XSIZE=width] [, YOFFSET=value] [, YSIZE=value] )
This function returns the widget ID of the newly-created button group widget.
The widget ID of the parent widget.
A string array, one string per button, giving the name of each button.
An array of user values to be associated with each button and returned in the event structure. If this keyword is set, the user values are always returned, even if the any of the RETURN_ID, RETURN_INDEX, or RETURN_NAME keywords are set.
Buttons will be arranged in the number of columns specified by this keyword.
A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. This function is called with the return value structure whenever a button is pressed, and follows the conventions for user-written event functions.
Set this keyword to cause buttons to be placed in an exclusive base, in which only one button can be selected at a time.
The name of the font to be used for the button titles. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows systems). See About Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.
Specifies the width of the frame to be drawn around the base.
A named variable in which the button IDs will be stored, as a longword vector.
Set this keyword to a string creating a text label to the left of the buttons.
Set this keyword to a string creating a text label above the buttons.
Set this keyword to cause the base to be mapped when the widget is realized (the default).
Set this keyword to cause buttons to be placed in an non-exclusive base, in which any number of buttons can be selected at once.
If set, button release events will not be returned.
Set this keyword to return the widget ID of the button in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set.
Set this keyword to return the zero-based index of the button within the base in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set. THIS IS THE DEFAULT.
Set this keyword to return the name of the button within the base in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set.
Buttons will be arranged in the number of rows specified by this keyword.
If set, the base will include scroll bars to allow viewing a large base through a smaller viewport.
Allows changing the current state of toggle buttons (i.e., exclusive and nonexclusive groups of buttons). The behavior of SET_VALUE differs between EXCLUSIVE and NONEXCLUSIVE CW_BGROUP widgets. With EXCLUSIVE CW_BGROUP widgets, the argument to SET_VALUE is the id of the widget to be turned on. With NONEXCLUSIVE CW_BGROUP widgets the argument to SET_VALUE should be an array of on/off flags for the array of buttons.
The space, in pixels, to be left around the edges of a row or column major base.
Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
The "user value" to be assigned to the widget.
The X offset of the widget relative to its parent.
The horizontal space, in pixels, between children of a row or column major base.
The width of the base.
The width of the viewport if SCROLL is specified.
The Y offset of the widget relative to its parent.
The vertical space, in pixels, between children of a row or column major base.
The height of the base.
The height of the viewport if SCROLL is specified.
The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets.
In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the button group. The values for different types of CW_BGROUP widgets is shown in the table below:
|
Type
|
Value
|
|---|---|
|
normal
|
None
|
|
exclusive
|
Index of currently set button
|
|
non-exclusive
|
Vector indicating the position of each button (1-set, 0-unset)
|
See Writing Compound Widgets for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.
Button Group widgets generates event structures with the following definition:
event = {ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 }
The SELECT field is passed through from the button event. VALUE is either the INDEX, ID, NAME, or BUTTON_UVALUE of the button, depending on how the widget was created.
Introduced: Pre 4.0