path: root/docs/reference/pygtk-gtkdialog.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkdialog">
  <refnamediv>
    <refname>gtk.Dialog</refname>
    <refpurpose>popup windows for user information and action</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Dialog</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkwindow">gtk.Window</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkdialog">gtk.Dialog</link></methodname>
        <methodparam><parameter role="keyword">title</parameter><initializer>None</initializer></methodparam>
        <methodparam><parameter role="keyword">parent</parameter><initializer>None</initializer></methodparam>
        <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam>
        <methodparam><parameter role="keyword">buttons</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--add-action-widget">add_action_widget</link></methodname>
        <methodparam><parameter role="keyword">child</parameter></methodparam>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--add-button">add_button</link></methodname>
        <methodparam><parameter role="keyword">button_text</parameter></methodparam>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--add-buttons">add_buttons</link></methodname>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--set-response-sensitive">set_response_sensitive</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
        <methodparam><parameter role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--set-default-response">set_default_response</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--set-has-separator">set_has_separator</link></methodname>
        <methodparam><parameter role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--get-has-separator">get_has_separator</link></methodname>
        <methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
      <methodname><link linkend="method-gtkdialog--response">response</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--run">run</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--set-alternative-button-order">set_alternative_button_order</link></methodname>
        <methodparam><parameter role="keyword">new_order</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--get-response-for-widget">get_response_for_widget</link></methodname>
        <methodparam><parameter role="keyword">widget</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--get-widget-for-response">get_widget_for_response</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--get-action-area">get_action_area</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkdialog--get-content-area">get_content_area</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>

    </classsynopsis>

    <programlisting>
      <emphasis role="bold">Functions</emphasis>

      <methodsynopsis language="python">
        <methodname><link linkend="function-gtk--alternative-dialog-button-order">gtk.alternative_dialog_button_order</link></methodname>
        <methodparam><parameter role="keyword">screen</parameter><initializer>None</initializer></methodparam>
  </methodsynopsis></programlisting>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkwindow">gtk.Window</link>
            +-- <link linkend="class-gtkdialog">gtk.Dialog</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Implemented Interfaces</title>
    <para>
      <link linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>
      implements 
      <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
    </para>
  </refsect1>


  <refsect1 id="properties-gtkdialog">
    <title>gtk.Dialog Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkwindow">gtk.Window Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
        <tgroup cols="3">
          <colspec column="1" colwidth="1in"/>
          <colspec column="2" colwidth="1in"/>
          <colspec column="3" colwidth="3.5in"/>
          <tbody>

            <row valign="top">
              <entry>"has-separator"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, the dialog has a separator bar above its
              buttons. This property has been deprecated since GTK+ 2.22 and should not
              be used in newly-written code.</entry>
          </row>

        </tbody>
      </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkdialog">
    <title>gtk.Dialog Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
        <tgroup cols="3">
          <colspec column="1" colwidth="1in"/>
          <colspec column="2" colwidth="1in"/>
          <colspec column="3" colwidth="3.5in"/>
          <tbody>
            <row valign="top">
              <entry>"action-area-border"</entry>
              <entry>Read</entry>
              <entry>The width of the vborder around the button area in pixels.</entry>
            </row>

            <row valign="top">
              <entry>"button-spacing"</entry>
              <entry>Read</entry>
              <entry>The spacing between buttons in pixels.</entry>
            </row>

            <row valign="top">
              <entry>"content-area-spacing"</entry>
              <entry>Read</entry>
              <entry>The default spacing used between elements of the content area of the dialog, as returned by
              <methodname><link linkend="method-gtkdialog--get-content-area">gtk.Dialog.get_content_area</link></methodname>(),
              unless <methodname><link linkend="method-gtkbox--set-spacing">gtk.Box.set_spacing</link></methodname>()
              was called on that widget directly. Allowed values: >= 0. Default value: 0. This property is available in GTK+ 2.16 and above.</entry>
            </row>

            <row valign="top">
              <entry>"content-area-border"</entry>
              <entry>Read</entry>
              <entry>The width of the border around the main dialog area in pixels.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
        <tgroup cols="3">
        <?dbhtml cellpadding="5"?>
          <colspec column="1" colwidth="1in"/>
          <colspec column="2" colwidth="1in"/>
          <colspec column="3" colwidth="3.5in"/>
          <tbody>
            <row valign="top">
              <entry>"vbox"</entry>
              <entry>Read</entry>
              <entry>A <link linkend="class-gtkvbox"><classname>gtk.VBox</classname></link> that is the main container of the dialog - all the other widgets are packed in it.</entry>
            </row>

            <row valign="top">
              <entry>"action_area"</entry>
              <entry>Read</entry>
              <entry>A <link linkend="class-gtkhbox"><classname>gtk.HBox</classname></link> that contains the buttons of the dialog.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkdialog">
    <title>gtk.Dialog Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwindow">gtk.Window Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkdialog--close">close</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>dialog</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkdialog--response">response</link>"</term>
        <listitem>
          <methodsynopsis language="python">
            <methodname>callback</methodname>
            <methodparam><parameter>dialog</parameter></methodparam>
            <methodparam><parameter>response_id</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>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 <link
    linkend="class-gtkvbox"><classname>gtk.VBox</classname></link>, and is
    where widgets such as a <link
    linkend="class-gtklabel"><classname>gtk.Label</classname></link> or a
    <link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>
    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
    <link
    linkend="class-gtkhseparator"><classname>gtk.HSeparator</classname></link>.</para>

    <para>The <link
    linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> boxes
    are created with a call to <link
    linkend="constructor-gtkdialog"><methodname>gtk.Dialog</methodname></link>()
    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.</para>

