[pygtk] Add docs for the new class gtk.Activatable
- From: Gian Mario Tagliaretti <gianmt src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [pygtk] Add docs for the new class gtk.Activatable
- Date: Thu, 13 Aug 2009 15:06:22 +0000 (UTC)
commit 6df9c85c2ab6bcbdeacde2f127e769905b67d95b
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date: Thu Aug 13 17:05:53 2009 +0200
Add docs for the new class gtk.Activatable
docs/Makefile.am | 14 +-
docs/reference/pygtk-gtk-classes.xml | 1 +
docs/reference/pygtk-gtkactivatable.xml | 351 +++++++++++++++++++++++++++++++
3 files changed, 360 insertions(+), 6 deletions(-)
---
diff --git a/docs/Makefile.am b/docs/Makefile.am
index aaf6363..90af941 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -34,7 +34,7 @@ XMLFILES = \
reference/pygtk-atktext.xml \
reference/pygtk-atkvalue.xml \
reference/pygtk-gdkapplaunchcontext.xml \
- reference/pygtk-gdkatom.xml \
+ reference/pygtk-gdkatom.xml \
reference/pygtk-gdkcairocontext.xml \
reference/pygtk-gdk-classes.xml \
reference/pygtk-gdkcolormap.xml \
@@ -72,6 +72,7 @@ XMLFILES = \
reference/pygtk-gtkaccessible.xml \
reference/pygtk-gtkactiongroup.xml \
reference/pygtk-gtkaction.xml \
+ reference/pygtk-gtkactivatable.xml \
reference/pygtk-gtkadjustment.xml \
reference/pygtk-gtkalignment.xml \
reference/pygtk-gtkarrow.xml \
@@ -163,7 +164,7 @@ XMLFILES = \
reference/pygtk-gtkmenu.xml \
reference/pygtk-gtkmessagedialog.xml \
reference/pygtk-gtkmisc.xml \
- reference/pygtk-gtkmountoperation.xml \
+ reference/pygtk-gtkmountoperation.xml \
reference/pygtk-gtknotebook.xml \
reference/pygtk-gtkobject.xml \
reference/pygtk-gtkoptionmenu.xml \
@@ -228,7 +229,7 @@ XMLFILES = \
reference/pygtk-gtktoolbar.xml \
reference/pygtk-gtktoolbutton.xml \
reference/pygtk-gtktoolitem.xml \
- reference/pygtk-gtktoolshell.xml \
+ reference/pygtk-gtktoolshell.xml \
reference/pygtk-gtktooltip.xml \
reference/pygtk-gtktooltips.xml \
reference/pygtk-gtktreedragdest.xml \
@@ -322,7 +323,7 @@ HTML_FILES = \
html/class-atktext.html \
html/class-atkvalue.html \
html/class-gdkatom.html \
- html/class-gdkapplaunchcontext.html \
+ html/class-gdkapplaunchcontext.html \
html/class-gdkcairocontext.html \
html/class-gdkcolor.html \
html/class-gdkcolormap.html \
@@ -355,6 +356,7 @@ HTML_FILES = \
html/class-gtkaccessible.html \
html/class-gtkactiongroup.html \
html/class-gtkaction.html \
+ html/class-gtkactivatable.html \
html/class-gtkadjustment.html \
html/class-gtkalignment.html \
html/class-gtkarrow.html \
@@ -443,7 +445,7 @@ HTML_FILES = \
html/class-gtkmenutoolbutton.html \
html/class-gtkmessagedialog.html \
html/class-gtkmisc.html \
- html/class-gtkmountoperation.html \
+ html/class-gtkmountoperation.html \
html/class-gtknotebook.html \
html/class-gtkobject.html \
html/class-gtkoptionmenu.html \
@@ -507,7 +509,7 @@ HTML_FILES = \
html/class-gtktoolbar.html \
html/class-gtktoolbutton.html \
html/class-gtktoolitem.html \
- html/class-gtktoolshell.html \
+ html/class-gtktoolshell.html \
html/class-gtktooltip.html \
html/class-gtktooltips.html \
html/class-gtktreedragdest.html \
diff --git a/docs/reference/pygtk-gtk-classes.xml b/docs/reference/pygtk-gtk-classes.xml
index 47084e7..04a83ed 100644
--- a/docs/reference/pygtk-gtk-classes.xml
+++ b/docs/reference/pygtk-gtk-classes.xml
@@ -13,6 +13,7 @@
<xi:include href="pygtk-gtkaccessible.xml"/>
<xi:include href="pygtk-gtkaction.xml"/>
<xi:include href="pygtk-gtkactiongroup.xml"/>
+ <xi:include href="pygtk-gtkactivatable.xml"/>
<xi:include href="pygtk-gtkadjustment.xml"/>
<xi:include href="pygtk-gtkalignment.xml"/>
<xi:include href="pygtk-gtkarrow.xml"/>
diff --git a/docs/reference/pygtk-gtkactivatable.xml b/docs/reference/pygtk-gtkactivatable.xml
new file mode 100644
index 0000000..6518a6e
--- /dev/null
+++ b/docs/reference/pygtk-gtkactivatable.xml
@@ -0,0 +1,351 @@
+<?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-gtkactivatable">
+ <refnamediv>
+ <refname>gtk.Activatable</refname>
+ <refpurpose>An interface for activatable widgets.</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Synopsis</title>
+
+ <classsynopsis language="python">
+ <ooclass><classname>gtk.Activatable</classname></ooclass>
+ <ooclass><classname><link linkend="class-ginterface">gobject.GInterface</link></classname></ooclass>
+
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">do_set_related_action</link></methodname>
+ <methodparam><parameter role="keyword">action</parameter></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--get-related-action">get_related_action</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--get-use-action-appearence">get_use_action_appearence</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--set-related-action">set_related_action</link></methodname>
+ <methodparam><parameter role="keyword">action</parameter></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--set-use-action-appearence">set_use_action_appearence</link></methodname>
+ <methodparam><parameter role="keyword">use_appearence</parameter></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gtkactivatable--sync-action-properties">sync_action_properties</link></methodname>
+ <methodparam><parameter role="keyword">action</parameter></methodparam>
+ </methodsynopsis>
+
+ </classsynopsis>
+ </refsect1>
+
+ <refsect1>
+ <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-ginterface">gobject.GInterface</link>
+ +-- <link linkend="class-gtkactivatable">gtk.Activatable</link>
+</synopsis>
+
+ </refsect1>
+
+ <refsect1 id="properties-gtkactivatable">
+ <title>gtk.Activatable Properties</title>
+
+ <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>"related-action"</entry>
+ <entry>Read/Write</entry>
+ <entry>
+ The action that this activatable will activate and receive updates from for various states and possibly appearance.
+ Note: <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ implementors need to handle the "related-action" property and call
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
+ when it changes.
+ </entry>
+ </row>
+ <row valign="top">
+ <entry>"use-action-appearance"</entry>
+ <entry>Read/Write</entry>
+ <entry>
+ Whether this activatable should reset its layout and appearance when setting the related
+ action or when the action changes appearance.
+ See the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> documentation
+ directly to find which properties should be ignored by the
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ when this property is <literal>False</literal>.
+ Note: <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ implementors need to handle the "related-action" property and call
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
+ when it changes. Default value: <literal>True</literal>. This property is available in GTK+ 2.16 and above.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </blockquote>
+ </refsect1>
+
+ <refsect1>
+ <title>Known Implementation</title>
+ <para>
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ is implementated by
+ <link linkend="class-gtktearoffmenuitem"><classname>gtk.TearoffMenuItem</classname></link>,
+ <link linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>,
+ <link linkend="class-gtklinkbutton"><classname>gtk.LinkButton</classname></link>,
+ <link linkend="class-gtkradiobutton"><classname>gtk.RadioButton</classname></link>,
+ <link linkend="class-gtkradiotoolbutton"><classname>gtk.RadioToolButton</classname></link>,
+ <link linkend="class-gtktogglebutton"><classname>gtk.ToggleButton</classname></link>,
+ <link linkend="class-gtkseparatormenuitem"><classname>gtk.SeparatorMenuItem</classname></link>,
+ <link linkend="class-gtkimagemenuitem"><classname>gtk.ImageMenuItem</classname></link>,
+ <link linkend="class-gtkcheckbutton"><classname>gtk.CheckButton</classname></link>,
+ <link linkend="class-gtkradiomenuitem"><classname>gtk.RadioMenuItem</classname></link>,
+ <link linkend="class-gtkbutton"><classname>gtk.Button</classname></link>,
+ <link linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>,
+ <link linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>,
+ <link linkend="class-gtkrecentchoosermenu"><classname>gtk.RecentChooserMenu</classname></link>,
+ <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>,
+ <link linkend="class-gtkseparatortoolitem"><classname>gtk.SeparatorToolItem</classname></link>,
+ <link linkend="class-gtkcheckmenuitem"><classname>gtk.CheckMenuItem</classname></link>,
+ <link linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>,
+ <link linkend="class-gtkfontbutton"><classname>gtkFontButton.</classname></link>,
+ <link linkend="class-gtkscalebutton"><classname>gtk.ScaleButton</classname></link>,
+ <link linkend="class-gtktoggletoolbutton"><classname>gtk.ToggleToolButton</classname></link>,
+ <link linkend="class-gtkvolumebutton"><classname>gtk.VolumeButton</classname></link>,
+ <link linkend="class-gtkcolorbutton"><classname>gtk.ColorButton</classname></link>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Activatable widgets can be connected to a
+ <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
+ and reflects the state of its action. A GtkActivatable can also provide
+ feedback through its action, as they are responsible for activating their related actions.
+ </para>
+ <para>
+ When extending a class that is already <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ it is only necessary to implement the
+ <methodname><link linkend="method-gtkactivatable--do-sync-action-properties">gtk.Activatable.do_sync_action_properties</link></methodname> and
+ <methodname><link linkend="method-gtkactivatable--do-update">gtk.Activatable.do_update</link></methodname>()
+ class methods and chain up to the parent implementation, however when introducing a new
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ class the "related-action" and "use-action-appearance" properties need to be handled by the implementor.
+ Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance,
+ and calling
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>() and
+ <methodname><link linkend="method-gtkactivatable--sync-action-properties">gtk.Activatable.sync_action_properties</link></methodname>()
+ at the appropriate times.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Methods</title>
+
+ <refsect2 id="method-gtkactivatable--do-set-related-action">
+ <title>gtk.Activatable.do_set_related_action</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>do_set_related_action</methodname>
+ <methodparam><parameter>action</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">action</parameter> :</term>
+ <listitem><simpara>
+ the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> to set.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <para>
+ The <methodname>do_set_related_action</methodname>() method is an
+ utility function for
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ implementors.
+ </para>
+ <para>
+ When implementing <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ you must call this when handling changes of the "related-action", and you must also
+ use this to break references in GObject->dispose().
+ </para>
+ <para>
+ This function adds a reference to the currently set related action for you,
+ it also makes sure the GtkActivatable->update() method is called when the related
+ <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
+ properties change and registers to the action's proxy list.
+ </para>
+ <note>
+ Be careful to call this before setting the local copy of the
+ <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
+ property, since this function uses
+ <methodname><link linkend="method-gtkactivatable--get-related-action">gtk.Activatable.get_related_action</link></methodname>()
+ to retrieve the previous action
+ </note>
+ </refsect2>
+
+ <refsect2 id="method-gtkactivatable--get-related-action">
+ <title>gtk.Activatable.get_related_action</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_related_action</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>the related <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
+ if one is set. </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <para>
+ The <methodname>get_related_action</methodname>() method gets the related
+ <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> for activatable.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-gtkactivatable--get-use-action-appearence">
+ <title>gtk.Activatable.get_use_action_appearence</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_use_action_appearence</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>whether activatable uses its actions appearance.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <para>
+ The <methodname>get_use_action_appearence</methodname>() method gets whether
+ this activatable should reset its layout and appearance when setting the
+ related action or when the action changes appearance.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-gtkactivatable--set-related-action">
+ <title>gtk.Activatable.set_related_action</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>set_related_action</methodname>
+ <methodparam><parameter>action</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">action</parameter> :</term>
+ <listitem><simpara>the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> to set.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <note>
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ implementors need to handle the "related-action" property and call
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
+ when it changes.
+ </note>
+
+ <para>
+ The <methodname>set_related_action</methodname>() method sets the related action on the activatable object.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-gtkactivatable--set-use-action-appearence">
+ <title>gtk.Activatable.set_use_action_appearence</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>set_use_action_appearence</methodname>
+ <methodparam><parameter>use_appearence</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">use_appearence</parameter> :</term>
+ <listitem><simpara>whether to use the actions appearance.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <note>
+ <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
+ implementors need to handle the "related-action" property and call
+ <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
+ when it changes.
+ </note>
+
+ <para>
+ The <methodname>set_use_action_appearence</methodname>() method sets whether
+ this activatable should reset its layout and appearance when setting the
+ related action or when the action changes appearance
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-gtkactivatable--sync-action-properties">
+ <title>gtk.Activatable.sync_action_properties</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>sync_action_properties</methodname>
+ <methodparam><parameter>action</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">action</parameter> :</term>
+ <listitem><simpara>the related <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
+ or <literal>None</literal>
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>This method is available in PyGTK 2.16 and above.</para>
+ </note>
+
+ <para>
+ The <methodname>set_use_action_appearence</methodname>() method is called to
+ update the activatable completely, this is called internally when the "related-action"
+ property is set or unset and by the implementing class when "use-action-appearance" changes.
+ </para>
+ </refsect2>
+ </refsect1>
+</refentry>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
