Modal Dialogs

Making your own modal dialogs

The default behaviour of all windows you create (even Dialog objects) is non-modal, which means that the user can activate other windows and menus. Often, this behaviour is preferred, since it gives the user more control over the application. Sometimes, however, you may wish a dialog to be modal, which means that the user must close the dialog (typically by clicking in an OK or Cancel button) before continuing with other tasks. In addition, you might want your program to wait until the dialog has been closed before proceeding. These two features are logically separate, but often go together. You make the dialog modal by invoking the Wait method on it, and you cause your program to wait for the dialog to be closed by calling ⎕WE with a right argument which is the name of the window. The following is a complete example of a function which puts up a modal dialog containing a label and two buttons. The function then waits until the user has responded, and returns 1 if the user presses the 'Yes' button or 0 if he presses the 'No' button.

    ∇R←ASK;X;MyDlog
[1] ⍝ Example of a modal dialog
[2]  MyDlog←'⎕' ⎕NEW 'Dialog' ⋄ MyDlog.size←5 34
[3]  MyDlog.Label.New 'Label' ⋄ MyDlog.Label.where←0.5 4 1.5 30
[4]  MyDlog.Label.caption←'Do you want to erase this file?'
[5]  MyDlog.No.New 'Button' ⋄ MyDlog.No.where←3 3 1.5 8 ⋄ MyDlog.No.style←2
[6]  MyDlog.Yes.New 'Button' ⋄ MyDlog.Yes.where←3 23 1.5 8 ⋄ MyDlog.Yes.style←1
[7]  MyDlog.No.onClick←'R←0 ⋄ MyDlog.Close'
[8]  MyDlog.Yes.onClick←'R←1 ⋄ MyDlog.Close'
[9]  MyDlog.Wait
[10] R←0
[11] X←⎕WE MyDlog
    ∇

In this function, line [9] causes the dialog to be modal, and line [11] causes the function to wait until the Dialog object MyDlog has been closed (or hidden), executing any callbacks which are invoked as a result of events that come in. The Dialog object can be closed under program control, by calling the Close method. In this example, this happens when either of the Yes or No buttons is clicked, which causes the onClick handler to be invoked, as set up in lines [7] and [8]. If the user presses the 'Yes' button, the APL function behaves very much as though line [11] was:

[11] ⍎'R←1 ⋄ MyDlog.Close'

which has the effect both of setting the explicit result of the function and closing the dialog.

Pre-defined modal dialogs

As an alternative to creating your own modal dialogs, you can often use one of the pre-defined dialog objects which are built-in to APLX. These include MsgBox, ChooseFont, ChooseDir, ChooseColor, OpenFile and SaveFile. To use these, you create an instance of the object, set the properties you want, and then call the Show method. This displays the dialog modally, and returns an integer indicating which button was used to exit. Where appropriate, you can then read the properties to see what the user selected. The above example can be written more simply as:

      ∇R←ASK;MBOX
[1]  ⍝ Modal dialog using the MsgBox object
[2]   MBOX←'⎕' ⎕NEW 'MsgBox' ⋄ MBOX.style←3 ⋄ MBOX.icon←1 
[3]   MBOX.text←'Do you want to erase this file?'
[4]   R←6=MBOX.Show
      ∇