gtk.Dialog
Prev | The gtk Class Reference | Next

## gtk.Dialog

gtk.Dialog — popup windows for user information and action

## Synopsis

    class gtk.Dialog(gtk.Window):
        gtk.Dialog(title=None, parent=None, flags=0, buttons=None)
        def add_action_widget(child, response_id)
        def add_button(button_text, response_id)
        def add_buttons(...)
        def set_response_sensitive(response_id, setting)
        def set_default_response(response_id)
        def set_has_separator(setting)
        def get_has_separator()
        def response(response_id)
        def run()
        def set_alternative_button_order(new_order)
        def get_response_for_widget(widget)
        def get_action_area()
        def get_content_area()

    Functions

        def gtk.alternative_dialog_button_order(screen=None)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.Window
                +-- gtk.Dialog

## Implemented Interfaces

`gtk.Dialog` implements `gtk.Buildable`

## gtk.Dialog Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.Window Properties

"has-separator" | Read/Write | If `True`, the dialog has a separator bar above its buttons

## gtk.Dialog Style Properties

gtk.Widget Style Properties

"action-area-border" | Read | The width of the vborder around the button area in pixels.
"button-spacing" | Read | The spacing between buttons in pixels.
"content-area-spacing" | Read | The default spacing used between elements of the content area of the dialog, as returned by `gtk.Dialog.get_content_area`(), unless `gtk.Box.set_spacing`() was called on that widget directly. Allowed values: >= 0. Default value: 0. This property is available in GTK+ 2.16 and above.
"content-area-border" | Read | The width of the border around the main dialog area in pixels.

## Attributes

"vbox" | Read | A `gtk.VBox` that is the main container of the dialog - all the other widgets are packed in it.
"action_area" | Read | A `gtk.HBox` that contains the buttons of the dialog.

## gtk.Dialog Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.Window Signal Prototypes

"close" | `def callback(`dialog`, `user_param1`, `...`)`
"response" | `def callback(`dialog`, `response_id`, `user_param1`, `...`)`

## 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. Dialogs are organized as a window split vertically. The top section is a `gtk.VBox`, and is where widgets such as a `gtk.Label` or a `gtk.Entry` should be packed. The bottom area is known as the action_area which is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. The two areas are separated by a `gtk.HSeparator`.

The `gtk.Dialog` boxes are created with a call to `gtk.Dialog`() that sets the dialog title, some convenient flags, and adds simple buttons. In a newly created dialog, the two primary areas of the window can be accessed as the vbox and action_area attributes, as can be seen from the example, below.

    import gtk

    label = gtk.Label("Nice label")
    dialog = gtk.Dialog("My dialog",
                       None,
                       gtk.DIALOG_MODAL | gtk.DIALOG_DESTROY_WITH_PARENT,
                       (gtk.STOCK_CANCEL, gtk.RESPONSE_REJECT,
                        gtk.STOCK_OK, gtk.RESPONSE_ACCEPT))
    dialog.vbox.pack_start(label)
    label.show()
    checkbox = gtk.CheckButton("Useless checkbox")
    dialog.action_area.pack_end(checkbox)
    checkbox.show()
    response = dialog.run()
    dialog.destroy()

A modal dialog (that is, one which freezes the rest of the application from user input), can be created by passing the `gtk.DIALOG_MODAL` flag to the `gtk.Dialog`() constructor or by calling `set_modal`() on the dialog.

If you add buttons to `gtk.Dialog` using `gtk.Dialog`(), `add_button`(), or `add_action_widget`(), clicking the button will emit a signal called "response" with a response ID that you specified. PyGTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the pre-defined GTK Response Type Constants (these all have values less than zero).

If a dialog receives a delete event, the "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 `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.

## Constructor

        gtk.Dialog(title=None, parent=None, flags=0, buttons=None)

`title` : | The title of the dialog, or `None`
`parent` : | The transient parent of the dialog, or `None`
`flags` : | flags that control the operation of the dialog
`buttons` : | a tuple containing button text/response id pairs or `None`
Returns : | a new `gtk.Dialog`

