CW_PDMENU

The CW_PDMENU function simplifies creating widget pulldown menus. 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:

Only buttons with textual names are handled by this widget. Bitmaps are not understood.

The returned value of this function is the widget ID of the newly-created pulldown menu widget.

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.

Calling Sequence

Result = CW_PDMENU( Parent, Desc )

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 '

or

'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 Button Flag Bit Meanings. . 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 has the following definition:

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

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

' item_name '

or

' 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 Button Flag Bit Meanings. . Note that if Desc is an array of structures, you cannot specify individual event-handling procedures for each element.

  • Button Flag Bit Meanings.

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

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 or Macintosh systems). See 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 menubar of a top-level base. (See the MBAR keyword to WIDGET_BASE for details.)

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).

UVALUE

The "user value" to be assigned to the widget.

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 Compound Widgets for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO .

Widget Events Returned by the CW_PDMENU Widget

This widget generates event structures 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.

Example

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

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' } ]

See Also

CW_BGROUP , WIDGET_DROPLIST