APPENDMENUQQ

QuickWin Function: Appends a menu item to the end of a menu and registers its callback subroutine.

Module: USE DFLIB

Syntax

result = APPENDMENUQQ (menuID, flags, text, routine)

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

flags
(Input) INTEGER(4). Constant indicating the menu state. Flags can be combined with an inclusive OR (see Results). 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) EXTERNAL. Callback subroutine that is called if the menu item is selected. All routines 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 the 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. It is .TRUE. if successful; otherwise, .FALSE..

You do not need to specify a menu item number, because APPENDMENUQQ always adds the new item to the bottom of the menu list. If there is no item yet for a menu, your appended item is treated as the top-level menu item (shown on the menu bar), and text becomes the menu title. APPENDMENUQQ ignores the callback routine for a top-level menu item if there are any other menu items in the menu. In this case, you can set routine to NUL.

If you want to insert a menu item into a menu rather than append to the bottom of the menu list, use INSERTMENUQQ.

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 APPENDMENUQQ 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 about customizing QuickWin menus, see Using QuickWin in the Programmer's Guide.

Compatibility

QUICKWIN GRAPHICS LIB

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

Example

      USE DFLIB
      LOGICAL(4) result
      CHARACTER(25) str
      ...
! Append two items to the bottom of the first (FILE) menu
      str    = '&Add to File Menu'C ! 'A' is a quick-access key
      result = APPENDMENUQQ(1, $MENUENABLED, str, WINSTATUS)
      str    = 'Menu Item &2b'C ! '2' is a quick-access key
      result = APPENDMENUQQ(1, $MENUENABLED, str, WINCASCADE)
! Append an item to the bottom of the second (EDIT) menu
      str    = 'Add to Second &Menu'C ! 'M' is a quick-access key
      result = APPENDMENUQQ(2, $MENUENABLED, str, WINTILE)