<programlisting>
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()
</programlisting>

    <para>A modal dialog (that is, one which freezes the
    rest of the application from user input), can be created by passing the
    <literal>gtk.DIALOG_MODAL</literal> flag to the <link
    linkend="constructor-gtkdialog"><methodname>gtk.Dialog</methodname>()</link>
    constructor or by calling <link
    linkend="method-gtkwindow--set-modal"><methodname>set_modal</methodname>()</link>
    on the dialog.</para>

    <para>If you add buttons to <link
    linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> using
    <link
    linkend="constructor-gtkdialog"><methodname>gtk.Dialog</methodname>()</link>,
    <link
    linkend="method-gtkdialog--add-button"><methodname>add_button</methodname>()</link>,
    or <link
    linkend="method-gtkdialog--add-action-widget"><methodname>add_action_widget</methodname>()</link>,
    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 <xref linkend="gtk-response-type-constants"
    endterm="gtk-response-type-constants-title"></xref> (these all have
    values less than zero).</para>

    <para>If a dialog receives a delete event, the "response" signal will be
    emitted with a response ID of
    <literal>gtk.RESPONSE_DELETE_EVENT</literal>.</para>

    <para>If you want to block waiting for a dialog to return before
    returning control flow to your code, you can call <link
    linkend="method-gtkdialog--run"><methodname>run</methodname>()</link>. 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.</para>

  </refsect1>

  <refsect1 id="constructor-gtkdialog">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
      <methodname>gtk.Dialog</methodname>
      <methodparam><parameter role="keyword">title</parameter><initializer>None</initializer></methodparam>
      <methodparam><parameter role="keyword">parent</parameter><initializer>None</initializer></methodparam>
      <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam>
      <methodparam><parameter role="keyword">buttons</parameter><initializer>None</initializer></methodparam>
    </constructorsynopsis></programlisting>

    <variablelist>
      <varlistentry>
        <term><parameter role="keyword">title</parameter>&nbsp;:</term>
        <listitem><simpara>The title of the dialog, or <literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter role="keyword">parent</parameter>&nbsp;:</term>
        <listitem><simpara>The transient parent of the dialog, or <literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
        <listitem><simpara>flags that control the operation of the dialog</simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter role="keyword">buttons</parameter>&nbsp;:</term>
        <listitem><simpara>a tuple containing button text/response id pairs or <literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis>Returns</emphasis>&nbsp;:</term>
        <listitem><simpara>a new <link linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
    linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> with the
    title text specified by <parameter>title</parameter> (or
    <literal>None</literal> for the default title; see <link
    linkend="method-gtkwindow--set-title"><methodname>gtk.Window.set_title</methodname>()</link>)
    and transient parent window specified by <parameter>parent</parameter> (or
    <literal>None</literal> for none; see <link
    linkend="method-gtkwindow--set-transient-for"><methodname>gtk.Window.set_transient_for</methodname>()</link>).
    The <parameter>flags</parameter> argument can be used to make the dialog
    modal (<literal>gtk.DIALOG_MODAL</literal>) and/or to have it destroyed
    along with its transient parent
    (<literal>gtk.DIALOG_DESTROY_WITH_PARENT</literal>) and/or remove the
    separator (<literal>gtk.DIALOG_NO_SEPARATOR</literal>) (see the <xref
    linkend="gtk-dialog-flag-constants"
    endterm="gtk-dialog-flag-constants-title"></xref> for more
    information). After <parameter>flags</parameter>, a tuple of button
    text/response ID pairs should be listed, or <literal>None</literal> (the
    default value) if no buttons are needed. The button text can be either a
    stock ID such as <literal>gtk.STOCK_OK</literal>, or some arbitrary text.  A
    response ID can be any positive number, or one of the pre-defined <xref
    linkend="gtk-response-type-constants"
    endterm="gtk-response-type-constants-title"></xref>.</para>

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

<para>Here's a simple example:</para>
<programlisting>
  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))
