This interface supports Macintosh-specific user interface display.
As an alternative to this platform-specific API, consider using
the MUI XDK and MUI Xtra instead. It
provides platform-independent interfaces that support dialogs
containing a variety of widget types, including dynamic layout
capabilities and a standard event-handling mechanism. The MUI
API also lets you easily display system alerts, file dialogs,
and URL dialogs. See the MUI Developer's
Guide for information on which applications support the MUI XDK.
Replaces the Macintosh Alert() call. This method is required to ensure proper window management
in the host application. alertID is the alert resource ID of your alert. Make sure
to call MoaBeginUsingResources() before this call and MoaEndUsingResources() afterwards,
to provide access to your resources. filterProcUPP is a universal procPtr to a filterProc;
set to NULL if there is none. MacAlert() returns a 16-bit integer identifying what user action
took place; it returns 1 if alert wasn't drawn. See the Inside
Mac documentation on Alert for more information.
Drags a Macintosh window. pWindow is
a Macintosh WindowPtr.
This method is provided as a replacement for the Macintosh Toolbox DragWindow() function.
This method allows the host application to correctly handle window
layering and focus when your Xtra is running along-side windows
owned by the application. To have events for a Macintosh window
routed to your code, see MacRegisterWindow() and MacUnregisterWindow().
See also: MacSelectWindow(), MacXShowWindow(), MacHideWindow().
Passes a Macintosh-style event on to host
application. pEventRecord is a pointer to a Macintosh EventRecord structure. This call passes the event directly to the host application's
event loop.
Hides a Macintosh window. pWindow is
a Macintosh WindowPtr.
This method is provided as a replacement for the Macintosh Toolbox HideWindow() function.
This method allows the host application to correctly handle window
layering and focus when your Xtra is running along-side windows
owned by the application. To have events for a Macintosh window
routed to your code, see MacRegisterWindow() and MacUnregisterWindow().
See also: MacDragWindow(), MacXShowWindow(), MacSelectWindow().
Value obtained from calling MacPrepareModalDialog()
filterProcUPP
PMoaVoid
itemHit
MoaShort *
Returns
MoaError
Description
Use this on the Macintosh instead of
calling the Toolbox ModalDialog().
This method allows the host application to get update events and
performs other operations supporting moveable modal dialogs. dialogCookieis
the value obtained from a call to MacPrepareModalDialog(), which must be made before showing the dialog and entering a dialog
loop. If the dialog has a title bar, it is moveable, and the host
application's windows and dialogs beneath it update properly when
it is moved. Since moving a dialog can cause update events in
the host applications, make sure you can handle calls back to
your thumbnail and sprite imaging methods from within this call.
Be sure to "bracket" your call to MacModalDialog() with calls to MoaBeginUsingResources()
and MacPrepareModalDialog() before showing your dialog
and entering your dialog loop, andMacUnprepareModalDialog() and MoaEndUsingResources() after exiting the dialog loop and closing the dialog.
Call this method before calling the MacModalDialog() loop. This method must be called before your dialog has been displayed
and before you enter you modal dialog loop. pDialogCookiecontains
a pointer to a MoaMmDialogCookieto
receive a special value that is passed to subsequent calls to MacModalDialog() and MacUnprepareModalDialog().
Use this method to incorporate modeless windows or floating palettes
controlled by your Xtra.. For example, your asset media editor
can be modeless and persist after the call to the Editor method
returns. (Use the PIMoaAssetCallback::SetModified() method to "dirty" your asset when changes
are made asynchronously.) As another example, a floating inspector
palette could be created that tracks the current selection in
the cast window, supplying additional information about the selected
cast member(s).
You supply a PIMoaMmMacEventHandler interface which the host application calls back (the
Macintosh EventRecord* is given as a parameter to the
HandleEvent() method).
pWindow is the Macintosh window pointer of the window
you want to register. flags contains the window registration flags; see mmtypes.h.
refCon is an
arbitrary 4-byte value (user-data) which the caller can supply
to be passed to pEventHandler when
events are dispatched.
Director Tip:This callback is also available in
projectors, so can be used to display arbitrary windows at run-time.
Here are some tips about Macintosh window management:
Do not use the refCon or windowKind fields of the Macintosh WindowPeek structure for your window; these are reserved for
use by the host application to support event dispatching. If you
need to associate special instance data with your window, use
the class implementing IMoaMmMacEventHandler.
Before registering a window, you create it using NewWindow(), NewCWindow(), GetNewWindow(),
or GetNewCWindow(),
which are standard Macintosh toolbox window creation calls.
You must create a new instance of your IMoaMmMacEventHandler class for each window to register.
(You can't use the same instance
to handle events for multiple windows.)
You must create your window as hidden. If you
want to show it immediately, use the MacXShowWindow() callback after registering it. To bring it to the
front, follow MacXShowWindow() with a call to MacSelectWindow().
Do not use the Macintosh calls DragWindow(),
ShowWindow(), HideWindow(),
or SelectWindow() on registered windows. Instead,
use the corresponding IMoaMmWndMac wrapper methods: MacDragWindow(),
MacXShowWindow(), MacHideWindow(), MacSelectWindow().
If you do not use these methods, the host application's window
management code may be affected adversely.
Only call the Macintosh DisposeWindow() routine after the window is hidden and
unregistered. The sequence for disposing a window is:
Selects a Macintosh window and brings the
window to the front. pWindow is
a Macintosh WindowPtr.
This method is provided as a replacement for the Macintosh Toolbox SelectWindow() function.
Use this callback instead of calling SelectWindow().
This allows the host application to correctly handle window layering
and focus when your Xtra is running along-side windows owned by
the application. To have events for a Macintosh window routed
to your code, see MacRegisterWindow() and MacUnregisterWindow().
See also: MacDragWindow(), MacXShowWindow(), MacHideWindow().
Makes a Macintosh window visible; it doesn't
necessarily bring the window to the front. pWindow is a Macintosh
WindowPtr.
This method is provided as a replacement for the Macintosh Toolbox ShowWindow() function.
Use this callback instead of calling ShowWindow().
This allows the host application to correctly handle window layering
and focus when your Xtra is running along-side windows owned by
the application. To have events for a Macintosh window routed
to your code, see MacRegisterWindow() and MacUnregisterWindow().
See also: MacDragWindow(), MacXShowWindow(), MacSelectWindow().
Call this after your MacModalDialog() loop. This method must be called after you have exited
your dialog loop and your dialog window has been closed. dialogCookie is the value
obtained from the previous call to MacPrepareModalDialog().
Call this with the PIMoaMmMacEventHandler you supplied to MacRegisterWindow() when you no longer want to receive events for the window. You
must call MacUnregisterWindow()before
disposing of your window See the description of MacRegisterWindow()method
for more information.