Creating Dialog Boxes
In
Mathematica, dialog boxes are customized notebooks used to provide users with information and/or request user input.
There are two properties associated with dialogs.
| modal | prevents access to other elements of the front end until the dialog is closed and must be explicitly set using the option Modal |
| blocking | blocks the kernel until the dialog is closed |
Dialog properties.
A modal dialog forces the user to respond to the dialog before doing anything else. This allows the front end to acquire the information necessary to either complete or initiate an evaluation. For example, when most applications close, a modal dialog will appear, prompting the user to save changes. Since the response is crucial in determining how the application should close, the dialog will prevent access to the other parts of the program until the user has responded to it. Setting the option
Modal->True will make a dialog modal.
Note: Modal dialogs will prevent users from accessing other notebooks in the front end while the dialog is open. If there is no mechanism for closing the dialog,
Mathematica will effectively freeze.
A blocking dialog halts a running evaluation until the user responds to it, but does not prevent access to other parts of the front end. The kernel in which these dialogs are evaluated will effectively block until the dialog is closed. For example, a choice dialog will start an evaluation, wait until the user chooses a value, and then complete the evaluation by returning the value. Any other evaluations that are sent through the main link while the dialog is open will be queued and evaluated once the dialog is closed.
Some dialogs are neither modal nor blocking, such as the system find dialog and message dialogs.
Dialog Buttons
Dialogs typically include buttons to allow users to respond to a question, a message, or other requested input. One of these buttons is the default action and is highlighted when the dialog opens. Another button that is almost always present is the cancel button, which will close the dialog and abort the dialog's action.
In
Mathematica, the default and cancel buttons can be created using a series of streamlined functions.
| DefaultButton[] | OK button that closes a dialog and is the default when Enter is pressed |
| DefaultButton[action] | button labeled OK that evaluates action whenever it is clicked or Enter is pressed |
| DefaultButton[label,action] | button labeled label that evaluates action whenever it is clicked or Enter is pressed |
| CancelButton[] | Cancel button that closes a dialog and is the default when Esc is pressed |
| CancelButton[action] | button labeled Cancel that evaluates action whenever it is clicked or Esc is pressed |
| CancelButton[label,action] | button labeled label that evaluates action whenever it is clicked or Esc is pressed |
| ChoiceButtons[] | pair of OK and Cancel buttons |
| ChoiceButtons[{actok,actcancel}] | OK and Cancel buttons that evaluate the corresponding  when clicked |
| ChoiceButtons[{lblok,lblcancel},{actok,actcancel}] |
| OK and Cancel buttons with label  that evaluate the corresponding  when clicked |
Dialog buttons.
In dialogs created using
DialogInput or
CreateDialog, pressing
Enter is equivalent to clicking the
OK (default) button and pressing
Esc is equivalent to clicking the
Cancel button. If there are several default buttons in a single dialog,
Enter will use the first one in the dialog. Similarly, pressing
Esc will use the first
Cancel button in the dialog.
Create a cancel button and a default button in a row.
| Out[6]= |  |
ChoiceButtons will display the default and cancel buttons in the standard order for the current computer system.
| Out[3]= |  |
Dialog Notebooks
Dialog notebooks can be opened as a separate window in the front end as a notebook or in-cell expression. Dialog notebooks are non-blocking dialogs that may or may not be modal.
| CreateDialog[expr] | create and open a dialog notebook containing expr in the front end |
| DialogNotebook[{cell1,cell2,...}] | an in-cell representation of a dialog notebook that can be manipulated by the front end |
| MessageDialog[expr] | create and open a message dialog notebook containing expr in the front end |
| DialogReturn[expr] | close a dialog window and return the expression expr from the dialog |
| Modal | option for CreateDialog specifying whether the dialog created should be modal to the front end |
Dialog notebook functions.
Note: Modal dialogs will prevent users from accessing other notebooks in the front end while the dialog is open. If there is no mechanism for closing the dialog,
Mathematica will effectively freeze.
Here is a dialog that displays a notification or message.
Set
Modal->True to make the same dialog modal.
Alternatively this creates an in-cell representation of the dialog notebook. A separate window containing the notebook can be opened in the front end by clicking the
{}[[3]] button or wrapping
CreateDialog around the
DialogNotebook expression.
| Out[43]= |  |
Dialogs that display a message can also be created using
MessageDialog, which includes the
DefaultButton by default.
Here is a message dialog informing a user that a calculation is complete.
| Out[4]= |  |
Sometimes it is useful to also include an audible beep with the message dialog using
Beep.
| Out[3]= |  |
In addition to accepting input, dialog boxes can also evaluate expressions when they are closed. This can be done using
DialogReturn. Here is a modal dialog box that accepts user input and evaluates a variable assignment.
Type a first and last name into the input fields and click
OK to assign the input values to
name.
| Out[22]= |  |
Several front end dialogs such as the
Mathematica Preferences dialog were created using
CreateDialog.
Blocking Dialogs
The kernel in which blocking dialogs are evaluated is blocked until the dialog is closed.
| DialogReturn[expr] | close a dialog window and return the expression expr from the dialog |
| DialogInput[expr] | put up expr as a dialog notebook, wait until DialogReturn[e] is evaluated, then return the result e |
| ChoiceDialog[expr] | create and open a choice dialog notebook containing expr in the front end |
Blocking dialog functions.
Block the kernel until
val is set to 123.
| Out[53]= |  |
Here, the kernel is blocked until the user sets a value to
removeQ by selecting
Cancel or
OK.
| Out[7]= |  |
Dialogs that display a choice can also be created using
ChoiceDialog, which blocks the kernel and returns
False if the
CancelButton is selected or
True if the
DefaultButton is selected.
| Out[4]= |  |
If the blocking dialog is thrown by a button or action menu, pass the button action along the main link to prevent timing out. This can be done by setting
Method
.
| Out[1]= |  |
| Out[3]= |  |
System Dialogs
Mathematica also offers access to system dialog through the use of
SystemDialogInput, front end tokens, and user interface-specific button functions including
FileNameSetter,
ColorSlider, and
ColorSetter.
Accessing common system dialogs programmatically.
Here is the system file open dialog that returns the file path for the chosen file.
| Out[19]= |  |
exhibits the same behavior as
by returning the file path for the chosen file.
| Out[29]= |  |
This opens the system color dialog and returns the
RGBColor value for the selected color.
| Out[15]= |  |
The front end token
opens the system print dialog and prints the notebook when the user selects
Print.
| FileNameSetter[name,"Open"] | create a Browse button to open the system file open dialog and save the value to name |
| FileNameSetter[name,"OpenList"] | create a Browse button to open the system multiple file open dialog and save the value to name |
| FileNameSetter[name,"Save"] | create a Browse button to open the system file save dialog and save the value to name |
| FileNameSetter[name,"Directory"] | create a Browse button to open the system directory picking dialog and save the value to name |
| ColorSetter[color] | create a swatch button set to color that opens the system color picker dialog when clicked |
| ColorSlider[color] | create a color slider set to color that opens the system color picker dialog when double-clicked |
Accessing common system dialogs using existing button functions.
Here is a button that opens the system file open dialog and assigns the file path for the chosen file to a dynamic variable.
| Out[14]= |  |
calls the system multiple file open dialog instead.
| Out[15]= |  |
exhibits the same behavior as
by assigning the file path for the chosen file to a dynamic variable.
| Out[16]= |  |
This creates a button that opens the system directory picking dialog and assigns the file path for the chosen directory to a dynamic variable.
| Out[17]= |  |
Here is a color swatch that can be used to assign the value of a dynamic variable to an RGB color. Clicking the swatch will open the system color picker dialog.
| Out[20]= |  |
ColorSlider is a control object that contains the
ColorSetter swatch as well as a color spectrum. Double-clicking the spectrum will open the system color picker dialog.
| Out[21]= |  |
Mathematica Input Dialogs
Mathematica usually works by taking whatever input it is given and then processing it. Sometimes, however, programs may need to explicitly request more input. This can be done using
Input and
InputString.
| Input[] | read a complete expression as input |
| Input[prompt] | request input, displaying prompt as a "prompt" |
| Input[prompt,init] | request input, displaying prompt as a "prompt" with init as the initial contents of the input field |
| InputString[] | read a character string as input |
| InputString[prompt] | request input, displaying prompt as a "prompt" |
| InputString[prompt,init] | request input, displaying prompt as a "prompt" with init as the initial contents of the input field |
Requesting input dialogs.
Note: With a text-based interface,
Input and
InputString will just wait for standard input, terminated by a newline. See
"Requesting Input" for more information.
This returns the polynomial expansion of the input.
| Out[3]= |  |
Here the inputted string is split into a list of substrings.
| Out[5]= |  |
Extended Examples
Progress Dialog
Here is a progress dialog that tracks the value of the dynamic variable
during a computation.
Save Dialog
This is a modal dialog that will save the inputted notebook if the user selects
Save or abort the operation if the user instead chooses
Cancel.
Find Dialog
This next example is a find dialog similar to those found in many applications.
Memory Usage Dialog
Mathematica can track the amount of memory being used by the front end and kernel processes at any given time. Here is a dialog that displays that data in real time.
