MUI Developer's Guide
MUI Interfaces | MUI Methods | MUI Types and Misc API

Director Xtra Development Kit

MUI (Macromedia User Interface) Developer's Guide


This document contains the following sections:


Introduction

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.


Dialog Boxes

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.

Creating a Dialog Box

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);

Initializing a Dialog Box

To initialize a dialog box, you call IMuiDialog::Initialize(), passing parameters to define the window and the widgets that appear in it.

Defining the Window

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.

Defining widgets in a dialog

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


Types of widgets

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>


Widget attributes

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.

Automatic layout support

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.

Dialog initialization example

See beeptool.cpp in the BeepTool example for a complete initialization sequence for an IMuiDialog instance.

Dialog notification

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.

Implementing the Notification Client

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 )
{
        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.

Displaying a dialog

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.


Alerts

The IMuiAlert interface and MUI Xtra provide a platform-independent mechanism to present user alerts from any MOA Xtra.

Creating an Alert

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.

Invoking the Alert

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.

Alert buttons

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.


MUI File Dialogs

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.


MUI URL Dialogs

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.


Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.