CW_PDMENU

The CW_PDMENU function creates widget pulldown menus, which can include sub-menus, from a set of buttons. It has a simpler interface than the XPDMENU procedure, which it replaces. Events for the individual buttons are handled transparently, and a CW_PDMENU event returned. This event can return any one of the following:

Index of the button within the base.
Widget ID of the button.
Name of the button.
Fully qualified name of the button. This allows different sub-menus to contain buttons with the same name in an unambiguous way.

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_pdmenu.pro in the lib subdirectory of the IDL distribution.

Syntax

Result = CW_PDMENU( Parent, Desc [, /COLUMN] [, /CONTEXT_MENU] [, DELIMITER=string] [, FONT=value] [, /MBAR [, /HELP]] [, IDS=variable] [, /RETURN_ID | , /RETURN_INDEX | , /RETURN_NAME | , /RETURN_FULL_NAME] [, TAB_MODE=value] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, YOFFSET=value] )

Return Value

This function returns the widget ID of the newly-created pulldown menu widget.

Arguments

Parent

The widget ID of the parent widget.

Desc

An array of strings or structures. If Desc is an array of strings, each element contains the flag field, followed by a backslash character, followed by the name of the menu item, optionally followed by another backslash character and the name of an event-processing procedure for that element. A string element of the Desc array would look like:

'n\item_name'

'n\item_name\event_proc'

where n is the flag field and item_name is the name of the menu item. The flag field is a bitmask that controls how the button is interpreted; appropriate values for the flag field are shown in the following table. If the event_proc field is present, it is the name of an event-handling procedure for the menu element and all of its children.

If Desc is an array of structures, each structure must have the following definition:

{CW_PDMENU_S, flags:0, name:''}

The name tag is a string field with the following components:

'item_name'

'item_name\event_proc'

where item_name is the name of the menu item. If the event_proc field is present, it is the name of an event-handling procedure for the menu element and all of its children

The flags field is a bitmask that controls how the button is interpreted; appropriate values for the flag field are shown in the following table. Note that if Desc is an array of structures, you cannot specify individual event-handling procedures for each element.

Value	Meaning
0	This button is neither the beginning nor the end of a pulldown level.
1	This button is the root of a sub-pulldown menu. The sub-buttons start with the next button.
2	This button is the last button at the current pulldown level. The next button belongs to the same level as the current parent button. If the name field is not specified (or is an empty string), no button is created, and the next button is created one level up in the hierarchy.
3	This button is the root of a sub-pulldown menu, but it is also the last entry of the current level.

Keywords

COLUMN

Set this keyword to create a vertical column of menu buttons. The default is to create a horizontal row of buttons.

CONTEXT_MENU

Set this keyword to create the pulldown menu within a context-sensitive menu. If CONTEXT_MENU is set, Parent must be the widget ID of a base widget, which also has the CONTEXT_MENU keyword set. The return value of CW_PDMENU is the Parent’s widget ID. If CONTEXT_MENU is set, setting the UNAME or UVALUE on the same call to CW_PDMENU will override the UNAME or UVALUE values of the parent base.

For more on creating context menus, see Context-Sensitive Menus and the CONTEXT_MENU keyword to WIDGET_BASE.

DELIMITER

The character used to separate the parts of a fully qualified name in returned events. The default is to use the “.” character.

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.

HELP

If the MBAR keyword is set, and one of the buttons on the menubar has the label “help” (case insensitive) then that button is created with the /HELP keyword to give it any special appearance it is supposed to have on a menubar. For example, Motif expects help buttons to be on the right.

IDS

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

MBAR

Set this keyword to create a menubar pulldown. If MBAR is set, Parent must be the widget ID of a menubar belonging to a top-level base, and the return value of CW_PDMENU is the Parent widget ID. For an example demonstrating the use of the MBAR keyword, see Example 2 below. Also see the MBAR keyword to WIDGET_BASE. If MBAR is set, setting the UNAME or UVALUE on the same call to CW_PDMENU will override the UNAME or UVALUE values of the parent base.

RETURN_ID

If this keyword is set, the VALUE field of returned events will contain the widget ID of the button.

RETURN_INDEX

If this keyword is set, the VALUE field of returned events will contain the zero-based index of the button within the base. THIS IS THE DEFAULT.

RETURN_NAME

