Creating Dialog Boxes
| Dialog Buttons | System Dialogs |
| Dialog Notebooks | Wolfram System Input Dialogs |
| Blocking Dialogs | Extended Examples |
In the Wolfram System, dialog boxes are customized notebooks used to provide users with information and/or request user input.
| 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 |
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, the Wolfram System 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.
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 the Wolfram System, 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 acti when clicked |
| ChoiceButtons[{lblok,lblcancel},{actok,actcancel}] | |
OK and Cancel buttons with label lbli that evaluate the corresponding acti when clicked | |
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.
ChoiceButtons will display the default and cancel buttons in the standard order for the current computer system.
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 |
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, the Wolfram System will effectively freeze.
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.
Dialogs that display a message can also be created using MessageDialog, which includes the DefaultButton by default.
Sometimes it is useful to also include an audible beep with the message dialog using Beep.
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.
Several front end dialogs such as the the Wolfram System Preferences dialog were created using CreateDialog.
| DialogReturn[expr] | close a dialog window and return the expression expr from the dialog |
| DialogInput[expr] | |
| ChoiceDialog[expr] | create and open a choice dialog notebook containing expr in the front end |
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.
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->"Queued".
The Wolfram Language also offers access to system dialogs through the use of SystemDialogInput, front end tokens, and user interface-specific button functions including FileNameSetter, ColorSlider, and ColorSetter.
| SystemDialogInput["FileOpen"] | open the system file open dialog and return the chosen file path |
| SystemDialogInput["FileSave"] | open the system file save dialog and return the chosen file path |
| SystemDialogInput["Color"] | open the system color picker dialog and return the chosen RGBColor value |
| FrontEndTokenExecute["PrintDialog"] | |
open the system print dialog to print the current notebook | |
This opens the system color dialog and returns the RGBColor value for the selected color.
The front end token "PrintDialog" 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 |
Here is a button that opens the system file open dialog and assigns the file path for the chosen file to a dynamic variable.
"Save" exhibits the same behavior as "Open" by assigning the file path for the chosen file to a dynamic variable.
This creates a button that opens the system directory picking dialog and assigns the file path for the chosen directory to a dynamic variable.
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.
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.
The Wolfram Language 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 |
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.
Input Dialog
InputString Dialog
Progress Dialog
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.
