path: root/docs/reference/pygtk-gtkinfobar.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-gtkinfobar">
  <refnamediv>
    <refname>gtk.InfoBar</refname>
    <refpurpose>report important messages to the user (new in PyGTK 2.22)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.InfoBar</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkhbox">gtk.HBox</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkinfobar">gtk.InfoBar</link></methodname>
        <methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--get-action-area">get_action_area</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--get-content-area">get_content_area</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--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-gtkinfobar--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-gtkinfobar--add-buttons">add_buttons</link></methodname>
        <methodparam><parameter role="keyword">first_button_text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--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-gtkinfobar--set-default-response">set_default_response</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--response">response</link></methodname>
        <methodparam><parameter role="keyword">response_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--set-message-type">set_message_type</link></methodname>
        <methodparam><parameter role="keyword">message_type</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkinfobar--get-message-type">get_message_type</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-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-gtkbox">gtk.Box</link>
          +-- <link linkend="class-gtkhbox">gtk.HBox</link>
            +-- <link linkend="class-gtkinfobar">gtk.InfoBar</link>
</synopsis>

  </refsect1>


  <refsect1>
    <title>Implemented Interfaces</title>
    <para>
      <link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link>
      implements
      <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
      <link linkend="class-atkimplementor"><classname>atk.ImplementorIFace</classname></link>
    </para>
  </refsect1>

  <refsect1 id="properties-gtkinfobar">
    <title>gtk.InfoBar 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-gtkbox">gtk.Box 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="4in"/>
          <tbody>
            <row valign="top">
              <entry>"message-type"</entry>
              <entry>Read-Write-Construct</entry>
              <entry>The type of the message.
              The type is used to determine the colors to use in the info bar. The following
              symbolic color names can by used to customize these colors: "info_fg_color",
              "info_bg_color", "warning_fg_color", "warning_bg_color", "question_fg_color",
              "question_bg_color", "error_fg_color", "error_bg_color". "other_fg_color", "other_bg_color".
              If the type is gtk.MESSAGE_OTHER, no info bar is painted but the colors are still set.
              Default value: gtk.MESSAGE_INFO
              This property is available in GTK+ 2.18 and above.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkinfobar">
    <title>gtk.InfoBar 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="4in"/>
          <tbody>
            <row valign="top">
              <entry>"action-area-border"</entry>
              <entry>Read</entry>
              <entry>Width of the border around the action area of the info bar.
              Allowed values: &gt;= 0
              Default value: 5
              This property is available in GTK+ 2.18 and above.</entry>
            </row>
            <row valign="top">
              <entry>"button-spacing"</entry>
              <entry>Read</entry>
              <entry>Spacing between buttons in the action area of the info bar.
              Allowed values: &gt;=0
              Default value: 6
              This property is available in GTK+ 2.18 and above.</entry>
            </row>
            <row valign="top">
              <entry>"content-area-border"</entry>
              <entry>Read</entry>
              <entry>The width of the border around the content content area of the info bar.
              Allowed values: &gt;=0
              Default value: 8
              This property is available in GTK+ 2.18 and above.</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 info bar.
              Allowed values: &gt;=0
              Default value: 16
              This property is available in GTK+ 2.18 and above.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkinfobar">
    <title>gtk.InfoBar 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>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkinfobar--close">close</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>infobar</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkinfobar--response">response</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>infobar</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>

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

    <para><link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link>
    is a widget that can be used to show messages to the user without showing a dialog.
    It is often temporarily shown at the top or bottom of a document. In contrast to
    <link linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>, which has
    a horizontal action area at the bottom,
    <link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link> has a vertical
    action area at the side.</para>
  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <programlisting>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkinfobar">gtk.InfoBar</link></methodname>
        <methodparam></methodparam>
      </constructorsynopsis>
    </programlisting>
    <variablelist>
      <varlistentry>
        <term><emphasis>Returns</emphasis>&nbsp;:</term>
        <listitem><simpara>a new <link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link> object</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new <link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link> object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkinfobar--get-action-area">
      <title>gtk.InfoBar.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.22 and above.</para>
      </note>

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

    </refsect2>

    <refsect2 id="method-gtkinfobar--get-content-area">
      <title>gtk.InfoBar.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</simpara></listitem>
        </varlistentry>
      </variablelist>

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

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

    </refsect2>

    <refsect2 id="method-gtkinfobar--add-action-widget">
      <title>gtk.InfoBar.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>response ID for <parameter>child</parameter></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Add an activatable widget to the action area of a
