reference: pygtk-gtktoolitemgroup.xml: add purpose, interfaces, properties and signals + update methods

1 files changed, 229 insertions, 18 deletions

diff --git a/docs/reference/pygtk-gtktoolitemgroup.xml b/docs/reference/pygtk-gtktoolitemgroup.xml
index 771fd023..25c88290 100644
--- a/docs/reference/pygtk-gtktoolitemgroup.xml
+++ b/docs/reference/pygtk-gtktoolitemgroup.xml
@@ -5,7 +5,7 @@
 <refentry id="class-gtktoolitemgroup">
   <refnamediv>
     <refname>gtk.ToolItemGroup</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>a sub container used in a tool palette (new in PyGTK 2.22)</refpurpose>
   </refnamediv>
 
   <refsect1>
@@ -102,6 +102,184 @@
   </refsect1>
 
   <refsect1>
+    <title>Implemented Interfaces</title>
+    <para>
+      <link linkend="class-gtktoolitemgroup"><classname>gtk.ToolItemGroup</classname></link>
+      implements
+      <link linkend="class-atkimplementor"><classname>atk.ImplementorIFace</classname></link>,
+      <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>,
+      <link linkend="class-gtktoolshell"><classname>gtk.ToolShell</classname></link>
+    </para>
+  </refsect1>
+
+  <refsect1 id="properties-gtktoolitemgroup">
+    <title>gtk.ToolItemGroup 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>
+
+    <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>"collapsed"</entry>
+              <entry>Read-Write</entry>
+              <entry>Whether the group has been collapsed and items are hidden.
+              Default value: <literal>False</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"ellipsize"</entry>
+              <entry>Read-Write</entry>
+              <entry>Ellipsize for item group headers.
+              Default value: <literal>pango.ELLIPSIZE_NONE</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"header-relief"</entry>
+              <entry>Read-Write</entry>
+              <entry>Relief of the group header button.
+              Default value: <literal>gtk.RELIEF_NORMAL</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"label"</entry>
+              <entry>Read-Write</entry>
+              <entry>The human-readable title of this item group.
+              Default value: ""
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"label-widget"</entry>
+              <entry>Read-Write</entry>
+              <entry>A widget to display in place of the usual label.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </blockquote>
+
+  </refsect1>
+
+  <refsect1 id="child-properties-gtktoolitemgroup">
+    <title>gtk.ToolItemGroup Child 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="4in"/>
+          <tbody>
+            <row valign="top">
+              <entry>"expand"</entry>
+              <entry>Read-Write</entry>
+              <entry>Whether the item should receive extra space when the group grows.
+              Default value: <literal>False</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"fill"</entry>
+              <entry>Read-Write</entry>
+              <entry>Whether the item should fill the available space.
+              Default value: <literal>True</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"homogeneous"</entry>
+              <entry>Read-Write</entry>
+              <entry>Whether the item should be the same size as other homogeneous items.
+              Default value: <literal>True</literal>.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"new-row"</entry>
+              <entry>Read-Write</entry>
+              <entry>Whether the item should start a new row.
+              Default value: <literal>False</literal>
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"position"</entry>
+              <entry>Read-Write</entry>
+              <entry>Position of the item within this group.
+              Allowed values: &gt;=0.
+              Default value: 0.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </blockquote>
+
+  </refsect1>
+
+  <refsect1 id="style-properties-gtktoolitemgroup">
+    <title>gtk.ToolItemGroup 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>"expander-size"</entry>
+              <entry>Read</entry>
+              <entry>Size of the expander arrow.
+              Allowed values: &gt;=0.
+              Default value: 16.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+            <row valign="top">
+              <entry>"header-spacing"</entry>
+              <entry>Read</entry>
+              <entry>Spacing between expander arrow and caption.
+              Allowed values: &gt;=0.
+              Default value: 2.
+              This property is available in GTK+ 2.20 and above.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </blockquote>
+
+  </refsect1>
+
+  <refsect1 id="signal-prototypes-gtktoolitemgroup">
+    <title>gtk.ToolItemGroup 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>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Description</title>
+
+    <note>
+      <para>This widget is available in PyGTK 2.22 and above.</para>
+    </note>
+
+    <para>A <link linkend="class-gtktoolitemgroup"><classname>gtk.ToolItemGroup</classname></link>
+    is used together with <link linkend="class-gtktoolpalette"><classname>gtk.ToolPalette</classname></link>
+    to add <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link> objects to
+    a palette like container with different categories and drag and drop support.</para>
+
+  </refsect1>
+
+  <refsect1>
     <title>Constructor</title>
 
     <programlisting>
