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:
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.
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:
Field | Type | Description |
iStructSize | MoaLong | Determine version of struct, = sizeof(TMuiWindow) |
vValue | MoaMmValue | initial value/data to be modified. When an ItemChanged event is passed back to the NotificationClient, this value is updated to represent the change. |
iType | TMuiWidgetType | contextual: if data driven, a widget TIMui_WidgetType; if DU driven, a widget TIMui_WidgetType; if Pixel driven, a widget TIMui_WidgetType; if resource driven, a resource ID |
vAttributeList | MoaMmValue | contextual: if enum list of valid values; if int/float list with min 1st, and optionally, max 2nd; if a label, a list with #center, #right, and #left for justification. |
pTitle | ConstPMoaChar | widget title, NULL no title |
pToolTip | ConstPMoaChar | string with tool tip to display when floating over, NULL = not tip |
iXPosition | MoaLong | position of upper left of item, from upper left of dialog |
iYPosition | MoaLong | position of upper left of item, from upper left of dialog |
iWidth | MoaLong | pixel width of item, NULL = automatic |
iHeight | MoaLong | pixel height of item, NULL = automatic |
bEnabled | MoaBool | the UI information related to value |
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.
Widget type | Title | Attributes |
kMuiWidgetType_None | No | none |
kMuiWidgetType_Void_VDivider | No | none |
kMuiWidgetType_Void_HDivider | No | none |
kMuiWidgetType_Bitmap | No | <bitmapStyle> |
kMuiWidgetType_Actor | ? | ? |
kMuiWidgetType_Boolean_Checkbox | Yes | <textSize> |
kMuiWidgetType_Boolean_RadioButton | Yes | <textSize> |
kMuiWidgetType_Enum_PopupList | No | <popupStyle><valueList> |
kMuiWidgetType_Char_EditText | No | <textSize><justification><editStyle> |
kMuiWidgetType_Label_Normal | No | <textSize><justification><editStyle> |
kMuiWidgetType_Long_HSlider | No | <sliderStyle><valueRange> |
kMuiWidgetType_Float_HSlider | No | <sliderStyle><valueRange> |
kMuiWidgetType_Button_DefaultPushButton | Yes | <textSize> |
kMuiWidgetType_Button_PushButton | Yes | <textSize> |
kMuiWidgetType_Button_CancelButton | Yes | <textSize> |
kMuiWidgetType_Button_Toggle | Yes | <textSize> |
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:
Layout grouping type | Purpose |
kMuiWidgetType_Group_WindowBegin | First entry in the pInputStructArray (always required) |
kMuiWidgetType_Group_WindowEnd | Last entry in the pInputStructArray (always required) |
kMuiWidgetType_Group_HBegin | Entry preceding a group of widgets arranged horizontally |
kMuiWidgetType_Group_HEnd | Entry following a group of widgets arranged horizontally |
kMuiWidgetType_Group_VBegin | Entry preceding a group of widgets arranged vertically |
kMuiWidgetType_Group_VEnd | Entry following a group of widgets arranged vertically |
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.
Event type | itemHit | Data in refCon |
kMuiDialogItemChanged | item changed | - |
kMuiDialogItemClicked | item clicked | - |
kMuiDialogWindowOpening | - | - |
kMuiDialogWindowClosed | - | - |
kMuiDialogWindowResize | - | PMoaRect |
kMuiDialogWindowZoom | - | PMoaRect |
kMuiDialogItemEnteringFocus | item about to get focus | - |
kMuiDialogItemLosingFocus | item about to lose focus | - |
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 ) { // sanity if( !MoaEqualID(notifyID, &IID(IMuiDialog) ) ) return 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; } return kMoaErr_NoErr; }
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:
Constant | Buttons |
kMuiAlertButtons_Ok | 1: OK |
kMuiAlertButtons_OkCancel | 2: OK, Cancel |
kMuiAlertButtons_AbortRetryIgnore | 3: Abort, Retry, Ignore |
kMuiAlertButtons_YesNoCancel | 3: Yes, No, Cancel |
kMuiAlertButtons_YesNo | 2: Yes, No |
kMuiAlertButtons_RetryCancel | 2: Retry, Cancel |
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.