CW_BGROUP

The CW_BGROUP function creates a widget base of buttons. It simplifies creation of a cluster of buttons, and handles the details of creating the proper base (standard, exclusive, or non-exclusive) and filling in the desired buttons. Button groups can be simple menus in which each button acts independently, exclusive groups (also known as “radio buttons”), or non-exclusive groups (often called “checkboxes”). 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.

Examples

See Creating Menus for example CW_BGROUP code.

Syntax

Result = CW_BGROUP( Parent, Names [, BUTTON_UVALUE=array] [, COLUMN=value] [, EVENT_FUNCT=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] [, SET_VALUE=value] [, TAB_MODE=value] [, X_SCROLL_SIZE=width] [, Y_SCROLL_SIZE=height] [, SET_VALUE=value] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, XSIZE=width] [, YOFFSET=value] [, YSIZE=value] )

Return Value

This function returns the widget ID of the newly-created button group widget.

Arguments

Parent

The widget ID of the parent widget.

Names

A string array, one string per button, giving the name of each button.

Keywords

BUTTON_UVALUE

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.

COLUMN

Buttons will be arranged in the number of columns specified by this keyword.

EVENT_FUNCT

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.

EXCLUSIVE

Set this keyword to cause buttons to be placed in an exclusive base, in which only one button can be selected at a time.

FONT

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 Using Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.

FRAME

Specifies the width of the frame to be drawn around the base.

IDS

A named variable in which the button IDs will be stored, as a longword vector.

LABEL_LEFT

Set this keyword to a string creating a text label to the left of the buttons.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

LABEL_TOP

Set this keyword to a string creating a text label above the buttons.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

MAP

Set this keyword to cause the base to be mapped when the widget is realized (the default).

NONEXCLUSIVE

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.

NO_RELEASE

If set, button release events will not be returned.

RETURN_ID

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.

RETURN_INDEX

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.

RETURN_NAME

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.

ROW

Buttons will be arranged in the number of rows specified by this keyword.

SCROLL

If set, the base will include scroll bars to allow viewing a large base through a smaller viewport.

SET_VALUE

Allows changing the current state of toggle buttons. SET_VALUE works differently for exclusive and nonexclusive buttons. For exclusive buttons, the SET_VALUE argument is set to the zero-based index of the button when the widget is realized. For example, to set the default to the fourth button in a series, then set the SET_VALUE keyword equal to three.

For nonexclusive buttons, the SET_VALUE keyword works as an array of flags to set the buttons on (1) or off (0).

The following example demonstrates both of these concepts:

PRO ex_cw_bgroup

values = ['One', 'Two', 'Three', 'Four', 'Five']

base = WIDGET_BASE(/ROW)

bgroup1 = CW_BGROUP(base, values, /COLUMN, /EXCLUSIVE, $

LABEL_TOP='Exclusive', /FRAME, SET_VALUE=3)

bgroup2 = CW_BGROUP(base, values, /COLUMN, /NONEXCLUSIVE, $

LABEL_TOP='Nonexclusive', /FRAME, SET_VALUE=[1,0,1,0,1])

WIDGET_CONTROL, base, /REALIZE

END

SPACE

The space, in pixels, to be left horizontally and vertically between each individual button member of the CW_BGROUP base. This keyword’s value is only applied if one of the COLUMN or ROW keywords is set.

TAB_MODE

Set this keyword to one of the values shown in the table below to determine how the widget hierarchy can be navigated using the Tab key. The TAB_MODE setting is inherited by lower-level bases and child widgets unless it is explicitly set on an individual widget.

Note: It is not possible to tab to disabled (SENSITIVE=0) or hidden (MAP=0) widgets.

Valid settings are:

Value

Description

0

Disable navigation onto or off of the widget. This is the default. Child widgets automatically inherit the tab mode of the parent base as described in Inheriting the TAB_MODE Value.

1

Enable navigation onto and off of the widget.

2

Navigate only onto the widget.

3

Navigate only off of the widget.

Note: In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems.

UNAME

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.

UVALUE

The “user value” to be assigned to the widget.

XOFFSET

The X offset of the widget relative to its parent.

XPAD

The horizontal space, in pixels, to be left around the edges of a row or column major base. This keyword’s value is only applied if one of the COLUMN or ROW keywords is set.

XSIZE

The width of the base.

X_SCROLL_SIZE

The width of the viewport if SCROLL is specified.

YOFFSET

The Y offset of the widget relative to its parent.

YPAD

The vertical space, in pixels, to be left around the edges of a row or column major base. This keyword’s value is only applied if one of the COLUMN or ROW keywords is set.

YSIZE

The height of the base.

Y_SCROLL_SIZE

The height of the viewport if SCROLL is specified.

Keywords to WIDGET_CONTROL and WIDGET_INFO

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.

Widget Events Returned by the CW_BGROUP Widget

CW_BGROUP generates an event that specifies which button or buttons were selected. The widgets generate 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.

Version History

Pre 4.0

Introduced

6.1

Added TAB_MODE keyword

See Also

CW_PDMENU, WIDGET_BUTTON