[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

Disabling menu items makes them unavailable for selection by the user.

Disabled menus and menu items are displayed in a ghosted fashion; that is,
their imagery is overlaid with a faint pattern of dots, making it less
distinct.

Enabling or disabling a menu or menu item is always a safe procedure,
whether or not the user is currently using the menus.  Of course, by the
time you have disabled the item, the user may have already selected it.
Thus, the program may receive a IDCMP_MENUPICK message for that item, even
though it considers the item disabled.  The program should be prepared to
handle this case and ignore items that it knows are already disabled.
This implies that the program must track internally which items are
enabled and which are disabled.

The OffMenu() and OnMenu() functions may be used to enable or disable
items while a menu strip is attached to the window.

    void OffMenu( struct Window *window, unsigned long menuNumber );
    void OnMenu( struct Window *window, unsigned long menuNumber );

These routines check if the user is currently using the menus and whether
the menus need to be redrawn to reflect the new states.  If the menus are
currently in use, these routines wait for the user to finish before
proceeding.

If the item component referenced by menuNumber equals NOITEM, the entire
menu will be disabled or enabled.  If the item component equates to an
actual component number, then that item will be disabled or enabled.  Use
the macros defined below for the construction of menu numbers from their
component parts.

The program can enable or disable whole menus, just the menu items, or
just single sub-items.

  * To enable or disable a whole menu, set the item component of the menu
    number to NOITEM.  This will enable or disable all items and any
    sub-items for that menu.

  * To enable or disable a single item and all sub-items attached to that
    item, set the item component of the menu number to the item's ordinal
    number.  If the item has a sub-item list, set the sub-item component
    of the menu number to NOSUB.  If the item has no sub-item list, the
    sub-item component of the menu number is ignored.

  * To enable or disable a single sub-item, set the item and sub-item
    components appropriately.

It is also legal to remove the menu strip from each window that it is
attached to (with ClearMenuStrip() ) change the ITEMENABLED or MENUENABLED
flag of one or more Menu or MenuItem structures and add the menu back
using ResetMenuStrip() (in V36 or higher) or SetMenuStrip() (in any
version of the OS).