| Dialogs | Chapter 9 | Contents |
|---|
|
Inside Macintosh |
Window Manager Dialog Manager Control Manager |
| Mops |
Windows Controls |
Class Dialog is, like Menu, a subclass of X-Array. Dialogs are similar to menus in that they have items associated with them that can be selected by the user. Dialog items can be controls, static (non-editable) text, editable textPICTs, Icons or be user-defined. A dialog item is selected by pressing the mouse button in the region assigned to the item; if an item is enabled, it will cause the Dialog Manager to return immediately to the caller with the number of the item clicked on. Text-Edit items are normally not enabled, so do not return immediately, but wait for the dialog to be terminated by a carriage return or clicking the OK button.
Macintosh dialogs can be modal or modeless. Mops's basic Dialog class supports modal dialogs, which do not allow the user to activate a different window while the dialog is active. Subclass Dialog+ adds the necessary support for modeless dialogs, which allow the user to activate a different window, select a menu or do anything else while they are active.
Note that Apple recommend that you use modeless dialogs by preference, since they are more user friendly. They recommend you reserve modal dialogs for unusual situations where a user response must be obtained before the program can proceed (although in this situation an Alert box may well be more appropriate).
Dialogs are heavily dependent upon resource definitions for the window and the item list. You can use ResEdit to create resources of type DLOG and DITL, and then store the resource ID (of the DLOG resource) in a Mops object of class Dialog (see IM - Dialog Manager). The items in a dialog's item list are not defined as control objects in Mops, because they can more easily be accessed via methods in class Dialog itself. A Dialog object's indexed cells are loaded with the xts of Mops words, one per item. For example, the handler for a Control of type CheckBox might be to get: the value of the control, XOR it with itself, and put: the result back in the control. This would result in toggling the value of the control between 0 and 1, turning the check mark off and on. The value of the checkBox could be used to set a program parameter when the user leaves the dialog.
For modal dialogs, once getNew: has been sent to fire up the dialog, you should send a modal: method to the dialog. This calls the Toolbox routine ModalDialog, which initiates the Dialog Manager's event loop, which handles events until the user clicks on a dialog item. Your handler for that item will then be executed. Each handler must end in one of two ways. If the item chosen indicates that the user wants to leave the dialog, and the data provided by the user is acceptable, the handler should send a close: message to its dialog, which will make the window disappear and release the heap storage for the Toolbox data. Otherwise, the handler should use the word ReturnToModal before it returns. This will signal the modal: method, which is still active, to loop and call ModalDialog again. Otherwise the modal: method will return to its caller.
Modeless dialogs don't require modal:, of course. Before you send getNew: to a modeless dialog to fire it up, you should execute the word +MODELESS, which modifies Mops' event handling so that it recognizes events relating to modeless dialogs. When you are finished with all your modeless dialogs, you may execute -MODELESS to restore the original event handling, but there is really no need to do so as the additional over-head is minimal.
Item data can be accessed via get: and put: messages to the dialog, which assume that the item is a control; for Text-Edit items, use getText: and putText:. SetSelect: will set the selection range for a Text-Edit item. If you need to perform operations not provided in class Dialog, you can either get the handle for the item via the Handle: method, and call the Toolbox directly, or you can define a subclass of Dialog that has additional item methods.
Alerts are very similar to Dialogs in implementation, with the exception that loading the Alert and entering the modal event loop are accomplished in a single operation via the show: message. You must have a resource definition of type ALRT in your resource file with an associated item list. The init: method of class Alert accepts both a resource ID and a type code; the type determines which icon will be printed in the upper-left corner of the alert:
| Type = | 0 | Caution Alert | Because it is loaded and executed in a single operation, you cannot modify the item list for an Alert in memory. Therefore, you should create item lists containing the exact information for each alert in your application. You could, of course, also define a subclass of Alert that separates the loading and event-handling operations. |
| 1 | Note Alert | ||
| 2 | Stop Alert | ||
| >2 | no icon |
Also provided is Alert" which gives you a predefined alert box without having to define any resources. You can use Alert" in place of Abort" in your application to better comply with the Mac user interface guidelines. However, Alert" is still rather “quick and dirty”; it is best of all to create custom alert boxes.
| Dialog |
Dialog implements a modal dialog object by associating the Toolbox dialog data with an X-Array containing the dialog's item handlers.
| Superclass | X-Array | |||||||||||||
| Source file | Dialog, DialogMod.txt | |||||||||||||
| Status | Optional |
| ||||||||||||
| Instance variables | ||||||||||||||
| Indexed data | 4-byte cells (must be xts) | |||||||||||||
| System objects | None |
X-Array, Array, Indexed-Obj, Object
| initialization | ||
| init: | ( <xt list> resID -- ) | Sets the dialog's item handlers and resource ID of the dialog's DLOG resource |
|---|---|---|
| setBold: | ( item# -- ) | Sets the item to be boldly outlined when the dialog is drawn |
| setProc: | ( xt -- ) | Sets the filterProc to be used by modal. This must be a :PROC definition |
| putResID: | ( resID -- ) | Sets the resource ID for the dialog |
| runtime control | ||
| getNew: | ( -- ) | Loads the resource template for the dialog and displays its window as the frontmost window. No key event can be processed after getNew: is issued and before modal: is issued. (This means a getNew:, modal: sequence must be typed on one line if executed from the Mops prompt.) |
| modal: | ( -- ) | Enters the Dialog Manager's modal event handler, which will beep whenever the user tries to click the mouse outside of the dialog window. If a click occurs inside an enabled item, the dialog will execute the handler corresponding to that item, which should either send a close: to close the dialog or use ReturnToModal |
| close: | ( -- ) | Closes the dialog window and disposes of the associated heap. |
| manipulation | ||
| show: | ( -- ) | If the dialog resource is set to be initially invisible, you will want to show: it when all the items are drawn. It makes for a nicer build creation appearance |
| hide: | ( -- ) | Makes the dialog invisible |
| accessing items | ||
| getItem: | ( item# -- val ) | Gets the value of a control item (numbered from 1 to N) |
| putItem: | ( val item# -- ) | Sets the value of a control item |
| getText: | ( item# -- addr len ) | Returns the text string for an item |
| putText: | ( addr len item# -- ) | Sets the text string for an item |
| setSelect: | ( start end item# -- ) | Sets the selection range for an editable text item |
| dlgPtr: | ( -- ^dlg ) | Returns the pointer to the dialog (after getNew: has been called) |
| itemHandle: | ( item# -- hndl ) | Returns the handle to the given item. TempRect is also set to the item's rectangle, and the item's type put in the Int ItemType |
| open?: | ( -- b ) | Returns true if the dialog is open. |
| drawing | ||
| draw: | ( -- ) | Forces drawing of the dialog without (or before) executing modal:. Useful in non-modal (or pre-modal ) situations |
| set: | ( -- ) | Same as set: for class Window. Any text will be output to the dialog object |
| drawBold: | ( -- ) | Draw the frame around the boldened OK button. Normally called automatically—from getNew:, and also, if this is a modeless dialog, in response to an update event |
| setUserProc: | ( ^proc item# -- ) | Sets the :proc routine for a user item |
| manipulating individual items | ||
| hideItem: | ( item# -- ) | Hides the item |
| showItem: | ( item# -- ) | Shows the item |
| disableItem: | ( item# -- ) | Disables the item. Only use for items that are Controls. The control will be dimmed and not respond to clicks |
| enableItem: | ( item# -- ) | Enables the item; again, only for Controls. Do not confuse this enabled with the general use of the word in ResEdit for Dialog items, where it means whether or not the items will ever return clicks. Our use of enabled and disabled for controls means active and inactive, in Inside Macintosh terms |
| hitBold: | ( -- ) | Acts as if the bold item has been clicked, and executes the corresponding item handler. Call this if Return or Enter is typed while the dialog is active. Does nothing if there isn't a bold item |
| key: | ( -- b ) | Called when a key down event occurs with this dialog's window active. Returns false if we've handled the key here, so no further action is required. Subclasses can have customized key: methods; here we just provide a hopefully sensible default action—namely, we treat a Return or Enter as a click on the bold item, and ignore all other keys. |
| manipulating the dialog's window | ||
| title: | ( addr len -- ) | Sets the title of the dialog |
| maxX: | ( -- x ) | Sends max?: to the dialog's window |
| maxY: | ( -- y ) | |
| move: | ( x y -- ) | Moves the dialog so that its top left corner is at the given coordinates |
| center: | ( ???) | Centers the dialog on the screen, by sending center: to the dialog's window |
| select: | ( -- ) | Makes this dialog the frontmost window. |
| global parameters | ||
| ParamText | ( addr0 len0 addr1 len1 addr2 len2 addr3 len3 -- ) | This is a word, not a method. Calls the Dialog Manager routine ParamText which defines dialog text substitution strings. All sub-sequent static or editable text in dialogs will automatically substitute strings 0 through 3 for occurrences of "^0", "^1”, "^2”, and "^3", respectively. NOTE: the combined length of the four strings must be less than or equal to 252 bytes |
| theItem, itemType, itemHandle | These are objects (see source file Dialog) holding parameters for selected items. | |
| Dialog+ |
Dialog+ adds support for modeless dialogs and pop-up menu dialog items.
| Superclass | Dialog | |||||||||||||
| Source file | Dialog+ | |||||||||||||
| Status | Optional |
| ||||||||||||
| Instance variables | ||||||||||||||
| Indexed data | 4-byte cells (must be xts) | |||||||||||||
| System objects | None | |||||||||||||
Dialog, X-Array, Array, Indexed-Obj, Object
| runtime control | ||
| getNew: | ( -- ) | Loads the resource template for the dialog and displays its window as the frontmost window. It will be a modeless dialog. Provided +MODELESS has been executed, all dialog events such as updates or clicks on the dialog's items will be handled automatically. |
|---|---|---|
| manipulation | ||
| close: | ( -- ) | Closes the dialog and releases its storage |
| disable: | ( -- ) | Disables the dialog. It will still respond to update events, but not to clicks |
| enable: | ( -- ) | Enables the dialog. It will respond to all events as normal |
| exec: | ( item# -- ) | If the dialog is enabled, executes the handler for the given item. Otherwise does nothing |
| enabled?: | ( -- b ) | Returns true if the dialog is enabled |
| Alert |
Alert loads and displays alerts defined in a resource file.
| Superclass | X-Array | |||||||
| Source file | Alert | |||||||
| Status | Optional |
| ||||||
| Instance variables | ||||||||
| Indexed data | 4-byte cells (must be xts) | |||||||
| System objects | None | |||||||
X-Array, Array, Indexed-Obj, Object
| initialization | ||
| init: | ( resID type -- ) | Sets the icon type and resource ID of the Alert. runtime control |
|---|---|---|
| show: | ( -- ) | Loads the Alert from a resource file, and enters the Dialog Manager's modal event loop. Item handlers are executed as in Dialog, above |
| disp: | ( resId type -- ) | Combines the actions of init: and show:. |
| Previous Chapter | Contents | Next Chapter |
|---|---|---|
| ⇧ | ||
| This page online: http://PowerMops.com/MopsManual/Classes/Chapter9.html | ||