WwMenuItem Function

Reference Guide > W Routines > WwMenuItem Function

WwMenuItem Function

Adds, modifies, or deletes specified menu items.

Usage

status = WwMenuItem(parent, item, value[, callback])

Input Keywords

parent — The menu pane widget ID acquired using the Menus keyword from the WwMenuBar, WwOptionMenu, or WwPopupMenu functions. A menu pane is a special menu widget that serves as a container for a menu item.

item — The index of the menu item; the index of the first menu item is one (1). Used for an Update or Delete operation.

value — The value (string) of the menu item. Used for an Update or Add operation.

callback — The callback procedure that is executed when the menu item is selected. Used for an Add operation.

Returned Value

status — Returns one (1) if the function is successful, or zero (0) if the function is not successful.

Keywords

Add — Appends the specified item to the menu. The type of item is specified by additional keywords (Button, Icon, Menu, or Toggle). The Name keyword can also be used with Add to specify the resource specification for the particular type of widget.

Button — A push button item is added. If Name is not specified, the default resource specification is button__#.

Icon — A graphic (icon) button is added. If Name is not specified, the default resource specification is icon__#.

Menu — A pull-right menu item is added. If Name is not specified, the default resource specification is pane__#.

Toggle — A toggle (radio) button is added. If Name is not specified, the default resource specification is toggle__#.

note	The default resource specification for each item type consists of the item name followed by two _ (underscores) and an index number identifying the number of items in the menu.

Update — Modifies the value of the item specified by the index of item.

Delete — Deletes the item specified by index.

note	Do not delete the last item of an option menu. The routines that maintain the menu may exhibit errors when dealing with menus with no items. When dealing with the last remaining item in a menu, affect changes exclusively via the Update keyword.

Name — A string specifying the name of the PushButton widget (if a string or icon label is given), otherwise Name specifies the name of the ToggleButton widget. The Name keyword is used as part of the resource specification that identifies items specified using the Add keyword. The defaults for Name are listed for each of the three different item types under the Add keyword description.

Discussion

WwMenuItem lets you dynamically update menus that have been created. All menu items are placed inside a parent menu pane, and the widget ID of the appropriate menu pane can be acquired using the Menus keyword of the WwMenuBar, WwPopupMenu, or WwOptionMenu functions.

To update (Update keyword) or remove (Delete keyword) a menu item, use the appropriate menu item index; the index of the first menu item is one (1). To add a menu item to the bottom of the menu use the Add keyword.

Example

This simple example shows how to use WwMenuItem in your callback routine to add, update and delete contents from the menu pane.

Enter the following code into a file, and compile it with the .RUN command. To run this example, enter WWMENUITEM_EX at the WAVE> prompt.

PRO MenuCB, wid, index

   COMMON menus, menupane, counter

   CASE index OF

      1: BEGIN

         IF counter NE 1 THEN  BEGIN

            status = WwMenuItem(menupane, 1, 'New menu', /Add)

            counter = 1

         ENDIF

END

      2: BEGIN

            status = WwMenuItem(menupane, 1, 'Menu updated', $

            /Update)

END

      3: BEGIN

            status = WwMenuItem(menupane, 1, /Delete)

            counter = 0

END

   ENDCASE

END

PRO wwmenuitem_ex

   COMMON menus, menupane, counter

   counter = 0

   top = WwInit('wwmenuitem_ex', 'Examples', layout)

   menus={,callback:'MenuCB', $

      menubutton:'Select an option', $

      menu:{,callback:'MenuCB', $

      button:'Add new menu item', $

      button:'Update menu item', $

      button:'Remove menu items'}}

   menupane = WwMenuBar(layout, menus)

   status=WwSetValue(top, /Display, Size=[200,75])

   WwLoop

END