@@ -120,13 +298,13 @@
         <listitem><simpara>a new <link linkend="class-gtktoolitemgroup"><classname>gtk.ToolItemGroup</classname></link>.</simpara></listitem>
       </varlistentry>
     </variablelist>
+
     <note>
       <para>This constructor is available in PyGTK 2.22 and above.</para>
     </note>
 
     <para>Creates a new tool item group with label <parameter>label</parameter>.</para>
 
-
   </refsect1>
 
   <refsect1>
@@ -147,12 +325,14 @@
           <listitem><simpara>the new human-readable label of of the group</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
-      <para>The <methodname>set_label</methodname>() method sets the label of the tool item group. The label is displayed in the header
-of the group.</para>
+      <para>The <methodname>set_label</methodname>() method sets the label of the tool item group.
+      The label is displayed in the header of the group.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--set-label-widget">
@@ -170,13 +350,14 @@ of the group.</para>
           <listitem><simpara>the widget to be displayed in place of the usual label</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>The <methodname>set_label_widget</methodname>() method sets the label of the tool item group.
-The label widget is displayed in the header of the group, in place
-of the usual label.</para>
+      The label widget is displayed in the header of the group, in place of the usual label.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--set-collapsed">
@@ -191,14 +372,16 @@ of the usual label.</para>
       <variablelist>
         <varlistentry>
           <term><parameter role="keyword">collapsed</parameter>&nbsp;:</term>
-          <listitem><simpara>whether the <parameter>group</parameter> should be collapsed or expanded</simpara></listitem>
+          <listitem><simpara><literal>True</literal> if <parameter>group</parameter> should be collapsed, <literal>False</literal> otherwise</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Sets whether the <parameter>group</parameter> should be collapsed or expanded.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--set-ellipsize">
@@ -213,14 +396,17 @@ of the usual label.</para>
       <variablelist>
         <varlistentry>
           <term><parameter role="keyword">ellipsize</parameter>&nbsp;:</term>
-          <listitem><simpara>the <literal>PangoEllipsizeMode</literal> labels in <parameter>group</parameter> should use</simpara></listitem>
+          <listitem><simpara>one of the <xref linkend="pango-ellipsize-mode-constants" endterm="pango-ellipsize-mode-constants-title"></xref> labels in <parameter>group</parameter> should use</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
-      <para>The <methodname>set_ellipsize</methodname>() method sets the ellipsization mode which should be used by labels in <parameter>group</parameter>.</para>
+      <para>The <methodname>set_ellipsize</methodname>() method sets the ellipsize mode which
+      should be used by labels in <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--set-header-relief">
@@ -235,15 +421,17 @@ of the usual label.</para>
       <variablelist>
         <varlistentry>
           <term><parameter role="keyword">style</parameter>&nbsp;:</term>
