# INSERTMENUQQ (W*S)

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

## Module

USE IFQWIN

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. 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+Rin the example) as an alternative to selecting the item with the mouse.

## Example

    USE IFQWIN
    LOGICAL(4)     :: status
    CHARACTER (80) :: text_input

    ! insert new item into Menu 5 (Window)
    status= INSERTMENUQQ(5, 5, $MENUCHECKED, 'New Item:Status 5_5'C, WINSTATUS)
    ! insert new menu in position 2
    status= INSERTMENUQQ(2, 0, $MENUENABLED, 'New Menu:2_0'C, NUL)
    ! insert new menu in position 3, and mark it disabled & grayed
    status= INSERTMENUQQ(3, 0, IOR($MENUGRAYED,$MENUDISABLED), 'New Disabled Menu:3_0'C, NUL)
    ! insert new item under the new menu 2 in position 1
    status= INSERTMENUQQ(2, 1, $MENUENABLED, 'New Item:Print'C, WINPRINT)
    ! insert separator bar under the new menu 2 in position 2
    status= INSERTMENUQQ(2, 2, $MENUSEPARATOR, 'New Separator'C, NUL)
    ! insert new item under the new menu 2 in position 3
    status= INSERTMENUQQ(2, 3, IOR($MENUCHECKED,$MENUENABLED), 'New Item:Select Text'C, &
                         WINSELECTTEXT)
    ! insert new item under the new menu 2 in position 5
    status= INSERTMENUQQ(2, 4, $MENUENABLED, 'New Item:Copy Selected Text'C, WINCOPY)
    ! insert new item under the new menu 2 in position 6
    status= INSERTMENUQQ(2, 5, $MENUENABLED, 'New Item:Paste Selected Text'C, WINPASTE)

    write(*,'("Enter (or cut and paste) a text value: ")',advance='no')
    read (*,"(A)") text_input
    write(*,'("You just entered: ", A1, A, A1)') "'",trim(text_input),"'"

    END

Parent topic: QuickWin Library Routines

## See Also

APPENDMENUQQ
DELETEMENUQQ
MODIFYMENUFLAGSQQ
MODIFYMENUROUTINEQQ
MODIFYMENUSTRINGQQ