</programlisting>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkdialog--add-action-widget">
      <title>gtk.Dialog.add_action_widget</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_action_widget</methodname>
        <methodparam><parameter role="keyword">child</parameter></methodparam>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">child</parameter>&nbsp;:</term>
          <listitem><simpara>an activatable widget</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>a response ID</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>add_action_widget</methodname>() method adds an
      activatable widget to the action area of a <link
      linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>,
      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 <literal>action_area</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--add-button">
      <title>gtk.Dialog.add_button</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_button</methodname>
        <methodparam><parameter role="keyword">button_text</parameter></methodparam>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">button_text</parameter>&nbsp;:</term>
          <listitem><simpara>the text of the button, or a stock ID</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>the response ID for the button</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the button widget that was added</simpara></listitem>
        </varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="method-gtkdialog--add-buttons">
      <title>gtk.Dialog.add_buttons</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_buttons</methodname>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>one or more pairs of button specifiers: button text (or stock ID) and a response id</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>add_buttons</methodname>() method adds several
      buttons to the <link
      linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link> using the
      button data passed as arguments to the method. This method is the same as
      calling the <link
      linkend="method-gtkdialog--add-button"><methodname>gtk.Dialog.add_button</methodname>()</link>
      repeatedly. The button data pairs - button text (or stock ID) and a response
      ID integer are passed individually. For example:</para>

      <programlisting>
        dialog.add_buttons(gtk.STOCK_OPEN, 42, "Close", gtk.RESPONSE_CLOSE)
      </programlisting>

      <para>will add "Open" and "Close" buttons to <parameter>dialog</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--set-response-sensitive">
      <title>gtk.Dialog.set_response_sensitive</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_response_sensitive</methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
        <methodparam><parameter role="keyword">setting</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>a response ID</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
          <listitem><simpara>the new value for sensitive</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>set_response_sensitive</methodname>() method
      calls the <link
      linkend="method-gtkwidget--set-sensitive"><methodname>gtk.Window.set_sensitive</methodname>()</link> 
      method with the specified <parameter>response_id</parameter> for each widget
      in the dialog's action area. This method is a convenience function to
      sensitize/desensitize all dialog buttons at once.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--set-default-response">
      <title>gtk.Dialog.set_default_response</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_default_response</methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>a response ID</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>set_default_response</methodname>() method sets
      the last widget in the dialog's action area with the specified
      <parameter>response_id</parameter> as the default widget for the dialog.
      Pressing <keycap>Enter</keycap> normally activates the default
      widget.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--set-has-separator">
      <title>gtk.Dialog.set_has_separator</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_has_separator</methodname>
        <methodparam><parameter role="keyword">setting</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
          <listitem><simpara>If <literal>True</literal> use a separator</simpara></listitem>
        </varlistentry>
      </variablelist>

      <warning>
        <para>
          This method is deprecated in PyGTK 2.22 and above and should not be
          used in newly-written code.
        </para>
      </warning>

      <para>The <methodname>set_has_separator</methodname>() method sets the
      "has-separator" property to the value of <parameter>setting</parameter>. If
      <parameter>setting</parameter> is <literal>True</literal> (the default
      value) the dialog has a separator above the buttons.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--get-has-separator">
      <title>gtk.Dialog.get_has_separator</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_has_separator</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the value of the "has-separator" property</simpara></listitem>
        </varlistentry>
      </variablelist>

      <warning>
        <para>
          This method is deprecated in PyGTK 2.22 and above and should not be
          used in newly-written code.
        </para>
      </warning>

      <para>The <methodname>get_has_separator</methodname>() method returns
      the value of the "has-separator" property.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--response">
      <title>gtk.Dialog.response</title>

      <programlisting><methodsynopsis language="python">
        <methodname>response</methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>response ID</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The <methodname>response</methodname>() method emits the
      "response" signal with the value specified in
      <parameter>response_id</parameter>. This method is used to indicate that the
      user has responded to the dialog in some way; typically either you or <link
      linkend="method-gtkdialog--run"><function>gtk.Dialog.run()</function></link>
      will be monitoring the "response" signal and take appropriate action.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--run">
      <title>gtk.Dialog.run</title>

      <programlisting><methodsynopsis language="python">
        <methodname>run</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a response ID</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>During the <methodname>run</methodname>() 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
      <methodname>run</methodname>() method will return
      <literal>gtk.RESPONSE_DELETE_EVENT</literal>. Also, during the
      <methodname>run</methodname>() method the dialog will be modal. You can
      force the <methodname>run</methodname>() method to return at any time by
      calling <link linkend="method-gtkdialog--response"><methodname>response</methodname>()</link> 
      to emit the "response" signal. Destroying the dialog during the
      <methodname>run</methodname>() method is a very bad idea, because your
      post-run code won't know whether the dialog was destroyed or not.</para>

      <para>After the <methodname>run</methodname>() method returns, you are
      responsible for hiding or destroying the dialog as needed.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--set-alternative-button-order">
      <title>gtk.Dialog.set_alternative_button_order</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_alternative_button_order</methodname>
        <methodparam><parameter role="keyword">new_order</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">new_order</parameter>&nbsp;:</term>
          <listitem><simpara>a sequence containing response id integer values</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_alternative_button_order</methodname>()
      method sets an alternative button order for the dialog based on the sequence
      of response ids specified by <parameter>new_order</parameter>. If the
      "gtk-alternative-button-order" property of the <link
      linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
      object is set to <literal>True</literal>, the dialog buttons are reordered
      according to the order of the response ids passed to this method.</para>

      <para>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
      <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>s
      do provide an alternative button order, which is more suitable on some
      platforms, e.g. Windows.</para>

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

      <programlisting>
  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])
