13. Dialogs

A dialog is a small window that presents information to the users and prompts them for a response. A dialog can be modal, in which case the user cannot continue without closing it, or modeless, where the user can continue work while the dialog is still open.¹ Qt offers several standard dialogs while also letting developers create custom ones by subclassing the QDialog class.

Qt standard dialogs²:

[TODO: A NOTE ON PARENTS]

QMessageBox is a modal dialog for providing information to the user or asking a question and receiving an answer. A message box can display a text message, an icon and Qt’s standard buttons for accepting the user’s response³.

To use a message box in your application:

1. Create a QMessageBox object. In the example, we detect when the user attempts to close the application by overriding the main window’s closeEvent(). The document is stored in a text edit and we only show the message box if the document’s isModified() property is true.

2. Set the message box properties. We set the title, icon, text, and informative text to provide additional information to the user (for even more details, use detailedText()). We also add three standard buttons, Save, Discard and Cancel, and set Save as the default.

3. Display the message box using exec(), making it modal, and handle the user response. The message box’s return value is one of the standard button enumeration values: if the user presses Save, we simulate saving the document and set its modified() property to false; if the user presses Discard we continue without saving the document; and if the user presses Cancel we ignore the close event and the application remains open.

Whereas QMessageBox typically returns a QMessageBox.StandardButton value, QinputDialog can return single-line or multiline text, an integer, a double, or a string selected from a list.

To use a QInputDialog in your application:

1. Provide a way for the user to invoke the dialog. We create a QAction and connect its triggered() signal to the set_note_title() slot.

2. Show the dialog. When the user triggers the action, display the input dialog using one of the QInputDialog’s static methods:

   Method	Description
   getDouble()	Gets a floating point number from the user
   getInt()	Gets an integer from the user
   getItem()	Gets an item from a list
   getMultiLineText()	Gets multi-line text input
   getText()	Gets a single line of text

   In the example, the user needs to enter a string so we use getText().

3. Check the return value and handle the user response. getText() returns a tuple:

   1 (text, ok)
   

   text is the string the user entered. ok will be true if the user presses Ok and false if the user presses Cancel. If ok is true, set the note title and update the action’s icon indicating the note has a title.

QFileDialog lets users select files or directories. The easiest approach is using one of its static methods⁴:

Behind the scenes, QFileDialog uses a platform-native file dialog if one is available, resulting in different appearence accross platforms.

To use a file dialog in your application:

1. Give users a way to display the dialog. Create two QActions, one for saving and one for opening a file. For both actions, set text, a shortcut and an icon. Connect each action’s triggered() signal to a slot - save_note() for the save action and open_note() for the open action.

2. Display the dialog. In open_note() we use getOpenFileName(). In save_note(), the file dialog is shown only if the note has not been already saved. For both dialogs set the title, the starting directory and the file filter.

3. Use the return value to handle the user’s response. getSaveFileName() returns a tuple:

If the user presses Cancel, fileName is an empty string so we don’t need to do anything. If the user presses the Save button, we save the contents of the text edit into fileName.

Likewise, we use fileName to read the file contents into the text edit only if getOpenFileName() does not return an empty string.

QColorDialog allows users to select colors. You typically use its getColor() static method to show it as a modal dialog⁵.

To use a color dialog in your application:

1. Provide a way for users to display the dialog. In the main window’s __init__(), create actions for selecting the foreground and background colors. Connect the actions to the slots and add the them to the the main window’s menu bar and toolbar.

2. Show the dialog. We want both dialogs to open with the current text colors. foreground() and background() are QBrush objects, so we extract their colors and use them as the dialogs’ initial colors.

3. If the dialog returns a valid color use it in your application. Unlike QInputDialog and QFileDialog, QColorDialog does not return a tuple - it always returns a QColor object, so we need to check if it isValid() to confirm that the user pressed Ok.

QFontDialog provides a dialog for selecting a font. It is created by invoking one of the static getFont() methods⁶:

• getFont(parent)
• getFont(initial, parent, title, options)

To use a font dialog in your application:

1. Create an action to trigger the dialog.

2. Show the dialog to the user. In set_font(), we get the current QFont from the text edit’s currentCharFormat() and pass it to getFont() so the dialog opens with that font selected.

3. If the user presses Ok, update the font. getFont() returns a tuple where the first element, ok, is true if the user pressed Ok and false otherwise. The second element is a QFont object representing the font the user selected.

Standard dialogs are straightforward to use - you display them using static methods and handle the result based on which button the user pressed. They are designed to fiy most common use cases like showing messages, choosing colors, files and folders, fonts, and accepting user input. For more complex or custom dialogs, however, you can subclass the QDialog class and create your own.

QDialog is the base class of all the Qt standard dialogs, implementing the slots common to all of them:

and their common methods:

signals:

and properties:

Set result() to one of the QDialog.DialogCode values, Accepted or Rejected.

The QDialogButtonBox class, commonly used with QDialog, automatically arranges standard buttons in a layout appropriate for the user’s desktop environment. For instance, Windows places the OK button before Cancel, while Gnome reverses this order.

To create a custom Qt dialog:

1. Create a QDialog subclass. We create a class named SettingsDialog, set its window title and set it to be modal.

2. Add the child widgets to the dialog. In the example, we create three widgets:

   • A checkbox to set whether the application should auto-save the current note or not,
   • A spinbox to set the auto-save interval,
   • A checkbox to make the application reopen the last edited note. The spinbox is enabled only if the auto-save checkbox is checked and lets the user select values between one and sixty minutes.

3. Add QDialogButtonBox to the dialog. We want the application to have a native look on multiple platforms so we add a button box with the Ok and Cancel buttons. We also connect the button box accepted signal to accept() and the rejected signal to reject(). The current widget values are saved to a .ini file using QSettings.

4. Use the custom dialog in your application. In the main window, we create the settings action and, when it’s triggered, show our custom dialog so the user can edit the settings.