Creates a new `gtk.Dialog` with the title text specified by `title` (or `None` for the default title; see `gtk.Window.set_title`()) and transient parent window specified by `parent` (or `None` for none; see `gtk.Window.set_transient_for`()). The `flags` argument can be used to make the dialog modal (`gtk.DIALOG_MODAL`) and/or to have it destroyed along with its transient parent (`gtk.DIALOG_DESTROY_WITH_PARENT`) and/or remove the separator (`gtk.DIALOG_NO_SEPARATOR`) (see the GTK Dialog Flag Constants for more information). After `flags`, a tuple of button text/response ID pairs should be listed, or `None` (the default value) if no buttons are needed. The button text can be either a stock ID such as `gtk.STOCK_OK`, or some arbitrary text. A response ID can be any positive number, or one of the pre-defined GTK Response Type Constants.

If the user clicks one of these dialog buttons, the `gtk.Dialog` will emit the "response" signal with the corresponding response ID. If a `gtk.Dialog` receives the "delete_event" signal, it will emit "response" with a response ID of `gtk.RESPONSE_DELETE_EVENT`. However, destroying a dialog does not emit the "response" signal; so be careful relying on "response" when using the `gtk.DIALOG_DESTROY_WITH_PARENT` flag. Buttons are added from left to right, so the first button in the list will be the leftmost button in the dialog.

Here's a simple example:

      dialog = gtk.Dialog("My dialog",
                         main_app_window,
                         gtk.DIALOG_MODAL | gtk.DIALOG_DESTROY_WITH_PARENT,
                         (gtk.STOCK_CANCEL, gtk.RESPONSE_REJECT,
                          gtk.STOCK_OK, gtk.RESPONSE_ACCEPT))

## Methods

### gtk.Dialog.add_action_widget

        def add_action_widget(child, response_id)

`child` : | an activatable widget
`response_id` : | a response ID

The `add_action_widget`() method 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 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`.

### gtk.Dialog.add_button

        def add_button(button_text, response_id)

`button_text` : | the text of the button, or a stock ID
`response_id` : | the response ID for the button
Returns : | the button widget that was added

The `add_button`() method adds a button with the text specified by `button_text` (or a stock button, if `button_text` is a stock ID) and sets things up so that clicking the button will emit the "response" signal with the specified `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.

### gtk.Dialog.add_buttons

        def add_buttons(...)

`...` : | one or more pairs of button specifiers: button text (or stock ID) and a response id

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:

      dialog.add_buttons(gtk.STOCK_OPEN, 42, "Close", gtk.RESPONSE_CLOSE)

will add "Open" and "Close" buttons to `dialog`.

### gtk.Dialog.set_response_sensitive

        def set_response_sensitive(response_id, setting)

`response_id` : | a response ID
`setting` : | the new value for sensitive

The `set_response_sensitive`() method calls the `gtk.Window.set_sensitive`() method with the specified `response_id` for each widget in the dialog's action area. This method is a convenience function to sensitize/desensitize all dialog buttons at once.

### gtk.Dialog.set_default_response

        def set_default_response(response_id)

`response_id` : | a response ID

The `set_default_response`() method sets the last widget in the dialog's action area with the specified `response_id` as the default widget for the dialog. Pressing Enter normally activates the default widget.

### gtk.Dialog.set_has_separator

        def set_has_separator(setting)

`setting` : | If `True` use a separator

The `set_has_separator`() method sets the "has-separator" property to the value of `setting`. If `setting` is `True` (the default value) the dialog has a separator above the buttons.

### gtk.Dialog.get_has_separator

        def get_has_separator()

Returns : | the value of the "has-separator" property

The `get_has_separator`() method returns the value of the "has-separator" property.

### gtk.Dialog.response

        def response(response_id)

`response_id` : | response ID

The `response`() method emits the "response" signal with the value specified in `response_id`. This method is 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.

### gtk.Dialog.run

        def run()

Returns : | a response ID

The `run`() method blocks in a recursive main loop until the dialog either emits the "response" signal, or is destroyed. If the dialog is destroyed, the `run`() method returns `gtk.RESPONSE_NONE`; otherwise, it returns the response ID from the "response" signal emission. Before entering the recursive main loop, the `run`() method calls the `gtk.Widget.show`() on the dialog for you. Note that you still need to show any children of the dialog yourself.