-          <listitem><simpara>the <literal>GtkReliefStyle</literal></simpara></listitem>
+          <listitem><simpara>one of the <xref linkend="gtk-relief-style-constants" endterm="gtk-relief-style-constants-title"></xref></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Set the button relief of the group header.
-See <link linkend="method-gtkbutton--set-relief"><methodname>gtk.Button.set_relief</methodname></link> for details.</para>
+      See <link linkend="method-gtkbutton--set-relief"><methodname>gtk.Button.set_relief</methodname></link> for details.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-label">
@@ -258,15 +446,17 @@ See <link linkend="method-gtkbutton--set-relief"><methodname>gtk.Button.set_reli
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>the label of <parameter>group</parameter>. The label is an internal string of <parameter>group</parameter> and must not be modified. Note that <literal>NULL</literal> is returned if a custom label has been set with <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.ToolItemGroup.set_label_widget</methodname></link></simpara></listitem>
+          <listitem><simpara>the label of <parameter>group</parameter>. Note that <literal>None</literal> is returned if a custom label has been set with <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.ToolItemGroup.set_label_widget</methodname></link></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the label of <parameter>group</parameter>.</para>
-    </refsect2>
+
+      </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-label-widget">
       <title>gtk.ToolItemGroup.get_label_widget</title>
@@ -283,12 +473,14 @@ See <link linkend="method-gtkbutton--set-relief"><methodname>gtk.Button.set_reli
           <listitem><simpara>the label widget of <parameter>group</parameter></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the label widget of <parameter>group</parameter>.
-See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.ToolItemGroup.set_label_widget</methodname></link>.</para>
+      See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.ToolItemGroup.set_label_widget</methodname></link>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-collapsed">
@@ -303,14 +495,16 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara><literal>TRUE</literal> if <parameter>group</parameter> is collapsed, <literal>FALSE</literal> if it is expanded</simpara></listitem>
+          <listitem><simpara><literal>True</literal> if <parameter>group</parameter> is collapsed, <literal>False</literal> if it is expanded</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets whether <parameter>group</parameter> is collapsed or expanded.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-ellipsize">
@@ -325,14 +519,16 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>the <literal>PangoEllipsizeMode</literal> of <parameter>group</parameter></simpara></listitem>
+          <listitem><simpara>one of the <xref linkend="pango-ellipsize-mode-constants" endterm="pango-ellipsize-mode-constants-title"></xref></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the ellipsization mode of <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-header-relief">
@@ -347,14 +543,16 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
       <variablelist>
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>the <literal>GtkReliefStyle</literal></simpara></listitem>
+          <listitem><simpara>one of the <xref linkend="gtk-relief-style-constants" endterm="gtk-relief-style-constants-title"></xref></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the relief mode of the header button of <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--insert">
@@ -377,11 +575,13 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the position of <parameter>item</parameter> in <parameter>group</parameter>, starting with 0. The position -1 means end of list.</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Inserts <parameter>item</parameter> at <parameter>position</parameter> in the list of children of <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--set-item-position">
@@ -404,11 +604,14 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the new position of <parameter>item</parameter> in <parameter>group</parameter>, starting with 0. The position -1 means end of list.</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
-      <para>The <methodname>set_item_position</methodname>() method sets the position of <parameter>item</parameter> in the list of children of <parameter>group</parameter>.</para>
+      <para>The <methodname>set_item_position</methodname>() method sets the position of
+      <parameter>item</parameter> in the list of children of <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-item-position">
@@ -430,11 +633,13 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the index of <parameter>item</parameter> in <parameter>group</parameter> or -1 if <parameter>item</parameter> is no child of <parameter>group</parameter></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the position of <parameter>item</parameter> in <parameter>group</parameter> as index.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-n-items">
@@ -452,11 +657,13 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the number of tool items in <parameter>group</parameter></simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the number of tool items in <parameter>group</parameter>.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-nth-item">
@@ -478,11 +685,13 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link> at index</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the tool item at <parameter>index</parameter> in group.</para>
+
     </refsect2>
 
     <refsect2 id="method-gtktoolitemgroup--get-drop-item">
@@ -509,11 +718,13 @@ See <link linkend="method-gtktoolitemgroup--set-label-widget"><methodname>gtk.To
           <listitem><simpara>the <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link> at position (x, y)</simpara></listitem>
         </varlistentry>
       </variablelist>
+
       <note>
         <para>This method is available in PyGTK 2.22 and above.</para>
       </note>
 
       <para>Gets the tool item at position (x, y).</para>
+
     </refsect2>
 
   </refsect1>