November 93 - TDialogBehaviors
This article is the first article in what I hope will be a regular series of technical questions and answers on object oriented programming. The intent of this column is to go beyond simple answers. I intend to take a question, answer it, and then use that question as a springboard to a more general discussion on programming. I hope you find the results interesting.
The first articles will be culled from frequently asked questions on MacApp3Tech$, but I need your questions! I can be reached electronically at AppleLink: B.HABLUTZEL; by telephone at 708.328.0130; or by post at Bob Hablutzel, Hablutzel Consulting, 606 Asbury, Evanston, IL, USA 60202.
Q: I need to create a modal dialog using MacApp 3.0.
I create the dialog using ViewEdit, but when I
attempt to pose the dialog it opens briefly and immediately closes. How can I create a modal dialog?
A: Modal dialogs in MacApp 3.0 are handled with a
TDialogBehavior, which is attached to the dialog
window. This behavior is responsible for receiving and handling keystrokes, looking for keystrokes that dismiss the dialog, and sending events off to the appropriate control.
The problem with ViewEdit (in this case) is that it does not attach a TDialogBehavior to the dialog when it is created. When TWindow::PoseModally() is called, the first thing it does is attempt to locate the dialog behavior; if this lookup fails it closes the window and returns immediately (returning kNoIdentifier as the dismisser).
There are a few work-arounds for this. In ViewEdit, you can add a TDialogView to the window. TDialogView is really not required in MacApp 3.0; it is a holdover from the old mechanisms in MacApp 2.0. However, if there is one in the window, it will cause the TDialogBehavior to be added when the window is opened.
Alternatively, you can create the TDialogBehavior yourself, and attach it to the window before the TWindow::PoseModally() method is called. When you create the dialog behavior, you have to supply the identifiers for the default and cancel items (in the call to IDialogBehavior()). Once this behavior is added to the window, TWindow::PoseModally() can be called.
You can also call TWindow::SetModality() before calling TWindow::PoseModally(). This method will create the dialog behavior if none exists. However, this routine may not properly set up the default and cancel identifiers; you would then have to call TWindow::GetDialogBehavior() to retrieve the dialog, and stuff the identifiers into its fCancelItem and fDefaultItem fields.
Even if you do all of this, the dialog will still not dismiss properly unless you change the default event for the dismissing control to mDismiss (==34). So if you use ViewEdit to create the dialog, you need to change the event number for the control by hand. If you leave the control at its default event number (mButton for TButtons), the control will activate, but the dialog will not dismiss.
Finally, the best solution is to avoid using ViewEdit. Either AdLib or IcePick (3.0) will add the dialog behavior to the window when you use them to create the dialog. Using either of these products will ensure that the dialog has the appropriate behavior. These programs will also take care of changing the event number for the dismissing controls to mDismiss for you. (Both these applications are available from MADA).
More About TDialogBehavior
It is somewhat interesting to notice the actual mechanism used to handle the dismissing of the modal dialogs. The TDialogBehavior does not in itself dismiss the dialog, which as we will see in a second has some interesting implications. The TDialogBehavior simply activates the control that is designated as the default (or cancel) item. It does this by sending the control its default event number. The control then accepts the event, reacts appropriately (in the case of a TButton, it flashes), and sends the event up the event chain.
The event eventually reaches the TDialogBehavior attached to the window, which checks the see if the event is mDismiss. Notice that this is the first time that the behavior checks the event type. If the event is mDismiss, the behavior records the identifier of the source of the event in the fDismisser field, and ends the modal posing. TWindow::PoseModally(), which started the modal posing in the first place, retrieves the value of the TDialogBehavior::fDismisser field, and returns that as the result of the modal posing.
What is interesting about all this is that TDialogBehavior does not necessarily have to be used with modal dialogs; it can be used with modeless dialogs just as easily. When the return key is struck, for example, the default item will be invoked. If you attach a behavior to the default control that intercepts that control's default event number, you can quickly and easily create modeless dialogs that contain default (and closing) items.
Take, for example, a drawing application that supports 1° rotations. A modeless dialog could be created that presents the user with the number of degrees of rotation, and a default Rotate button. Every time the user strikes the return key, the Rotate button would be activated. You could attach a behavior to the Rotate button that checks for events where (a) the source of the event is the owner of the behavior, and (b) the event number matches the default event number (fEventNumber) of the owner. When it receives an event that matches this criteria, it would create whatever command was responsible for the rotation of the object, and post it to the application.
The question of where to attach the behavior is an interesting one. The behavior can be attached anywhere in the event chain and still function properly. It is mostly a question of style to decide where the behavior best fits.
For example, if the behavior is attached to the button itself, it will clearly get the event that the button generates. However, if the button does not handle the event, it will pass the event up the event chain; for views this means that the superview will receive the event. This passing along continues through each respective superview until someone handles the event, the TWindow used to draw the dialog will get the event eventually, provided no-one else has handled it.
In the example above, there are two ways of designing the interface. If the TNumberText used to hold the rotation amount is just a generic TNumberText, then it would make sense to have the behavior attached to the dialog. This would allow the dialog access to a child view to retrieve the rotation amount. (If the behavior were attached to the button, it would have to access a sibling view to retrieve the rotation amount; there is nothing actually wrong with this but it forces the dialog to have additional information about its environment, which will limit its overall reusability).
However, if the TNumberText holding the rotation amount where overridden to set a value in the application (fRotationAmount, e.g.) when stopping editing, then the behavior could be attached to the button. In this case, the button would be set to want to become the target of the view. When the user clicks this button, the TNumberText would resign its target, which would cause it to stop editing, which in turn would cause it to update the application value. The button would then be free to post a command using this value.
Finally, we can take this one step further, and change the default event number of the button from mButtonHit to some application defined event (mRotate, e.g. ). We could then attach a behavior to the application that looks for the mRotate event and creates the appropriate command. This would allow us the flexibility of generating the mRotate command in multiple places in our interface, and handling them all identically. (Remember that the dialog we are discussing is modeless; this would not work in a modal dialog as it requires the event number of the default button to be mDismiss).
Once you understand how they function, TDialogBehaviors provide a simple, generic means of handling a common user interface problem. By carefully using them in cooperation with other built-in mechanisms, powerful interfaces can be designed with a minimum of coding. They can be used with modeless as well as modal dialogs, giving you complete freedom in designing your interface.