INSERTMENUQQ (W*32, W*64)

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

Module: USE IFQWIN

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 ake a single LOGICAL parameter that 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.
• WININPUT - Brings to the top the child window requesting input and makes it 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 type is 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 Building Applications: Using QuickWin Overview.

Compatibility

QUICKWIN GRAPHICS LIB

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

Example

! build as a QuickWin App.
USE IFQWIN
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