diff options
author | Dieter Verfaillie <dieterv@optionexplicit.be> | 2011-03-15 15:54:30 +0100 |
---|---|---|
committer | Dieter Verfaillie <dieterv@optionexplicit.be> | 2011-03-18 20:21:32 +0100 |
commit | f835813c6b5f7824e3f1c2a84e9ecf0d2f09ea5f (patch) | |
tree | 5562bf32879c22b5c800d525ee48b247326489bf /docs/reference | |
parent | 3f832b40642c0343810f3e64f0a53702a00ecffe (diff) | |
download | pygtk-f835813c6b5f7824e3f1c2a84e9ecf0d2f09ea5f.tar.gz |
reference: pygtk-gtkinfobar.xml: add purpose, interfaces, properties and signals + update methods
Diffstat (limited to 'docs/reference')
-rw-r--r-- | docs/reference/pygtk-gtkinfobar.xml | 288 |
1 files changed, 269 insertions, 19 deletions
diff --git a/docs/reference/pygtk-gtkinfobar.xml b/docs/reference/pygtk-gtkinfobar.xml index 63eb216a..15cfbc03 100644 --- a/docs/reference/pygtk-gtkinfobar.xml +++ b/docs/reference/pygtk-gtkinfobar.xml @@ -5,7 +5,7 @@ <refentry id="class-gtkinfobar"> <refnamediv> <refname>gtk.InfoBar</refname> - <refpurpose></refpurpose> + <refpurpose>report important messages to the user (new in PyGTK 2.22)</refpurpose> </refnamediv> <refsect1> @@ -79,6 +79,152 @@ </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: >= 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: >=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: >=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: >=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> @@ -94,13 +240,13 @@ <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> @@ -121,11 +267,13 @@ <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 <parameter>info_bar</parameter>.</para> + <para>The <methodname>get_action_area</methodname>() method returns the action area of the infobar.</para> + </refsect2> <refsect2 id="method-gtkinfobar--get-content-area"> @@ -143,11 +291,13 @@ <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 <parameter>info_bar</parameter>.</para> + <para>The <methodname>get_content_area</methodname>() method returns the content area of the infobar.</para> + </refsect2> <refsect2 id="method-gtkinfobar--add-action-widget"> @@ -170,14 +320,18 @@ <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 + <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"> @@ -204,6 +358,7 @@ is appended to the end of the message areas action area.</para> <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> @@ -213,6 +368,7 @@ 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"> @@ -222,6 +378,8 @@ returned, but usually you don't need it.</para> <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> @@ -229,15 +387,20 @@ returned, but usually you don't need it.</para> <term><parameter role="keyword">first_button_text</parameter> :</term> <listitem><simpara>button text or stock ID</simpara></listitem> </varlistentry> + <varlistentry> + <term><parameter role="keyword">first_response_id</parameter> :</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>gtk.InfoBar.add_button</methodname></link> -repeatedly. The variable argument list should be <literal>NULL</literal>-terminated -as with <function>gtk_info_bar_new_with_buttons()</function>. Each button must have both -text and response ID.</para> + <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"> @@ -260,13 +423,15 @@ text and response ID.</para> <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 gtk_widget_set_sensitive (widget, setting) for each -widget in the info bars's action area with the given response_id. + <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"> @@ -289,13 +454,15 @@ A convenient way to sensitize/desensitize dialog buttons.</para> <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 + <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 <parameter>info_bar</parameter> to + + <para> Note that this function currently requires the infobar to be added to a widget hierarchy.</para> + </refsect2> <refsect2 id="method-gtkinfobar--response"> @@ -313,11 +480,13 @@ be added to a widget hierarchy.</para> <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"> @@ -335,13 +504,15 @@ be added to a widget hierarchy.</para> <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> + <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"> @@ -363,9 +534,88 @@ when drawing the message area.</para> <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> + <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> :</term> + <listitem><simpara>the infobar that received the signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</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> :</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> :</term> + <listitem><simpara>the infobar that received the signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>response_id</parameter> :</term> + <listitem><simpara>the response ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_param1</parameter> :</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> :</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> |