<link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link>,
connecting a signal handler that will emit the
<link linkend="class-gtkinfobar"><classname>gtk.InfoBar</classname></link>::response
signal on the message area when the widget is activated. The widget
is appended to the end of the message areas action area.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--add-button">
      <title>gtk.InfoBar.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>text of button, or stock ID</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">response_id</parameter>&nbsp;:</term>
          <listitem><simpara>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>

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

      <para>Adds a button with the given 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 given response_id. The button is appended
to the end of the info bars's action area. The button widget is
returned, but usually you don't need it.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--add-buttons">
      <title>gtk.InfoBar.add_buttons</title>

      <programlisting>
        <methodsynopsis language="python">
          <methodname>add_buttons</methodname>
          <methodparam><parameter role="keyword">first_button_text</parameter></methodparam>
          <methodparam><parameter role="keyword">first_response_id</parameter></methodparam>
          <methodparam><parameter role="keyword">...</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">first_button_text</parameter>&nbsp;:</term>
          <listitem><simpara>button text or stock ID</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">first_response_id</parameter>&nbsp;:</term>
          <listitem><simpara>response ID for the button</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Adds more buttons, same as calling
<link linkend="method-gtkinfobar--add-button"><methodname>add_button</methodname></link>()
repeatedly. Each button must have both text and response ID.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--set-response-sensitive">
      <title>gtk.InfoBar.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>TRUE for sensitive</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Calls <link linkend="method-gtkwidget--set-sensitive"><methodname>gtk.Widget.set_sensitive</methodname>()</link>
for each widget in the info bars's action area with the given response_id.
A convenient way to sensitize/desensitize dialog buttons.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--set-default-response">
      <title>gtk.InfoBar.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>

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

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

      <para> Note that this function currently requires the infobar to
be added to a widget hierarchy.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--response">
      <title>gtk.InfoBar.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>a response ID</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Emits the 'response' signal with the given <parameter>response_id</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--set-message-type">
      <title>gtk.InfoBar.set_message_type</title>

      <programlisting>
        <methodsynopsis language="python">
          <methodname>set_message_type</methodname>
          <methodparam><parameter role="keyword">message_type</parameter></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">message_type</parameter>&nbsp;:</term>
          <listitem><simpara>a <literal>GtkMessageType</literal></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>set_message_type</methodname>() method sets
the message type of the message area. GTK+ uses this type to determine what
color to use when drawing the message area.</para>

    </refsect2>

    <refsect2 id="method-gtkinfobar--get-message-type">
      <title>gtk.InfoBar.get_message_type</title>

      <programlisting>
        <methodsynopsis language="python">
          <methodname>get_message_type</methodname>
          <methodparam></methodparam>
        </methodsynopsis>
      </programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the message type of the message area.</simpara></listitem>
        </varlistentry>
      </variablelist>
      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_message_type</methodname>() method returns
      the message type of the message area.</para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkinfobar--close">
      <title>The "close" gtk.InfoBar Signal</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter>infobar</parameter>&nbsp;:</term>
          <listitem><simpara>the infobar 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>

      <note>
        <para>This signal is available in GTK+ 2.18 and above.</para>
      </note>

      <para>The "close" signal keybinding signal which gets emitted when the user
      uses a keybinding to dismiss the info bar. The default binding for this signal
      is the Escape key.</para>

    </refsect2>

    <refsect2 id="signal-gtkinfobar--response">
      <title>The "response" gtk.InfoBar Signal</title>

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

      <variablelist>
        <varlistentry>
          <term><parameter>infobar</parameter>&nbsp;:</term>
          <listitem><simpara>the infobar that received the signal</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter>response_id</parameter>&nbsp;:</term>
          <listitem><simpara>the response ID</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>

      <note>
        <para>This signal is available in GTK+ 2.18 and above.</para>
      </note>

      <para>The "response" signal is emitted when an action widget is clicked or the
      application programmer calls <link linkend="method-gtkinfobar--response"><methodname>response</methodname></link>().
      The response_id depends on which action widget was clicked.</para>

    </refsect2>
  </refsect1>
</refentry>