Menu verify is one of the Intuition verification capabilities that allow
an application to ensure that it is prepared for some action taken by
Intuition before that action takes place.  Through menu verify, Intuition
allows all windows in a screen to verify that they are prepared for menu
operations before the operations begin.  In general, use menu verify if
the program is doing something special to the display of a custom screen,
and needs to be sure the operation has completed before menus are rendered.

Any window can access the menu verify feature by setting the
idcmp_menuverify flag with the wa_idcmp tag when opening the window.  when
menus are activated in a screen which contains at least one window with
IDCMP_MENUVERFIY set, menu operations will not proceed until all windows
with the menu verify flag set reply to the notification or until the last
message times out.  The specific menu verify protocol is described below.

In any case, it is vital that the application know when menu operations
terminate, for only then does it have control of the screen again.  For
the active window, this is typically detected by watching for an
idcmp_menupick message.  if the program cancels the menu operations
(MENUCANCEL), then it will instead receive an idcmp_mousebuttons message
with code equal to MENUUP.  Inactive windows will always receive
IDCMP_MOUSEBUTTONS message with code equal to MENUUP.

The active window is given special menu verify treatment.  It receives the
menu verify message before any other window and has the option of
canceling menu operations altogether.  This could be used, for instance,
to examine where the user has positioned the mouse when the right button
was pressed.  For example, the application may choose to allow normal menu
operations to proceed only when the pointer is in the menu bar area.  When
the pointer is below the menu bar, then the application can choose to
interpret the menu verify message as a right button event for some
non-menu purpose.

The program can tell if it is the active window for the verify event by
examining the code field of the idcmp_menuverify message.  if the code
field is equal to MENUWAITING, this window is not active and Intuition is
simply waiting for verification that menu operations may continue.
However, if the Code field is equal to MENUHOT, this window is active and
it determines if menu operations should proceed.

If it wishes menu operations to proceed, the active window should reply to
the idcmp_menuverify message without changing any values.  to cancel the
menu operation, change the code field of the message to MENUCANCEL before
replying to the message.

When the active window cancels the menu operation it will be sent an
idcmp_mousebuttons message with code equal to menuup.  in general, the
window will not then receive an idcmp_menupick event as it cancelled the
operation.  However, the system should be prepared to handle an
IDCMP_MENUPICK message with code equal to menunull as one may be sent if
the user releases the mouse button before the window replies to the
message.

The system takes no action on screen until the active window either
replies to the menu verify event or the event times out.  If the active
window replies to the event in time and does not cancel the menu
operation, Intuition will then move the screen title bar layer to the
front, display the menu strip and notify all inactive menu verify windows
of the operation.  Layers will not be locked and the actual menus will not
be swapped in until all these inactive windows reply to the message or
time out.  The inactive windows may not cancel the menu operation.

If the user releases the menu button before the active window replies to
the menu verify message, the menu operation will be cancelled and the
active window will be sent an idcmp_mousebuttons message with code equal
to MENUUP.  When the active window finally replies to the message, it will
receive an idcmp_menupick message with code equal to menunull.

If the event times out before the active window replies to the message, it
will immediately be sent an idcmp_menupick message with code equal to
menunull.  then, when the user releases the menu button, the program will
receive an idcmp_mousebuttons message with code equal to menuup.

If an inactive window receives an idcmp_menuverify message, it will always
receive an idcmp_mousebuttons message with code equal to menuup when the
menu operations are completed.

    About Double-Menu Requesters.
    -----------------------------
    The processing described above becomes more complicated when
    double-menu requester processing is introduced.  If an application
    chooses to use a double-menu requester in a window with
    idcmp_menuverify set, it should be aware that odd message
    combinations are possible.  For instance, it is possible to receive
    only an IDCMP_MENUVERIFY event with no following idcmp_mousebuttons
    event or idcmp_menupick event.  applications should avoid using
    double menu requesters if possible.