This document contains the following sections:
The MUI XDK and MUI Xtra provide a cross-platform API for displaying and interacting with several different types of user interface dialog boxes. The following interfaces are available:
IMuiDialog
provides a general mechanism
for presenting and interacting with complex dialog windows containing
text fields, buttons, sliders, bitmaps, groups of widgets, and
other user interface elements.
IMuiAlert
provides a way to display simple user alert dialogs.
IMuiFile
provides a way to display file open dialogs for local
files.
IMuiURL
provides a way to display
a dialog for accepting URLs and returning them in IMoaPathName
interfaces. Note: The MUI Xtra and MUI API are supported on PPC Macintosh, and
on Windows 95 and Windows NT. They are supported only in Director 6 and higher.
The IMuiDialog
interface supports dialog boxes displaying a variety of UI widgets.
Provided by the MUI Xtra, this interface offers a number of widgets,
such as buttons, sliders, text boxes, bitmaps, horizontal and
vertical separators, and other features for presentation in a
dialog box. The Xtra supports manual or automatic layout of widgets,
and provides a mechanism, using the standard IMoaNotification
interface, to interact with your Xtra as the user manipulates
those widgets.
To create a MUI Dialog, you first create an instance of the MUI
Xtra's Dialog class and IMuiDialog
interface. To
do so, you call the IMoaCallback::MoaCreateInstance() method, passing CLSID_CMui
, the CLSID for the Dialog
class, and IID_IMuiDialog
, the IID for the IMuiDialog
interface, as follows:
PIMuiDialog pMuiDialog; pObj->pCallback->MoaCreateInstance(&CLSID(CMui), &IID(IMuiDialog), (PPMoaVoid)&pMuiDialog);
To initialize a dialog box, you call IMuiDialog::Initialize(),
passing parameters to define the window and the widgets that appear
in it.
The TMuiWindow type is a structure designed for passing information to the MUI
Xtra about the characteristics of the window you want to display.
When you call IMuiDialog::Initialize()
, you pass
a populated instance of this structure to define these characteristics
through the pWindow
parameter.
The fields of the TMuiWindow
structure include:
Field | Type | Description |
iStructSize |
MoaLong |
use to determine version of struct, = sizeof(TMuiWindow) |
iType |
TMuiWindowType |
window type (one of kMuiWindowType_None , kMuiWindowType_Palette , kMuiWindowType_Standard , or kMuiWindowType_NonMovable ) |
pTitle |
ConstPMoaChar |
name of window, set to NULL for none |
iLayout |
TMuiLayoutType |
how to layout the widgets (one of kMuiLayout_Dynamic , kMuiLayout_DialogUnit , kMuiLayout_Pixel , kMuiLayout_Resource , or kMuiLayout_MAX ) |
iPosition |
TMuiWindowPosition |
if this set, the iXPosition and iYPosition fields may be ignored (one of kMuiWindowPosition_Alert , kMuiWindowPosition_Centered ) |
iXPosition |
MoaLong |
position of upper left of window, from upper left of dialog, NULL = Center |
iYPosition |
MoaLong |
position of upper left of window, from upper left of dialog, NULL = Center |
iWidth |
MoaLong |
pixel width of window, NULL = automatic |
iHeight |
MoaLong |
pixel height of window, NULL = automatic |
bModal |
MoaBool |
TRUE if modal |
bToolTipsOn |
MoaBool |
TRUE if dialog should display tool tips initially |
bHasCloseBox |
MoaBool |
TRUE if dialog has close box |
bCanZoom |
MoaBool |
TRUE if window zooms |
The iLayout
entry kMuiLayout_Dynamic
supports automatic layout of dialog boxes. This provides a convenient
way to build a dialog box without having to design the position
and size of all widgets. The automatic layout feature is described
in more detail in the following discussion.
The TMuiItem type
is a structure designed for passing information about the characteristics
of the widgets you want to display. When you call IMuiDialog::Initialize(),
you pass an array of instances of this structure through the pInputStrucArray[]
parameter, with one entry for each widget to appear in the dialog.
The fields of the TMuiItem
structure include:
iStructSize
MoaLong
vValue
MoaMmValue
iType
TMuiWidgetType
vAttributeList
MoaMmValue
pTitle
ConstPMoaChar
pToolTip
ConstPMoaChar
iXPosition
MoaLong
iYPosition
MoaLong
iWidth
MoaLong
iHeight
MoaLong
bEnabled
MoaBool
The iType
field of the TMuiItem
structure
represents the type of widget defined by the structure. The MUI
Xtra supports a number of widget types. The following table lists
the various types of widgets and the attributes they support.
Note that particular widget types support particular attributes,
which are described in greater detail below.
kMuiWidgetType_None
kMuiWidgetType_Void_VDivider
kMuiWidgetType_Void_HDivider
kMuiWidgetType_Bitmap
kMuiWidgetType_Actor
kMuiWidgetType_Boolean_Checkbox
kMuiWidgetType_Boolean_RadioButton
kMuiWidgetType_Enum_PopupList
kMuiWidgetType_Char_EditText
kMuiWidgetType_Label_Normal
kMuiWidgetType_Long_HSlider
kMuiWidgetType_Float_HSlider
kMuiWidgetType_Button_DefaultPushButton
kMuiWidgetType_Button_PushButton
kMuiWidgetType_Button_CancelButton
kMuiWidgetType_Button_Toggle
As noted in the list of widget types, certain widgets support
specific attributes. Widget attributes are defined through the vAttributeList
field of the TMuiItem
structure. The possible attributes and their values are:
Attribute | Values |
<textSize> | #large, #tiny, #normal (default) |
<textStyle> | [#bold, #italic, #underline, #plain (default)] |
<justification> | #left, #right, #center (defaults to system language standard) |
<popupStyle> | #tiny, #cramped, #normal (default) |
<valueList> | ["one", #two, 3, 4.0] (list of mmvalues, all coerced to strings) |
<valueRange> | [#min:0.0, #max:1000.0, #increment:1.0, #jump:10.0, #acceleration:0.5] |
<sliderStyle> | [#ticks, #value] |
<editStyle> | #VScrollBar, #HScrollBar, #BothScrollBars |
<bitmapStyle> | [#bitmapIcon: #stop/#note/#caution/#question/#error] |
<layoutStyle> | [#lockPosition, #lockSize, #center, #right, #left, #minimize] |
As indicated, some attributes have standard default values. For
these attributes, you need not provide an entry the vAttributeList
.
Entries in the vAttributeList
take the following
form:
[#attributeName:#valueName, ...]
Note that the layoutStyle
attribute applies to all
widget types except groups.
In addition to defining widget types, entries in the pInputStrucArray[]
parameter passed to IMuiDialog::Initialize()
can
define groupings of widgets. These groupings apply when the window's iLayout
field has been set to kMuiLayout_Dynamic
.
The MUI Xtra uses these groupings to determine how to organize
the layout of the widgets in the dialog.
The grouping entries in the array can include the following:
kMuiWidgetType_Group_WindowBegin
pInputStructArray
(always required) kMuiWidgetType_Group_WindowEnd
pInputStructArray
(always required) kMuiWidgetType_Group_HBegin
kMuiWidgetType_Group_HEnd
kMuiWidgetType_Group_VBegin
kMuiWidgetType_Group_VEnd
Each grouping of widgets is bracketed by the corresponding ...Begin
and ...End
pair, and groupings can be nested.
Note that you're always required to provide the entries kMuiWidgetType_Group_WindowBegin
and kMuiWidgetType_Group_WindowEnd
as the first and
last entries in the input structure array, regardless of whether
or not you're using automatic layout support.
To specify a group of radio buttons, enclose them in an HBegin/HEnd
or VBegin/VEnd
grouping. Any buttons within these
entries will be treated as mutually exclusive radio buttons (clicking
one deselects the previous selection), regardless of whether or
not you are using the automatic layout feature.
See beeptool.cpp in the BeepTool example for a complete initialization
sequence for an IMuiDialog instance.
As the user manipulates a dialog, the dialog generates a specific
set of events that represent user interaction with the widgets
it contains. For your Xtra to interact with these events, it implements
an IMoaNotificationClient
interface, and passes this interface to the dialog through the IMuiDialog::SetCallback() method.
Events are passed from the dialog to your notification client
in a TMuiEventRecord
structure, with the following definition:
typedef struct { MoaLong itemHit; TMuiDialogEvent event; PIMuiDialog pDialog; MoaLong reserved; } TMuiEventRecord;
The itemHit
field represents the index of the widget
in the pInputStrucArray[]
passed when the dialog
is iniatialized. You can use the itemHit
to index
into your stored array of widgets to get information about the
specific widget that received the event.
The event
field represents the type of event passed.
The possible types are listed in the following table, along with
the item represented in the itemHit
field and the
data passed in the refCon
parameter.
itemHit
kMuiDialogItemChanged
kMuiDialogItemClicked
kMuiDialogWindowOpening
kMuiDialogWindowClosed
kMuiDialogWindowResize
kMuiDialogWindowZoom
kMuiDialogItemEnteringFocus
kMuiDialogItemLosingFocus
Note: a modal dialog must handle at least one event by
stopping the dialog. Otherwise, the host application will hang.
Note: kMuiDialogItemChanged
and kMuiDialogItemClicked
are mutually exclusive. Widgets whose vValue
can
change (e.g., EditText, Slider) generate ItemChanged
events. Widgets such as bitmaps and default push buttons generate ItemClicked
events.
Here's a sample implementation of the notification client for
interacting with an IMuiDialog
.
STDMETHODIMP MyMuiDialog_IMoaNotificationClient::Notify( ConstPMoaNotifyID notifyID, PMoaVoid itemPtr, PMoaVoid refcon ) { X_ENTER // sanity if( !MoaEqualID(notifyID, &IID(IMuiDialog) ) ) X_RETURN(MoaError, kMoaErr_BadInterface ); PTMuiEventRecord item = (PTMuiEventRecord)itemPtr; MoaLong notifyCode = 0L; switch( item->event ) { case kMuiDialogItemClicked: // handle this event type; break; case kMuiDialogItemChanged: // handle this event type; break; case kMuiDialogWindowOpening: // handle this event type; break; case kMuiDialogWindowClosed: // handle this event type; break; case kMuiDialogWindowResize: // handle this event type; break; case kMuiDialogWindowZoom: // handle this event type; break; case kMuiDialogItemEnteringFocus: // handle this event type; break; case kMuiDialogItemLosingFocus: // handle this event type; break; default: break; } X_RETURN(MoaError, kMoaErr_NoErr); X_EXIT }
When implementing a dialog containing multiple widgets, you would include a secondary switch statement within each of the event cases above to determine the identity of the item being manipulated and perform operations specific to particular items.
Within your implementation of the Notify()
method,
you can update widgets in the dialog by calling the IMuiDialog::ItemUpdate()
method, passing the ID of the item to update and a a handle to
a TMuiItem
structure representing the new state of
the item.
One crucial bit of functionality in the Notify()
method is to enable the user to dismiss the dialog, generally
in response to clicking Update or Cancel buttons. To do so, you
call the IMuiDialog::Stop()
method.
When you've initialized the dialog and set its notification interface, you can display it.
To display a modal dialog, call the method IMuiDialog::Run()
.
This method blocks until the user dismisses the dialog.
To display a non-modal dialog, call the method IMuiDialog::WindowOp(),
passing kMui_WindowOp_Show
as the operation parameter.
This method returns immediately. To hide a non-modal dialog,
call the WindowOps()
method with kMui_WindowOp_Hide
as the operation parameter.
The IMuiAlert interface and MUI Xtra provide a platform-independent
mechanism to present user alerts from any MOA Xtra.
To create a MUI Alert, you first create an instance of the MUI
Xtra's Alert class and IMuiAlert
interface. To do
so, you call the IMoaCallback::MoaCreateInstance() method, passing CLSID_CMuiAlert
, the CLSID for the
Alert class, and IID_IMuiAlert
, the IID for the IMuiAlert
interface.
To invoke an alert, you call the one method of the IMuiAlert
interface, Alert()
.
The parameters to this method let you define the title of the
Alert window, the message and icon to display in the alert box,
the buttons to present the user, and the default button to activate
if the user presses Return.
An alert may display several different combinations of buttons, specified by the following constants:
kMuiAlertButtons_Ok
kMuiAlertButtons_OkCancel
kMuiAlertButtons_AbortRetryIgnore
kMuiAlertButtons_YesNoCancel
kMuiAlertButtons_YesNo
kMuiAlertButtons_RetryCancel
The return value of the Alert()
method represents
the left-to-right order of the button pressed in the alert dialog:
the first button in the lists above returns 1, the second returns
2, etc.
The IMuiFile
interface displays the standard system
file open and file save dialogs. It is available by calling IMoaCallback::CreateInstance()
with the class identifier CLSID_CMuiFile
and the
interface identifier IID_IMuiFile
. This interface
consists of two methods.
IMuiFile::SimpleFileOpen() displays the standard system dialog for opening files. IMuiFile::SimpleFileSave() displays the dialog for saving files. In both methods, you can
pass in a user prompt string and an IMoaPathName interface representing the default path, or pass NULL to let the
MUI Xtra allocate a path name interface for you. (In either case,
you own the returned IMoaPathName
interface and must
release it when you're through with it.) The value returned in
the path name represents the user's selection. Use this interface
in conjunction with the Moa File Support II API to open the file specified by the user.
The IMuiURL
interface displays displays the standard
system file open and file save dialogs. It is available by calling IMoaCallback::CreateInstance()
with the class identifier CLSID_CMuiURL
and the interface identifier IID_IMuiURL
.
This interface consists of two methods.
IMuiURL::ModalGetURLPath() displays a modal dialog for getting URLS. IMuiURL::MovableGetURLPath() displays a movable dialog for getting URLS.