INSERTMENUQQ

QuickWin Function: Inserts a menu item into a QuickWin menu and registers its callback routine.

Module: USE DFLIB

Syntax

result = INSERTMENUQQ (menuID, itemID, flag, text, routine)

menuID
(Input) INTEGER(4). Identifies the menu in which the item is inserted, starting with 1 as the leftmost menu.

itemID
(Input) INTEGER(4). Identifies the position in the menu where the item is inserted, starting with 0 as the top menu item.

flag
(Input) INTEGER(4). Constant indicating the menu state. Flags can be combined with an inclusive OR (see Results section below). The following constants are available:

• $MENUGRAYED - Disables and grays out the menu item.
• $MENUDISABLED - Disables but does not gray out the menu item.
• $MENUENABLED - Enables the menu item.
• $MENUSEPARATOR - Draws a separator bar.
• $MENUCHECKED - Puts a check by the menu item.
• $MENUUNCHECKED - Removes the check by the menu item.

text
(Input) Character*(*). Menu item name. Must be a null-terminated C string, for example, words of text'C.

routine
(Input) EXERNAL. Callback subroutine that is called if the menu item is selected. All routines must take a single LOGICAL parameter which indicates whether the menu item is checked or not. You can assign the following predefined routines to menus:

• WINPRINT: Prints the program.
• WINSAVE: Saves the program.
• WINEXIT: Terminates the program.
• WINSELECTTEXT: Selects text from the current window.
• WINSELECTGRAPHICS: Selects graphics from the current window.
• WINSELECTALL: Selects the entire contents of the current window.
• WINCOPY: Copies the selected text and/or graphics from current window to the Clipboard.
• WINPASTE: Allows the user to paste Clipboard contents (text only) to the current text window of the active window during a READ.
• WINCLEARPASTE: Clears the paste buffer.
• WINSIZETOFIT: Sizes output to fit window.
• WINFULLSCREEN: Displays output in full screen.
• WINSTATE: Toggles between pause and resume states of text output.
• WINCASCADE: Cascades active windows.
• WINTILE: Tiles active windows.
• WINARRANGE: Arranges icons.
• WINSTATUS: Enables a status bar.
• WININDEX: Displays the index for QuickWin help.
• WINUSING: Displays information on how to use Help.
• WINABOUT: Displays information about the current QuickWin application.
• NUL: No callback routine.

Results:

The result is of type LOGICAL(4). The result is .TRUE. if successful; otherwise, .FALSE.

Menus and menu items must be defined in order from left to right and top to bottom. For example, INSERTMENUQQ fails if you try to insert menu item 7 when 5 and 6 are not defined yet. For a top-level menu item, the callback routine is ignored if there are subitems under it.

The constants available for flags can be combined with an inclusive OR where reasonable, for example $MENUCHECKED .OR. $MENUENABLED. Some combinations do not make sense, such as $MENUENABLED and $MENUDISABLED, and lead to undefined behavior.

You can create quick-access keys in the text strings you pass to INSERTMENUQQ as text by placing an ampersand (&) before the letter you want underlined. For example, to add a Print menu item with the r underlined, text should be "P&rint". Quick-access keys allow users of your program to activate that menu item with the key combination ALT+QUICK-ACCESS-KEY (ALT+R in the example) as an alternative to selecting the item with the mouse.

For more information on customizing QuickWin menus, see Using QuickWin in the Programmer's Guide.

Compatibility

QUICKWIN GRAPHICS LIB

See Also: APPENDMENUQQ, DELETEMENUQQ, MODIFYMENUFLAGSQQ, MODIFYMENUROUTINEQQ, MODIFYMENUSTRINGQQ

Example

! build as a QuickWin App.
USE DFLIB
LOGICAL(4) status
! insert new item into Menu 5 (Window)
status= INSERTMENUQQ(5, 5, $MENUCHECKED, 'New Item'C, &
                     WINSTATUS)
! insert new menu in position 2
status= INSERTMENUQQ(2, 0, $MENUENABLED, 'New Menu'C, &
                     WINSAVE)
END