If this keyword is set, the VALUE field of returned events will be the name of the selected button.

RETURN_FULL_NAME

Set this keyword and the VALUE field of returned events will be the fully qualified name of the selected button. This means that the names of all the buttons from the topmost button of the pulldown menu to the selected one are concatenated with the delimiter specified by the DELIMITER keyword. For example, if the top button was named COLORS, the second level button was named BLUE, and the selected button was named LIGHT, the returned value would be

COLORS.BLUE.LIGHT

This allows different submenus to have buttons with the same name (e.g., COLORS.RED.LIGHT).

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. If the MBAR keyword is set, the value specified for UVALUE is also assigned as the UVALUE of the parent menu (i.e., the widget specified by the Parent argument in the call to CW_PDMENU).

XOFFSET

The X offset of the widget relative to its parent.

YOFFSET

The Y offset of the widget relative to its parent.

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.

See Creating a Compound Widget for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.

Widget Events Returned by the CW_PDMENU Widget

CW_PDMENU generates an event structure that specifies the index, widget ID, or name of the menu item selected with the following definition:

event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }

VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button, depending on how the widget was created.

Examples

Example 1

The following is the description of a menu bar with two buttons: “Colors” and “Quit”. Colors is a pulldown containing the colors “Red”, “Green”, Blue”, “Cyan”, and “Magenta”. Blue is a sub-pulldown containing “Light”, “Medium”, “Dark”, “Navy”, and “Royal.”

The following small program can be used with the above description to create the specified menu:

PRO PD_EXAMPLE

desc = [ '1\Colors' , $

'0\Red' , $

'0\Green' , $

'1\Blue' , $

'0\Light' , $

'0\Medium' , $

'0\Dark' , $

'0\Navy' , $

'2\Royal' , $

'0\Cyan' , $

'2\Magenta' , $

'2\Quit' ]

; Create the widget:

base = WIDGET_BASE()

menu = CW_PDMENU(base, desc, /RETURN_FULL_NAME)

WIDGET_CONTROL, /REALIZE, base

;Provide a simple event handler:

REPEAT BEGIN

ev = WIDGET_EVENT(base)

PRINT, ev.value

END UNTIL ev.value EQ 'Quit'

WIDGET_CONTROL, /DESTROY, base

END

The Desc array could also have been defined using a structure for each element. The following array of structures creates the same menu as the array of strings shown above. Note, however, that if the Desc array is composed of structures, you cannot specify individual event-handling routines.

First, make sure CW_PDMENU_S structure is defined:

junk = {CW_PDMENU_S, flags:0, name:'' }

Define the menu:

desc = [ { CW_PDMENU_S, 1, 'Colors' }, $

{ CW_PDMENU_S, 0, 'Red' }, $

{ CW_PDMENU_S, 0, 'Green' }, $

{ CW_PDMENU_S, 1, 'Blue' }, $

{ CW_PDMENU_S, 0, 'Light' }, $

{ CW_PDMENU_S, 0, 'Medium' }, $

{ CW_PDMENU_S, 0, 'Dark' }, $

{ CW_PDMENU_S, 0, 'Navy' }, $

{ CW_PDMENU_S, 2, 'Royal' }, $

{ CW_PDMENU_S, 0, 'Cyan' }, $

{ CW_PDMENU_S, 2, 'Magenta' }, $

{ CW_PDMENU_S, 2, 'Quit' } ]

Example 2

This example demonstrates the use of the MBAR keyword to CW_PDMENU to populate the “Colors” menu item on a menu bar created using WIDGET_BASE.

PRO mbar_event, event

WIDGET_CONTROL, event.id, GET_UVALUE=uval

CASE uval OF

'Quit': WIDGET_CONTROL, /DESTROY, event.top

ELSE: PRINT, event.value

ENDCASE

END

PRO mbar

; Create the base widget:

base = WIDGET_BASE(TITLE = 'Example', MBAR=bar, XSIZE=200, $

UVALUE='base')

file_menu = WIDGET_BUTTON(bar, VALUE='File', /MENU)

file_bttn1=WIDGET_BUTTON(file_menu, VALUE='Quit', $

UVALUE='Quit')

colors_menu = WIDGET_BUTTON(bar, VALUE='Colors', /MENU)

; Define array for colors menu items:

desc = [ '0\Red' , $