Gtk.Dialog

Gtk.Dialog — Create popup windows

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.Window
                        ╰── Gtk.Dialog
                            ├── Gtk.AboutDialog
                            ├── Gtk.AppChooserDialog
                            ├── Gtk.ColorChooserDialog
                            ├── Gtk.ColorSelectionDialog
                            ├── Gtk.FileChooserDialog
                            ├── Gtk.FontChooserDialog
                            ├── Gtk.FontSelectionDialog
                            ├── Gtk.MessageDialog
                            ├── Gtk.PageSetupUnixDialog
                            ├── Gtk.PrintUnixDialog
                            ╰── Gtk.RecentChooserDialog

See also:

Gtk.Window, Gtk.Button

Functions:

Signals:

  • “close” (user_data)

Description:

Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

GTK+ treats a dialog as a window split vertically. The top section is a GtkVBox, and is where widgets such as a Gtk.Label or a GtkEntry should be packed. The bottom area is known as the action area. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply.

Gtk.Dialog boxes are created with a call to Gtk.Dialog::new() or Gtk.Dialog::new_with_buttons(). Gtk.Dialog::new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons.

If dialog is a newly created dialog, the two primary areas of the window can be accessed through Gtk.Dialog::get_content_area() and Gtk.Dialog::get_action_area(), as can be seen from the example below.

A modal dialog (that is, one which freezes the rest of the application from user input), can be created by calling Gtk.Window::set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from Gtk.Dialog::new() into a Gtk.Window. When using Gtk.Dialog::new_with_buttons() you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal.

If you add buttons to Gtk.Dialog using Gtk.Dialog::new_with_buttons(), Gtk.Dialog::add_button(), Gtk.Dialog::add_buttons(), or Gtk.Dialog::add_action_widget(), clicking the button will emit a signal 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 GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the Gtk.Dialog::response signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call Gtk.Dialog::run(). This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked.

For the simple dialog in the following example, in reality you’d probably use Gtk.MessageDialog to save yourself 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 Gtk.Dialog usage:

class Dialog(Gtk.Dialog):
    def __init__(self, parent):
        Gtk.Dialog.__init__(self, parent=parent)
        self.set_title("Dialog")
        self.set_default_size(400, 300)
        self.add_button("_OK", Gtk.ResponseType.OK)
        self.add_button("_Cancel", Gtk.ResponseType.CANCEL)
        self.connect("response", self.on_response)

        label = Gtk.Label("This is a Dialog example.")
        self.vbox.add(label)

        self.show_all()

    def on_response(self, dialog, response):
        if response == Gtk.ResponseType.OK:
            print("OK button clicked")
        elif response == Gtk.ResponseType.CANCEL:
            print("Cancel button clicked")
        else:
            print("Dialog closed")

        dialog.destroy()

Gtk.Dialog as Gtk.Buildable:

The Gtk.Dialog implementation of the Gtk.Buildable interface exposes the vbox and action_area as internal children with the names vbox and action_area.

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

Gtk.Dialog 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 Gtk.Dialog UI definition fragment:

<object class="GtkDialog" id="dialog1">
  <child type="action">
    <object class="GtkButton" id="button_cancel"/>
  </child>
  <child type="action">
    <object class="GtkButton" id="button_ok">
      <property name="can-default">True</property>
    </object>
  </child>
  <action-widgets>
    <action-widget response="cancel">button_cancel</action-widget>
    <action-widget response="ok" default="true">button_ok</action-widget>
  </action-widgets>
</object>

Function Details:

new()

new () -> Gtk.Widget

Creates a new dialog box. Widgets should not be packed into this Gtk.Windowdirectly, but into the vbox and action_area, as described above.

  • Returns: the new dialog as a Gtk.Widget

run()

run (self) -> int

Blocks in a recursive main loop until the dialog either emits the“response” signal, or is destroyed. If the dialog isdestroyed during the call to Gtk.Dialog:run(), Gtk.Dialog:run() returnsGTK_RESPONSE_NONE. Otherwise, it returns the response ID from the::response signal emission. Before entering the recursive main loop, Gtk.Dialog:run() calls`Gtk.Widget:show()on the dialog for you. Note that you stillneed to show any children of the dialog yourself. DuringGtk.Dialog:run(), the default behavior of “delete-event”is disabled; if the dialog receives ::delete_event, it will not bedestroyed as windows usually are, andGtk.Dialog:run()will returnGTK_RESPONSE_DELETE_EVENT. Also, duringGtk.Dialog:run()the dialogwill be modal. You can forceGtk.Dialog:run()to return at any time bycallingGtk.Dialog:response()to emit the ::response signal. Destroyingthe dialog duringGtk.Dialog:run()is a very bad idea, because yourpost-run code won’t know whether the dialog was destroyed or not. AfterGtk.Dialog:run()returns, you are responsible for hiding ordestroying the dialog if you wish to do so. Typical usage of this function might be: gint result = Gtk.Dialog:run (GTK_DIALOG (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT: do_application_specific_something (); break; default: do_nothing_since_dialog_was_cancelled (); break; }Gtk.Widget:destroy(dialog); Note that even though the recursive main loop gives the effect of amodal dialog (it prevents the user from interacting with otherwindows in the same window group while the dialog is run), callbackssuch as timeouts, IO channel watches, DND drops, etc, willbe triggered during aGtk.Dialog:run()` call.

  • Returns: response ID

