Methods
=======

   The MUI system talks to its classes with a specific set of methods.
Some of these methods need to be implemented by all MUI classes but
most of them are optional.  This chapter gives a quick overview about
the methods your class might receive.  All methods are discussed more
detailed in the following sections.

   As usual with BOOPSI objects, you will get an OM_NEW whenever a new
object of your class shall be created. Since with MUI, the deepest
nested objects are always created first, your object won't know anything
about its display environment during OM_NEW.

   After all objects are created, MUI finds out about the display
environment (screen, drawinfo structure, fonts, etc.) and sends you a
MUIM_Setup method with this information. You can calculate some
internal data here that depends on the display enviroment (e.g. the
line height in an editor class). Note that you still don't have a
intuition window at this point.

   The next method your class receives is called MUIM_AskMinMax. MUI
wants to find out about your minimum, maximum and default sizes to
prepare its window size calculation and layout algorithms. Since you
already know about display environment, calculating these values should
be easy at this point.

   After asking all objects about their dimensions and adding the
results depending on the type of group your object resides in, MUI is
able to open the window. Once it is open, your object will receive a
MUIM_Show method telling you that you are about to be added to the
window.  MUIM_Show is mainly intended for use by intuition like
gadgets, they will do an AddGadget() here (and a RemGadget() during
MUIM_Hide). Usually, you won't need to implement these methods.

   Since your class still didn't draw anything, its time for a
MUIM_Draw method now. MUI sends this method whenever it feels that you
should draw yourself.  This happens of course after a window has been
opened but also when you reside in a simple refresh window and need to
be refreshed. MUIM_Draw is the only place where you are actually
allowed to draw something!

   When the window is resized, MUI sends a MUIM_Hide (allowing some
RemGadget() for intuition like gadgets), calculates new positions and
sizes and sends a MUIM_Show and a MUIM_Draw again. However, if you
correctly implement MUIM_Draw, you don't need to care about this in
almost all cases.

   When your window is about to be closed (either because your
application no longer needs it or because the user iconified your
program or changed the preferences settings), you will receive a
MUIM_Cleanup. This allows you to free some display environment
dependant things you allocated during MUIM_Setup.

   The last thing your object will get is of course a OM_DISPOSE after
it has hopefully done all the things you wanted it to do.

   To sum it up again, look at the diagram below. Things between
brackets might be called zero or more times for the same object.

     OM_NEW; /* you dont know anything about display environment here */
     {
        MUIM_Setup;      /* information about display, still no window */
        MUIM_AskMinMax;  /* tell me your min/max dimensions */
        [ window is opened here ]
        {
           MUIM_Show;    /* add yourself to the window, don't yet draw */
           {
              MUIM_Draw;     /* draw yourself */
           }
           MUIM_Hide;    /* remove yourself from the window */
        }
        [ window is closed here ]
        MUIM_Cleanup;    /* free any display dependant data */
     }
     OM_DISPOSE; /* kill yourself completely */

   As you probably noticed, most methods are implemented as
constructor/destructor pairs: OM_NEW & OM_DISPOSE, MUIM_Setup &
MUIM_Cleanup, MUIM_Show & MUIM_Hide. For every constuctor call, you
will receive exactly one destructor call. Usually, you will allocate
some resources during OM_NEW, MUIM_Setup or MUIM_Show and free these
resources during OM_DISPOSE, MUIM_Cleanup or MUIM_Hide respectively.

   The three levels of constructor/destructor pairs feature different
amount of available information about the display environment.

   - OM_NEW (destructor OM_DISPOSE)

     No information at all. All you can do is parse the initial
     attribute list and store its contents in the instance data
     structure of your object.

   - MUIM_Setup (destructor MUIM_Cleanup)

     MUI has figured out what screen and font to use. You can
     allocate/calculate things that depend on this information.

   - MUIM_Show (destructor MUIM_Hide)

     MUI has finally opened an intuition window at this point. You are
     able to allocate resources depending on a window context here.

   You can rely on the fact that you receive OM_NEW before MUIM_Setup
(of course, otherwise you wouldn't have a valid object pointer) and
MUIM_Setup before MUIM_Show. But always keep in mind that you might get
multiple MUIM_Show / MUIM_Hide pairs or MUIM_Setup / MUIM_Cleanup pairs
or that you could receive a MUIM_Setup / MUIM_Cleanup pair without some
MUIM_Show / MUIM_Hide between.