:right-sidebar: True Dialog =================================================================== .. currentmodule:: gi.repository.Gtk .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead .. class:: Dialog(*args, **kwargs) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Window`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gtk.AppChooserDialog`, :class:`~gi.repository.Gtk.ColorChooserDialog`, :class:`~gi.repository.Gtk.FileChooserDialog`, :class:`~gi.repository.Gtk.FontChooserDialog`, :class:`~gi.repository.Gtk.MessageDialog`, :class:`~gi.repository.Gtk.PageSetupUnixDialog`, :class:`~gi.repository.Gtk.PrintUnixDialog` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Native`, :class:`~gi.repository.Gtk.Root`, :class:`~gi.repository.Gtk.ShortcutManager` Dialogs are a convenient way to prompt the user for a small amount of input. .. image:: https://docs.gtk.org/gtk4/dialog.png Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part. The main area of a ``GtkDialog`` is called the "content area", and is yours to populate with widgets such a ``GtkLabel`` or ``GtkEntry``, to present your information, questions, or tasks to the user. In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your ``GtkDialog`` using :obj:`~gi.repository.Gtk.Dialog.new_with_buttons`, or use :obj:`~gi.repository.Gtk.Dialog.add_button`, :obj:`~gi.repository.Gtk.Dialog.add_buttons`, or :obj:`~gi.repository.Gtk.Dialog.add_action_widget`. ``GtkDialogs`` uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID :const:`~gi.repository.Gtk.ResponseType.CLOSE` or :const:`~gi.repository.Gtk.ResponseType.CANCEL`, the close button is omitted. Clicking a button that was added as an action widget will emit the :obj:`~gi.repository.Gtk.Dialog.signals.response` signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the :obj:`~gi.repository.Gtk.ResponseType` enumeration (these all have values less than zero). If a dialog receives a delete event, the :obj:`~gi.repository.Gtk.Dialog.signals.response` signal will be emitted with the :const:`~gi.repository.Gtk.ResponseType.DELETE_EVENT` response ID. Dialogs are created with a call to :obj:`~gi.repository.Gtk.Dialog.new` or :obj:`~gi.repository.Gtk.Dialog.new_with_buttons`. The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons. A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling :obj:`~gi.repository.Gtk.Window.set_modal` on the dialog. When using :obj:`~gi.repository.Gtk.Dialog.new_with_buttons`, you can also pass the :const:`~gi.repository.Gtk.DialogFlags.MODAL` flag to make a dialog modal. For the simple dialog in the following example, a :obj:`~gi.repository.Gtk.MessageDialog` would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog. An example for simple ``GtkDialog`` usage: .. code-block:: :dedent: // Function to open a dialog box with a message void quick_message (GtkWindow *parent, char *message) { GtkWidget *dialog, *label, *content_area; GtkDialogFlags flags; // Create the widgets flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("Message", parent, flags, _("_OK"), GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message); // Ensure that the dialog box is destroyed when the user responds g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_window_destroy), dialog); // Add the label, and show everything we’ve added gtk_box_append (GTK_BOX (content_area), label); gtk_widget_show (dialog); } GtkDialog as GtkBuildable ------------------------- The ``GtkDialog`` implementation of the ``GtkBuildable`` interface exposes the ``content_area`` as an internal child with the name “content_area”. ``GtkDialog`` supports a custom ```` element, which can contain multiple ```` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs ``action_area``). To mark a response as default, set the “default” attribute of the ```` element to true. ``GtkDialog`` supports adding action widgets by specifying “action” as the “type” attribute of a ```` element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the ```` element. An example of a ``GtkDialog`` UI definition fragment: .. code-block:: :dedent: button_cancel button_ok Accessibility ------------- ``GtkDialog`` uses the :const:`~gi.repository.Gtk.AccessibleRole.DIALOG` role. Constructors ------------ .. rst-class:: interim-class .. class:: Dialog :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new dialog box. Widgets should not be packed into the ``GtkWindow`` directly, but into the ``content_area`` and ``action_area``, as described above. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead Methods ------- .. rst-class:: interim-class .. class:: Dialog :no-index: .. method:: add_action_widget(child: ~gi.repository.Gtk.Widget, response_id: int) -> None Adds an activatable widget to the action area of a ``GtkDialog``. GTK connects a signal handler that will emit the :obj:`~gi.repository.Gtk.Dialog.signals.response` signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, simply pack it into the ``action_area`` field of the ``GtkDialog`` struct. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param child: an activatable widget :param response_id: response ID for ``child`` .. method:: add_button(button_text: str, response_id: int) -> ~gi.repository.Gtk.Widget Adds a button with the given text. GTK arranges things so that clicking the button will emit the :obj:`~gi.repository.Gtk.Dialog.signals.response` signal with the given ``response_id``. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param button_text: text of button :param response_id: response ID for the button .. method:: add_buttons(*args) The add_buttons() method adds several buttons to the Gtk.Dialog using the button data passed as arguments to the method. This method is the same as calling the Gtk.Dialog.add_button() repeatedly. The button data pairs - button text (or stock ID) and a response ID integer are passed individually. For example: .. code-block:: python dialog.add_buttons(Gtk.STOCK_OPEN, 42, "Close", Gtk.ResponseType.CLOSE) will add "Open" and "Close" buttons to dialog. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param args: .. method:: get_content_area() -> ~gi.repository.Gtk.Box Returns the content area of ``dialog``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead .. method:: get_header_bar() -> ~gi.repository.Gtk.HeaderBar Returns the header bar of ``dialog``. Note that the headerbar is only used by the dialog if the :obj:`~gi.repository.Gtk.Dialog.props.use_header_bar` property is :const:`True`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead .. method:: get_response_for_widget(widget: ~gi.repository.Gtk.Widget) -> int Gets the response id of a widget in the action area of a dialog. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param widget: a widget in the action area of ``dialog`` .. method:: get_widget_for_response(response_id: int) -> ~gi.repository.Gtk.Widget | None Gets the widget button that uses the given response ID in the action area of a dialog. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: the response ID used by the ``dialog`` widget .. method:: response(response_id: int) -> None Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: response ID .. method:: set_default_response(response_id: int) -> None Sets the default widget for the dialog based on the response ID. Pressing “Enter” normally activates the default widget. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: a response ID .. method:: set_response_sensitive(response_id: int, setting: bool) -> None A convenient way to sensitize/desensitize dialog buttons. Calls `gtk_widget_set_sensitive (widget, ``setting``)` for each widget in the dialog’s action area with the given ``response_id``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: a response ID :param setting: :const:`True` for sensitive Properties ---------- .. rst-class:: interim-class .. class:: Dialog :no-index: .. attribute:: props.use_header_bar :type: int :const:`True` if the dialog uses a headerbar for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to :const:`True` or :const:`False`. Creating a dialog with headerbar -------------------------------- Builtin ``GtkDialog`` subclasses such as :obj:`~gi.repository.Gtk.ColorChooserDialog` set this property according to platform conventions (using the :obj:`~gi.repository.Gtk.Settings.props.gtk_dialogs_use_header` setting). Here is how you can achieve the same: .. code-block:: :dedent: g_object_get (settings, "gtk-dialogs-use-header", &header, NULL); dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL); .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead Signals ------- .. rst-class:: interim-class .. class:: Dialog.signals :no-index: .. method:: close() -> None Emitted when the user uses a keybinding to close the dialog. This is a `keybinding signal `_. The default binding for this signal is the Escape key. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead .. method:: response(response_id: int) -> None Emitted when an action widget is clicked. The signal is also emitted when the dialog receives a delete event, and when :obj:`~gi.repository.Gtk.Dialog.response` is called. On a delete event, the response ID is :const:`~gi.repository.Gtk.ResponseType.DELETE_EVENT`. Otherwise, it depends on which action widget was clicked. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: the response ID Virtual Methods --------------- .. rst-class:: interim-class .. class:: Dialog :no-index: .. method:: do_close() -> None Signal emitted when the user uses a keybinding to close the dialog. .. method:: do_response(response_id: int) -> None Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.Window` instead :param response_id: response ID Fields ------ .. rst-class:: interim-class .. class:: Dialog :no-index: .. attribute:: parent_instance