Creating Dialog Boxes

In the Wolfram System, dialog boxes are customized notebooks used to provide users with information and/or request user input.

There are two properties associated with dialogs.

modalprevents access to other elements of the front end until the dialog is closed and must be explicitly set using the option Modal
blockingblocks 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, 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.

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.

1.gif

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 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.

In[6]:=
Click for copyable input
Out[6]=

ChoiceButtons will display the default and cancel buttons in the standard order for the current computer system.

In[3]:=
Click for copyable input
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
Modaloption 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, the Wolfram System 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.

In[43]:=
Click for copyable input
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.

In[4]:=
Click for copyable input
Out[4]=

13.gif

Sometimes it is useful to also include an audible beep with the message dialog using Beep.

In[3]:=
Click for copyable input
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.

15.gif

In[22]:=
Click for copyable input
Out[22]=

Several front end dialogs such as the the Wolfram System Preferences dialog were created using CreateDialog.

16.gif

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.

In[53]:=
Click for copyable input
Out[53]=

Here, the kernel is blocked until the user sets a value to removeQ by selecting Cancel or OK.

In[7]:=
Click for copyable input
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.

In[4]:=
Click for copyable input
Out[4]=

19.gif

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".

In[1]:=
Click for copyable input
Out[1]=
In[3]:=
Click for copyable input
Out[3]=

System Dialogs

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

Accessing common system dialogs programmatically.

Here is the system file open dialog that returns the file path for the chosen file.

In[19]:=
Click for copyable input
Out[19]=

20.gif

exhibits the same behavior as by returning the file path for the chosen file.

In[29]:=
Click for copyable input
Out[29]=

23.gif

This opens the system color dialog and returns the RGBColor value for the selected color.

In[8]:=
Click for copyable input
Out[8]=

24.gif

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.

In[14]:=
Click for copyable input
Out[14]=

27.gif

calls the system multiple file open dialog instead.

In[15]:=
Click for copyable input
Out[15]=

29.gif

exhibits the same behavior as by assigning the file path for the chosen file to a dynamic variable.

In[16]:=
Click for copyable input
Out[16]=

32.gif

This creates a button that opens the system directory picking dialog and assigns the file path for the chosen directory to a dynamic variable.

In[17]:=
Click for copyable input
Out[17]=

33.gif

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.

In[20]:=
Click for copyable input
Out[20]=

34.gif

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.

In[21]:=
Click for copyable input
Out[21]=

35.gif

Wolfram System Input Dialogs

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

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.

Input Dialog

This returns the polynomial expansion of the input.

In[3]:=
Click for copyable input
Out[3]=

36.gif

InputString Dialog

Here the inputted string is split into a list of substrings.

In[5]:=
Click for copyable input
Out[5]=

37.gif

Extended Examples

Progress Dialog

Here is a progress dialog that tracks the value of the dynamic variable during a computation.

In[1]:=
Click for copyable input

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

The Wolfram System 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.