There are a lot of ways to use fakeModalDialog, and therefore there is a lot
to know.  However, for simple cases, using fakeModalDialog is very simple.
In complex cases, using fakeModalDialog is still a lot simpler than if it were
not used.  Overall, using fakeModalDialog makes dialog things a lot easier to
do than before.

How to use fakeModalDialog in a simple case:

Step 1:  Open a window with a NewWindow2 call.
Step 2:  Call fakeModalDialog inside a loop.  Unlike ModalDialog,
         fakeModalDialog returns NULL events.  This makes the loop necessary.
Step 3:  When the dialog should be closed, break out of the loop and close the
         window.  You may wish to use some of fakeModalDialog's data access
		 routines before closing the window, since the controls will disappear,
		 along with their data, when the window is closed.

Using fakeModalDialog is really that simple.

Here is some sample c code showing a typical usage:

    wptr = NewWindow2(NULL, NULL, NULL, NULL, 2, theWindowID, rWindParam1);

    for (;;) {
		ctlID = fakeModalDialog(&event, NULL, NULL, NULL, 0);
		if (ctlID == 1) break;
	}

	CloseWindow(wptr);



There are some rules and restrictions when using fakeModalDialog.  (We couldn't
make it too painless, could we?)  These restrictions aren't many, but they are
important.

Restriction 1:  Control resource ID's must have bit 31 off.  Bit 31 is reserved
                by fakeModalDialog.
Restriction 2:  Menu item resource ID's must also have bit 31 off.  This is
                for the same reason as restriction 1.
Restriction 3:  fakeModalDialog expects extended controls to be used in a
                window.  While regular controls won't cause fakeModalDialog to
                explode, they are not handled as well or as efficiently.

Those are about the only restrictions to fakeModalDialog.


What makes fakeModalDialog somewhat complex is the new human interface dialog
type movable/modal dialogs.  These are a new type of animal, and therefore
weren't supported directly by the toolbox.  To fill this gap, fakeModalDialog
has had movable/modal dialog support added.

Basically, movable/modal dialogs are a hybrid between modeless dialogs and
modal dialogs.  Movable/modal dialogs have all the properties of modeless
dialogs, except that the movable/modal dialog stays as the top window of
an application.

Let's talk about how movable/modal dialog behave on the Mac for a minute.
This will help with the understanding of why fakeModalDialog allows some
of the things that it does.

When using MultiFinder on the Mac, you can switch between multiple applications
just by clicking on an application's window (or by other means).  If the
current application has a movable/modal dialog, that dialog must be the
frontmost window for that application.  However, if you click on a window from
another application, that application's windows are brought to the front.  In
this respect, the rule that a movable/modal dialog must be the frontmost window
can be violated.  Other than application switching, however, the rule that a
movable/modal dialog is the frontmost window stands.

Now back to the IIGS.

The IIGS doesn't have MultiFinder.  It does have desk accessories, however.
Desk accessories are a kind of additional application, and you can switch
between the main application and desk accessories simply by clicking on the
appropriate window.  Desk accessories are as close as the IIGS gets to 
MultiFinder.  Due to this, desk accessory support is a part of fakeModalDialog.

Another feature of movable/modal dialogs is that menus are available.  Remember
that movable/modal dialogs are just like modeless dialogs, except that they
stay as the top window.  Modeless dialogs allow menu access, so therefore
movable/modal dialogs should, too.

Since menus are available from a movable/modal dialog, the application has to
make sure that the correct menus are and are not available when the
movable/modal dialog is shown.


This has been a quick introduction to the issues involving movable/modal
dialogs and fakeModalDialog.  The new version of lister uses fakeModalDialog
and movable/modal dialogs extensively.  This sample code should be studied for
more information.

