path: root/docs/reference/pygtk-gtktoolbutton.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-gtktoolbutton">
  <refnamediv>
    <refname>gtk.ToolButton</refname> <refpurpose>a <link
    linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>
    subclass that displays buttons (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.ToolButton</classname></ooclass>
      <ooclass><classname><link linkend="class-gtktoolitem">gtk.ToolItem</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtktoolbutton">gtk.ToolButton</link></methodname>
	<methodparam><parameter role="keyword">icon_widget</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter role="keyword">label</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtktoolbutton2">gtk.ToolButton</link></methodname>
	<methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-label">set_label</link></methodname>
	<methodparam><parameter role="keyword">label</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-label">get_label</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-use-underline">set_use_underline</link></methodname>
	<methodparam><parameter role="keyword">use_underline</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-use-underline">get_use_underline</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-stock-id">set_stock_id</link></methodname>
	<methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-stock-id">get_stock_id</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-icon-name">set_icon_name</link></methodname>
	<methodparam><parameter role="keyword">icon_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-icon-name">get_icon_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-icon-widget">set_icon_widget</link></methodname>
	<methodparam><parameter role="keyword">icon_widget</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-icon-widget">get_icon_widget</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--set-label-widget">set_label_widget</link></methodname>
	<methodparam><parameter role="keyword">label_widget</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktoolbutton--get-label-widget">get_label_widget</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </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-gtktoolitem">gtk.ToolItem</link>
            +-- <link linkend="class-gtktoolbutton">gtk.ToolButton</link>
</synopsis>

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


  <refsect1 id="properties-gtktoolbutton">
    <title>gtk.ToolButton 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-gtktoolitem">gtk.ToolItem 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>"icon-name"</entry>
	      <entry>Read-Write</entry>
	      <entry>The themed icon name to display in the item. This
property only has an effect if not overridden by "label", "icon-widget" or
"stock-id" properties. Default value: <literal>None</literal>.
Available in GTK+ 2.8 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"icon-widget"</entry>
	      <entry>Read-Write</entry>
	      <entry>The icon widget to display in the item.
Default value: <literal>None</literal>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"label"</entry>
	      <entry>Read-Write</entry>
	      <entry>The text to show in the item.
Default value: <literal>None</literal>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"label-widget"</entry>
	      <entry>Read-Write</entry>
	      <entry>The widget to use as the item label instead of
"label". Default value: <literal>None</literal>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"stock-id"</entry>
	      <entry>Read-Write</entry>
	      <entry>The stock icon displayed on the item if "label" and
"label-widget" are <literal>None</literal>.
Default value: <literal>None</literal>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"use-underline"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, an underline in the "label"
property indicates that the next character should be used for the mnemonic
accelerator key in the overflow menu.
Default value: <literal>False</literal>.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtktoolbutton">
    <title>gtk.ToolButton 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>"icon-spacing"</entry>
              <entry>Read-Write</entry>
              <entry>Spacing in pixels between the icon and label</entry>
            </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtktoolbutton">
    <title>gtk.ToolButton 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-gtktoolitem">gtk.ToolItem Signal Prototypes</link></para>

  </refsect1>

  <refsect1>
    <title>Signal Prototypes</title>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtktoolbutton--clicked">clicked</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>toolbutton</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.4 and above.</para>
    </note>

    <para>A <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
is a sub class of <link
linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link> that
contains a button. Use the <link
linkend="constructor-gtktoolbutton">gtk.ToolButton</link>() constructor to
create a new <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
specifying a widget to use as the icon and a label for the
text. Alternatively use the other <link
linkend="constructor-gtktoolbutton2">gtk.ToolButton</link>() constructor to
create a <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
from a stock item.</para>

    <para>The label of a <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
is determined by the properties "label_widget", "label", and "stock_id". If
"label_widget" specifies a <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>, that
widget is used as the label. If "label-widget" is <literal>None</literal>,
then the string in "label" is used as the label. If both "label-widget" and
"label" are <literal>None</literal>, the label is determined by the stock
item specified by "stock-id". Finally, if "label-widget", "label" and
"stock-id" are all <literal>None</literal>, the button does not have a
label.</para>

    <para>The icon of a <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
is determined by the properties "icon-widget" and "stock-id". If
"icon-widget" specifies a <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>, that
widget is used as the icon. If "icon-widget" is <literal>None</literal>, the
icon is determined by the stock item specified by "stock-id". If both
"icon-widget" and "stock-id" are <literal>None</literal>, the button does
not have an icon.</para>

  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-gtktoolbutton">
      <title>gtk.ToolButton</title>

      <programlisting><constructorsynopsis language="python">
	  <methodname>gtk.ToolButton</methodname>
	  <methodparam><parameter role="keyword">icon_widget</parameter><initializer>None</initializer></methodparam>
	  <methodparam><parameter role="keyword">label</parameter><initializer>None</initializer></methodparam>
	</constructorsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">icon_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
	  that will be used as the icon widget, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">label</parameter>&nbsp;:</term>
	  <listitem><simpara>a string that will be used as the label, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A new <link
	  linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>Creates a new <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
optionally using the icon specified by <parameter>icon_widget</parameter>
and the label text specified by <parameter>label</parameter>. If both
<parameter>icon_widget</parameter> and <parameter>label</parameter> are
<literal>None</literal>, the tool button will be empty.</para>

      </refsect2>

    <refsect2 id="constructor-gtktoolbutton2">
      <title>gtk.ToolButton</title>

      <programlisting><constructorsynopsis language="python">
	  <methodname>gtk.ToolButton</methodname>
	  <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
	</constructorsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a string that specifies a stock
	  item</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A new <link
	  linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>Creates a new <link
linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
using the stock item specified by <parameter>stock_id</parameter> to
determine the icon and label text. It is an error if
<parameter>stock_id</parameter> is not a name of a stock item.</para>

      </refsect2>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtktoolbutton--set-label">
      <title>gtk.ToolButton.set_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_label</methodname>
	  <methodparam><parameter role="keyword">label</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">label</parameter>&nbsp;:</term>
	  <listitem><simpara>a string that will be used as label, or
      <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_label</methodname>() method sets the "label"
property to the value of <parameter>label</parameter>. If the "label_widget"
property is <literal>None</literal>, label will be used as the label of the
tool button.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-label">
      <title>gtk.ToolButton.get_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_label</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The label, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_label</methodname>() method returns the
value of the "label" property that is used as the label of the tool button
if the "label-widget" property is <literal>None</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--set-use-underline">
      <title>gtk.ToolButton.set_use_underline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_underline</methodname>
	  <methodparam><parameter role="keyword">use_underline</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">use_underline</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal>, an underline in the
	  label string specifies a mnemonic key for the overflow
	  menu</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_use_underline</methodname>() method sets the
"use-underline" property to the value of
<parameter>use_underline</parameter>. If
<parameter>use_underline</parameter> is <literal>True</literal>, an
underline in the "label" property indicates that the next character should
be used for the mnemonic accelerator key in the overflow menu. For example,
if the label property is "_Open" and <parameter>use_underline</parameter> is
<literal>True</literal>, the label on the tool button will be "Open" and the
item on the overflow menu will have an underlined 'O'. Labels shown on tool
buttons never have mnemonics on them; this property only affects the menu
item on the overflow menu.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-use-underline">
      <title>gtk.ToolButton.get_use_underline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_use_underline</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if underscores in the
	  "label" property are used as mnemonics on menu items on the
	  overflow menu.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_use_underline</methodname>() method returns
the value of the "use-underline" property. If "use-underline" is
<literal>True</literal>, underscores in the label property are used as
mnemonics on menu items on the overflow menu. See the <link
linkend="method-gtktoolbutton--set-use-underline"><methodname>set_use_underline()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--set-stock-id">
      <title>gtk.ToolButton.set_stock_id</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_stock_id</methodname>
	  <methodparam><parameter role="keyword">stock_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a name of a stock item, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_stock_id</methodname>() method sets the
"stock-id" property to the value of <parameter>stock_id</parameter>. The
stock item specified by <parameter>stock_id</parameter> is used to determine
the icon and label if not overridden by the "label" and "icon-widget"
properties. See the <link
linkend="constructor-gtktoolbutton2">gtk.ToolButton</link>() constructor for
more information.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-stock-id">
      <title>gtk.ToolButton.get_stock_id</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_stock_id</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of the stock item.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_stock_id</methodname>() method returns the
value of the "stock-id" property that contains the name of a stock item or
<literal>None</literal>. See the <link
linkend="constructor-gtktoolbutton2">gtk.ToolButton</link>() constructor for
more information.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--set-icon-name">
      <title>gtk.ToolButton.set_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_name</methodname>
	  <methodparam><parameter role="keyword">icon_name</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>a name of a themed icon, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_icon_name</methodname>() method sets the
"icon-name" property to the value of <parameter>icon_name</parameter>. The
themed icon name specified by <parameter>icon_name</parameter> is used to
determine the icon for the toolbutton if not overridden by the "label",
"stock-id" and "icon-widget" properties. See the <link
linkend="constructor-gtktoolbutton2">gtk.ToolButton</link>() constructor for
more information.</para>

<para>In PyGTK 2.10 and above, <parameter>icon_name</parameter> may be
<literal>None</literal> to unset the icon name.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-icon-name">
      <title>gtk.ToolButton.get_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_name</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of the stock item.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_icon_name</methodname>() method returns the
value of the "icon_name" property that contains the name of a themed icon or
<literal>None</literal>. See the <link
linkend="constructor-gtktoolbutton2">gtk.ToolButton</link>() constructor for
more information.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--set-icon-widget">
      <title>gtk.ToolButton.set_icon_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_widget</methodname>
	  <methodparam><parameter role="keyword">icon_widget</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">icon_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget used as icon, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_icon_widget</methodname>() method sets the
"icon-widget" property to the value of
<parameter>icon_widget</parameter>. If <parameter>icon_widget</parameter>
specifies a <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>, it is
used as the icon of the tool button. If <parameter>icon_widget</parameter>
is <literal>None</literal> the icon is determined by the "stock_id"
property. If the "stock_id" property is also <literal>None</literal>, the
tool button will not have an icon.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-icon-widget">
      <title>gtk.ToolButton.get_icon_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_icon_widget</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The widget used as icon on
	  <parameter>button</parameter>, or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_icon_widget</methodname>() method returns
the value of the "icon-widget" property that contains the <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> used as
the icon on the tool button. See the <link
linkend="method-gtktoolbutton--set-icon-widget"><methodname>set_icon_widget()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--set-label-widget">
      <title>gtk.ToolButton.set_label_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_label_widget</methodname>
	  <methodparam><parameter role="keyword">label_widget</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">label_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget used as the label, or
	  <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_label_widget</methodname>() method sets the
"label-widget" property to the <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> specified
by <parameter>label_widget</parameter> that will be used as the label for
the tool button. If <parameter>label_widget</parameter> is
<literal>None</literal> the "label" property is used as label. If
"label-widget" and "label" are both <literal>None</literal>, the label in
the stock item determined by the "stock_id" property is used as the
label. If "label-widget", "label" and "stock_id" are all
<literal>None</literal>, the tool button will not have a label.</para>

    </refsect2>

    <refsect2 id="method-gtktoolbutton--get-label-widget">
      <title>gtk.ToolButton.get_label_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_label_widget</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The widget used as label on
	  <parameter>button</parameter>, or
	  <literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_label_widget</methodname>() method returns
the value of the "label-widget" property that is used as the label on the
tool button. See the <link
linkend="method-gtktoolbutton--set-label-widget"><methodname>gtk.ToolButton.set_label_widget()</methodname></link>
method for more information.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtktoolbutton--clicked">
      <title>The "clicked" gtk.ToolButton Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>toolbutton</parameter>&nbsp;:</term>
	  <listitem><simpara>the toolbutton 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 "clicked" signal is emitted when the tool button is clicked
with the mouse or activated with the keyboard.</para>

    </refsect2>

  </refsect1>

</refentry>