</programlisting>

    </refsect2>

    <refsect2 id="method-gtkdialog--get-response-for-widget">
      <title>gtk.Dialog.get_response_for_widget</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_response_for_widget</methodname>
        <methodparam><parameter role="keyword">widget</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
          <listitem><simpara>a widget in the action area of the dialog</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara> the response id of <parameter>widget</parameter>, or gtk.RESPONSE_NONE if the widget doesn't have a response id set.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <methodname>get_response_for_widget</methodname>() method
      returns the response id of the widget specified by
      <parameter>widget</parameter> in the action area of the dialog.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--get-widget-for-response">
      <title>gtk.Dialog.get_widget_for_response</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_widget_for_response</methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>the response ID used by the dialog widget </simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the widget button that uses the given response_id, or <literal>None</literal>.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_widget_for_response</methodname>() method returns the widget button
      that uses the given response ID in the action area of a dialog, or <literal>None</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--get-action-area">
      <title>gtk.Dialog.get_action_area</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_action_area</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the action area.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>The <methodname>get_action_area</methodname>() method
      returns the action area of dialog.</para>

    </refsect2>

    <refsect2 id="method-gtkdialog--get-content-area">
      <title>gtk.Dialog.get_content_area</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_content_area</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the content area <link linkend="class-gdkscreen"><classname>gtk.VBox</classname></link>.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>The <methodname>get_content_area</methodname>() method
      returns the content area of dialog.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--alternative-dialog-button-order">
      <title>gtk.alternative_dialog_button_order</title>

      <programlisting><methodsynopsis language="python">
        <methodname>gtk.alternative_dialog_button_order</methodname>
        <methodparam><parameter role="keyword">screen</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
          <listitem><simpara>the <link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link> or <literal>None</literal> to use the default screen</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the alternative button order should be used</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <function>gtk.alternative_dialog_button_order</function>()
      returns <literal>True</literal> if the alternative button order should be
      used for the <link linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
      specified by <parameter>screen</parameter>. If <parameter>screen</parameter>
      is <literal>None</literal> the default <link
      linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link> is used.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkdialog--close">
      <title>The "close" gtk.Dialog Signal</title>

      <programlisting><methodsynopsis language="python">
        <methodname>callback</methodname>
        <methodparam><parameter>dialog</parameter></methodparam>
        <methodparam><parameter>user_param1</parameter></methodparam>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>dialog</parameter>&nbsp;:</term>
          <listitem><simpara>the dialog that received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified with the <link linkend="method-gobject--connect"><methodname>connect</methodname>()</link> method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>The "close" signal is emitted when the dialog is closed.</para>

    </refsect2>

    <refsect2 id="signal-gtkdialog--response">
      <title>The "response" gtk.Dialog Signal</title>

      <programlisting><methodsynopsis language="python">
        <methodname>callback</methodname>
        <methodparam><parameter>dialog</parameter></methodparam>
        <methodparam><parameter>response_id</parameter></methodparam>
        <methodparam><parameter>user_param1</parameter></methodparam>
        <methodparam><parameter>...</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter>dialog</parameter>&nbsp;:</term>
          <listitem><simpara>the dialog that received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>response_id</parameter>&nbsp;:</term>
          <listitem><simpara>the response id received by the dialog</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified with the <link linkend="method-gobject--connect"><methodname>connect</methodname>()</link> method</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>...</parameter>&nbsp;:</term>
          <listitem><simpara>additional user parameters (if any)</simpara></listitem>
        </varlistentry>
      </variablelist>

      <para>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 <link
      linkend="method-gtkdialog--response"><methodname>response</methodname>()</link> 
      method. When a delete_event triggers the "response" signal the
      <parameter>response_id</parameter> will be
      <literal>gtk.RESPONSE_DELETE_EVENT</literal>.</para>

    </refsect2>

  </refsect1>

</refentry>