During the `run`() method, the default behavior of "delete_event" is disabled; if the dialog receives a "delete_event", it will not be destroyed as windows usually are, and the `run`() method will return `gtk.RESPONSE_DELETE_EVENT`. Also, during the `run`() method the dialog will be modal. You can force the `run`() method to return at any time by calling `response`() to emit the "response" signal. Destroying the dialog during the `run`() method is a very bad idea, because your post-run code won't know whether the dialog was destroyed or not.

After the `run`() method returns, you are responsible for hiding or destroying the dialog as needed.

### gtk.Dialog.set_alternative_button_order

        def set_alternative_button_order(new_order)

`new_order` : | a sequence containing response id integer values

### Note

This method is available in PyGTK 2.6 and above.

The `set_alternative_button_order`() method sets an alternative button order for the dialog based on the sequence of response ids specified by `new_order`. If the "gtk-alternative-button-order" property of the `gtk.Settings` object is set to `True`, the dialog buttons are reordered according to the order of the response ids passed to this method.

By default, GTK+ dialogs use the button order advocated by the Gnome Human Interface Guidelines with the affirmative button at the far right, and the cancel button left of it. But the builtin GTK+ dialogs and `gtk.MessageDialog`s do provide an alternative button order, which is more suitable on some platforms, e.g. Windows.

Use this method after adding all the buttons to your dialog, as the following example shows:

      settings = gtk.settings_get_default()
      settings.set_property('gtk-alternative-button-order', True)

      dialog = gtk.Dialog()
      cancel_button = dialog.add_button(gtk.STOCK_CANCEL, gtk.RESPONSE_CANCEL)
      ok_button = dialog.add_button(gtk.STOCK_OK, gtk.RESPONSE_OK)
      ok_button.grab_default()
      help_button = dialog.add_button(gtk.STOCK_HELP, gtk.RESPONSE_HELP)

      dialog.set_alternative_button_order([gtk.RESPONSE_OK, gtk.RESPONSE_CANCEL,
                                           gtk.RESPONSE_HELP])

### gtk.Dialog.get_response_for_widget

        def get_response_for_widget(widget)

`widget` : | a widget in the action area of the dialog
Returns : | the response id of `widget`, or gtk.RESPONSE_NONE if the widget doesn't have a response id set.

### Note

This method is available in PyGTK 2.8 and above.

The `get_response_for_widget`() method returns the response id of the widget specified by `widget` in the action area of the dialog.

### gtk.Dialog.get_action_area

        def get_action_area()

Returns : | the action area.

### Note

This method is available in PyGTK 2.14 and above.

The `get_action_area`() method returns the action area of dialog.

### gtk.Dialog.get_content_area

        def get_content_area()

Returns : | the content area `gtk.VBox`.

### Note

This method is available in PyGTK 2.14 and above.

The `get_content_area`() method returns the content area of dialog.

## Functions

### gtk.alternative_dialog_button_order

        def gtk.alternative_dialog_button_order(screen=None)

`screen` : | the `gtk.gdk.Screen` or `None` to use the default screen
Returns : | `True` if the alternative button order should be used

### Note

This function is available in PyGTK 2.10 and above.

The `gtk.alternative_dialog_button_order`() returns `True` if the alternative button order should be used for the `gtk.gdk.Screen` specified by `screen`. If `screen` is `None` the default `gtk.gdk.Screen` is used.

## Signals

### The "close" gtk.Dialog Signal

        def callback(dialog, user_param1, ...)

`dialog` : | the dialog that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "close" signal is emitted when the dialog is closed.

### The "response" gtk.Dialog Signal

        def callback(dialog, response_id, user_param1, ...)

`dialog` : | the dialog that received the signal
`response_id` : | the response id received by the dialog
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "response" signal is emitted when an action_area widget is activated (button "clicked"), the dialog receives a delete_event or the application calls the `response`() method. When a delete_event triggers the "response" signal the `response_id` will be `gtk.RESPONSE_DELETE_EVENT`.

Prev | Up | Next
gtk.Curve | Home | gtk.DrawingArea