response()

response (self, response_id:int)

Emits the “response” signal with the given response ID.Used to indicate that the user has responded to the dialog in some way;typically either you or Gtk.Dialog:run() will be monitoring the::response signal and take appropriate action.

add_button()

add_button (self, button_text:str, response_id:int) -> Gtk.Widget

Adds a button with the given text and sets things up so thatclicking the button will emit the “response” signal withthe given response_id. The button is appended to the end of thedialog’s action area. The button widget is returned, but usuallyyou don’t need it.

  • Returns: the Gtk.Button widget that was added.

add_action_widget()

add_action_widget (self, child:Gtk.Widget, response_id:int)

Adds an activatable widget to the action area of a Gtk.Dialog,connecting a signal handler that will emit the “response”signal on the dialog when the widget is activated. The widget isappended to the end of the dialog’s action area. If you want to add anon-activatable widget, simply pack it into the action_area fieldof the Gtk.Dialog struct.

set_default_response()

set_default_response (self, response_id:int)

Sets the last widget in the dialog’s action area with the given response_idas the default widget for the dialog. Pressing “Enter” normally activatesthe default widget.

set_response_sensitive()

set_response_sensitive (self, response_id:int, setting:bool)

Calls `Gtk.Widget:set_sensitive (widget, @setting)for each widget in the dialog’s action area with the givenresponse_id`.A convenient way to sensitize/desensitize dialog buttons.

get_response_for_widget()

get_response_for_widget (self, widget:Gtk.Widget) -> int

Gets the response id of a widget in the action areaof a dialog.

  • Returns: the response id of widget, or GTK_RESPONSE_NONEif widgetdoesn’t have a response id set.

  • Since: 2.8

get_widget_for_response()

get_widget_for_response (self, response_id:int) -> Gtk.Widget

Gets the widget button that uses the given response ID in the action areaof a dialog.

  • Returns: the widgetbutton that uses the givenresponse_id, or None.

  • Since: 2.20

get_action_area()

get_action_area (self) -> Gtk.Widget

Gtk.Dialog:get_action_area has been deprecated since version 3.12 and should not be used in newly-written code. Direct access to the action area is discouraged; use Gtk.Dialog:add_button(), etc. Returns the action area of dialog.

  • Returns: the action area.

  • Since: 2.14

get_content_area()

get_content_area (self) -> Gtk.Box

Returns the content area of dialog.

  • Returns: the content area Gtk.Box.

  • Since: 2.14

get_header_bar()

get_header_bar (self) -> Gtk.Widget

Returns the header bar of dialog. Note that theheaderbar is only used by the dialog if the“use-header-bar” property is True.

  • Returns: the header bar.

  • Since: 3.12

set_alternative_button_order_from_array()

set_alternative_button_order_from_array (self, new_order:list)

Gtk.Dialog:set_alternative_button_order_from_array has been deprecated since version 3.10 and should not be used in newly-written code. Deprecated Sets an alternative button order. If the“gtk-alternative-button-order” setting is set to True,the dialog buttons are reordered according to the order of theresponse ids in new_order. See Gtk.Dialog:set_alternative_button_order() for more information. This function is for use by language bindings.

  • Since: 2.6

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class Dialog(Gtk.Dialog):
    def __init__(self, parent):
        Gtk.Dialog.__init__(self, parent=parent)
        self.set_title("Dialog")
        self.set_default_size(400, 300)
        self.add_button("_OK", Gtk.ResponseType.OK)
        self.add_button("_Cancel", Gtk.ResponseType.CANCEL)
        self.connect("response", self.on_response)

        label = Gtk.Label("This is a Dialog example.")
        self.vbox.add(label)

        self.show_all()

    def on_response(self, dialog, response):
        if response == Gtk.ResponseType.OK:
            print("OK button clicked")
        elif response == Gtk.ResponseType.CANCEL:
            print("Cancel button clicked")
        else:
            print("Dialog closed")

        dialog.destroy()

class TestWindow(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("Test Dialog")
        self.set_size_request(200, 100)
        self.connect("destroy", Gtk.main_quit)

        button = Gtk.Button(label="Click to show Dialog")
        button.connect("clicked", self.on_button_clicked)
        self.add(button)

    def on_button_clicked(self, button):
        dialog = Dialog(self)
        dialog.run()

window = TestWindow()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""