path: root/docs/reference/pygtk-gtkbutton.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-gtkbutton">
  <refnamediv>
    <refname>gtk.Button</refname>
    <refpurpose>A pushbutton widget that issues a signal when
clicked.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Button</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkbin">gtk.Bin</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkbutton">gtk.Button</link></methodname>
        <methodparam><parameter role="keyword">label</parameter><initializer>None</initializer></methodparam>
        <methodparam><parameter role="keyword">stock</parameter><initializer>None</initializer></methodparam>
        <methodparam><parameter role="keyword">use_underline</parameter><initializer>True</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--pressed">pressed</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--released">released</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--clicked">clicked</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
      <methodname><link linkend="method-gtkbutton--enter">enter</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--leave">leave</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-relief">set_relief</link></methodname>
        <methodparam><parameter role="keyword">newstyle</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-relief">get_relief</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-label">set_label</link></methodname>
        <methodparam><parameter role="keyword">label</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-label">get_label</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-use-underline">set_use_underline</link></methodname>
        <methodparam><parameter role="keyword">use_underline</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-use-underline">get_use_underline</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-use-stock">set_use_stock</link></methodname>
        <methodparam><parameter role="keyword">use_stock</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-use-stock">get_use_stock</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-focus-on-click">set_focus_on_click</link></methodname>
        <methodparam><parameter role="keyword">focus_on_click</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-focus-on-click">get_focus_on_click</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-alignment">set_alignment</link></methodname>
        <methodparam><parameter role="keyword">xalign</parameter></methodparam>
        <methodparam><parameter role="keyword">yalign</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-alignment">get_alignment</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-image">set_image</link></methodname>
        <methodparam><parameter role="keyword">image</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-image">get_image</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--set-image-position">set_image_position</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-image-position">get_image_position</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbutton--get-event-window">get_event_window</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-gtkbutton">gtk.Button</link>
</synopsis>

  </refsect1>

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

  <refsect1 id="properties-gtkbutton">
    <title>gtk.Button 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="3.5in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"focus-on-click"</entry>
	      <entry>Read/Write</entry>
	      <entry>If <literal>True</literal> the button grabs focus when
	      it is clicked with the mouse. Default value:
<literal>True</literal>. This property is available in GTK+ 2.4 and
above.</entry>
	  </row>

	    <row valign="top">
	      <entry>"image"</entry>
	      <entry>Read/Write</entry>
          <entry>The child widget to appear next to the button text. Default
value: <literal>None</literal>.
This property is available in GTK+ 2.6 and above.</entry>
	  </row>

	    <row valign="top">
	      <entry>"image-position"</entry>
	      <entry>Read/Write</entry>
          <entry>The position of the image relative to the text inside the
          button. One of the <xref linkend="gtk-position-type-constants"
          endterm="gtk-position-type-constants-title"></xref>. Default
          value: <literal>gtk.POS_LEFT</literal>.  This property is
          available in GTK+ 2.10 and above.</entry>
	  </row>

	    <row valign="top">
	      <entry>"label"</entry>
	      <entry>Read/Write</entry>
	<entry>Text of the label widget inside the button, if the button
contains a label widget. Default value: <literal>None</literal>.</entry>
	  </row>

	<row valign="top">
	  <entry>"relief"</entry>
	  <entry>Read/Write</entry>
	  <entry>The border relief style. One of:
<literal>gtk.RELIEF_NORMAL</literal>, <literal>gtk.RELIEF_HALF</literal> or
<literal>gtk.RELIEF_NONE</literal>. Default value:
<literal>gtk.RELIEF_NORMAL</literal>.</entry>
	</row>

	<row valign="top">
	  <entry>"use-stock"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal>, the label text is used to pick
a stock item instead of being displayed.
Default value: <literal>False</literal>.</entry>
	</row>

	<row valign="top">
	  <entry>"use-underline"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal>, an underscore in the text
indicates the next character should be underlined and used for the mnemonic
accelerator key if it is the first character so marked.
Default value: <literal>False</literal>.</entry>
	</row>

	<row valign="top">
	  <entry>"xalign"</entry>
	  <entry>Read/Write</entry>
	  <entry>If the
	  child of the button is a <link
	  linkend="class-gtkmisc"><classname>gtk.Misc</classname></link> or
	  <link
	  linkend="class-gtkalignment"><classname>gtk.Alignment</classname></link>,
	  this property can be used to control it's horizontal
	  alignment. The value ranges from 0.0 to 1.0 representing the fraction
 of freespace to the left of the widget. Default value: 0.5.
This property is available in GTK+ 2.4 and above.</entry>
	</row>

	<row valign="top">
	  <entry>"yalign"</entry>
	  <entry>Read/Write</entry>
	  <entry>If the
	  child of the button is a <link
	  linkend="class-gtkmisc"><classname>gtk.Misc</classname></link> or
	  <link
	  linkend="class-gtkalignment"><classname>gtk.Alignment</classname></link>,
	  this property can be used to control it's vertical
	  alignment. The value ranges from 0.0 to 1.0 representing the fraction
of freespace above the widget.  Default value: 0.5.
This property is available in GTK+ 2.4 and above.</entry>
	</row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkbutton">
    <title>gtk.Button 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>"child-displacement-x"</entry>
	  <entry>Read</entry>
	  <entry>The number of pixels in the x direction to move the child
when the button is depressed. Default value: 0</entry>
	</row>

	    <row valign="top">
	      <entry>"child-displacement-y"</entry>
	      <entry>Read</entry>
	<entry>The number of pixels in the y direction to move the child
when the button is depressed. Default value: 0</entry>
	  </row>

	<row valign="top">
	  <entry>"default-border"</entry>
	  <entry>Read</entry>
	  <entry>The extra space to add for
	  <literal>gtk.CAN_DEFAULT</literal> buttons as a <link
	  linkend="class-gtkborder"><classname>gtk.Border</classname></link></entry>
	</row>

	<row valign="top">
	  <entry>"default-outside-border"</entry>
	  <entry>Read</entry>
	  <entry>The extra space to add for
	  <literal>gtk.CAN_DEFAULT</literal> buttons always drawn outside
	  the border as a <link
	  linkend="class-gtkborder"><classname>gtk.Border</classname></link></entry>
	</row>

	<row valign="top">
	  <entry>"displace-focus"</entry>
	  <entry>Read</entry>
	  <entry>If <literal>True</literal> the "child-displacement-x" and
	  "child-displacement-y" properties should also affect the focus
	  rectangle. Default value: <literal>False</literal>. This property
	  is available in GTK+ 2.6 and above.</entry>
	</row>

	<row valign="top">
	  <entry>"image-spacing"</entry>
	  <entry>Read</entry>
	  <entry>Spacing in pixels between the image and the label. Allowed values: &#62;=0. Default value: 2.</entry>
	</row>

	<row valign="top">
	  <entry>"inner-border"</entry>
	  <entry>Read</entry>
	  <entry>The border between the button edges and child as a <link
	  linkend="class-gtkborder"><classname>gtk.Border</classname></link>.
	  This property is available in GTK+ 2.10 and above.</entry>
	</row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkbutton">
    <title>gtk.Button 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-gtkbutton--activate">activate</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkbutton--clicked">clicked</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkbutton--enter">enter</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkbutton--leave">leave</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkbutton--pressed">pressed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkbutton--released">released</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>button</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkbutton"><classname>gtk.Button</classname></link> widget is
usually displayed as a pushbutton with a text label (<link
linkend="class-gtklabel"><classname>gtk.Label</classname></link>) though it
can contain any valid widget. The <link
linkend="class-gtkbutton"><classname>gtk.Button</classname></link> is
generally used to attach a callback function or method that is called when
the button is clicked. Buttons generate signals that indicate:</para>

    <itemizedlist>
      <listitem>
	<simpara>"clicked" - the user pressed and released a mouse button
over the button</simpara>
      </listitem>
      <listitem>
	<simpara>"pressed" - the user pressed a mouse button over the
button</simpara>
      </listitem>
      <listitem>
	<simpara>"released" - the user released a mouse button over the
button</simpara>
      </listitem>
      <listitem>
	<simpara>"enter" - the pointer entered the button</simpara>
      </listitem>
      <listitem>
	<simpara>"leave" - the pointer left the button</simpara>
      </listitem>
    </itemizedlist>

    <para>The "clicked" signal is usually the only signal that an
application needs to handle.</para>

    <para>If a label is being used by the button its text (the "label"
property) is retrieved using the <link
linkend="method-gtkbutton--get-label"><methodname>get_label</methodname>()</link> 
method. The label text is changed using the <link
linkend="method-gtkbutton--set-label"><methodname>set_label</methodname>()</link> 
method.</para>

    <para>The property ("use_underline") that tells a button to use the
first underscore to indicate a mnemonic key is changed using the <link
linkend="method-gtkbutton--set-use-underline"><methodname>set_use_underline</methodname>().</link> 
method. It can be retrieved using the <link
linkend="method-gtkbutton--get-use-underline"><methodname>get_use_underline</methodname>()</link> 
method.</para>

    <para>The button's relief style (the "relief" property) is retrieved
using the method <link
linkend="method-gtkbutton--get-relief"><methodname>get_relief</methodname>()</link>. 
The relief style is set to one of <literal>gtk.RELIEF_NONE</literal>,
<literal>gtk.RELIEF_HALF</literal> or <literal>gtk.RELIEF_NORMAL</literal>
using the method <link
linkend="method-gtkbutton--set-relief"><methodname>set_relief</methodname>()</link>.</para>

  </refsect1>

  <refsect1 id="constructor-gtkbutton">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Button</methodname>
	<methodparam><parameter
		       role="keyword">label</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">stock</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter
		       role="keyword">use_underline</parameter><initializer>True</initializer></methodparam>
      </constructorsynopsis></programlisting>

    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">label</parameter>&nbsp;:</term>
	<listitem><simpara>the text to be displayed by the button label
including an underscore to indicate the mnemonic character if desired or
<literal>None</literal> if no label is required.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">stock</parameter>&nbsp;:</term>
	<listitem><simpara>the stock id identifying the stock image and text
to be used in the button or <literal>None</literal> if no stock id is to be
used.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">use_underline</parameter>&nbsp;:</term>
	<listitem><simpara>if <literal>True</literal>, an underscore in the
text indicates the next character should be underlined and used for the
mnemonic accelerator key if it is the first character so
marked. Available in PyGTK 2.4 and above.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new button object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new button widget with the content depending on the
parameters: <parameter>label</parameter>, <parameter>stock</parameter> and
<parameter>use_underline</parameter>.  The default values for
<parameter>stock</parameter> and <parameter>label</parameter> are
<literal>None</literal> and, in PyGTK 2.4 and above,
<parameter>use_underline</parameter> is available and defaults to
<literal>True</literal>. If both <parameter>label</parameter> and
<parameter>stock</parameter> are specified <parameter>stock</parameter>
takes precedence. If neither is specified the button is created with no
child widget. A child widget can be added later with the <link
linkend="method-gtkcontainer--add"><methodname>add</methodname>()</link>
method.</para>

    <para>If <parameter>stock</parameter> is specified the "use-stock"
property will be set to <literal>True</literal>.</para>

    <para>If <parameter>label</parameter> is specified the "label" property
will be set with the text of the label, the "use_underline" property will be
set to <literal>True</literal> and any characters that are preceded by an
underscore are underlined (use two underscores to insert an underscore in a
label). The first underscored character will become the mnemonic character
used as the keyboard accelerator for the button when pressed simultaneously
with the <keycap>Alt</keycap> key. In PyGTK 2.4 and above the
"use-underline" property can be set by using the optional
<parameter>use_underline</parameter> parameter.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkbutton--pressed">
      <title>gtk.Button.pressed</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>pressed</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.22 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--button-press-event">button-press-event</link>"
        signal.</para>
      </warning>

      <para>The <methodname>pressed</methodname>() method emits the
"pressed" signal to the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--released">
      <title>gtk.Button.released</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>released</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.22 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--button-release-event">button-release-event</link>"
        signal.</para>
      </warning>

      <para>The <methodname>released</methodname>() method emits the
"released" signal to the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--clicked">
      <title>gtk.Button.clicked</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>clicked</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>clicked</methodname>() method emits the
"clicked" signal to the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--enter">
      <title>gtk.Button.enter</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>enter</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.22 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--enter-notify-event">enter-notify-event</link>"
        signal.</para>
      </warning>

      <para>The <methodname>enter</methodname>() method emits the "enter"
signal to the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--leave">
      <title>gtk.Button.leave</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>leave</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.22 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--leave-notify-event">leave-notify-event</link>"
        signal.</para>
      </warning>

      <para>The <methodname>leave</methodname>() method emits the "leave"
signal to the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-relief">
      <title>gtk.Button.set_relief</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_relief</methodname>
	  <methodparam><parameter>newstyle</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">newstyle</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>one of <literal>gtk.RELIEF_NONE</literal>,
<literal>gtk.RELIEF_NORMAL</literal> or
<literal>gtk.RELIEF_HALF</literal></simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_relief</methodname>() method sets the relief
style of the edges of the button. Three styles exist,
<literal>gtk.RELIEF_NORMAL</literal>, <literal>gtk.RELIEF_HALF</literal>,
<literal>gtk.RELIEF_NONE</literal>. The default style is, as one can guess,
<literal>gtk.RELIEF_NORMAL</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-relief">
      <title>gtk.Button.get_relief</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_relief</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the relief style</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_relief</methodname>() method retrieves the
current relief style (the "relief" property) set for the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-label">
      <title>gtk.Button.set_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_label</methodname>
	  <methodparam><parameter>label</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">label</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>a string to be set as the text in the button
label</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_label</methodname>() method sets the text of
the button label to <parameter>label</parameter> (also sets the "label"
property). This string is also used to select the stock item if the
"use_stock" property is <literal>True</literal> and the string references a
stock item. Any previously set labels will be cleared.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-label">
      <title>gtk.Button.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 text of the label
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_label</methodname>() method retrieves the
text from the label of the button, as set by <link
linkend="method-gtkbutton--set-label"><methodname>set_label</methodname>()</link> 
or by the <link
linkend="constructor-gtkbutton"><methodname>gtk.Button</methodname>()</link>
constructor. This string is owned by the widget and must not be modified or
freed.  If the label text has not been set the return value  will be
<literal>None</literal>. This will be the case if you create an empty button
with <link
linkend="constructor-gtkbutton"><methodname>gtk.Button</methodname>()</link>
to use as a container.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-use-underline">
      <title>gtk.Button.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>use_underline</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara><literal>True</literal> if underscores in the text
indicate mnemonics</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <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
underscore in the text of the button label indicates that the next character
should be underlined and used for the mnemonic accelerator key if it is also
the first underlined character.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-use-underline">
      <title>gtk.Button.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 an underscore in the button
label indicates the mnemonic accelerator keys.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_use_underline</methodname>() method returns
whether the "use_underline" property is <literal>True</literal> meaning that
an underscore in the button label indicates a mnemonic. See <link
linkend="method-gtkbutton--set-use-underline"><methodname>set_use_underline</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-use-stock">
      <title>gtk.Button.set_use_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_stock</methodname>
	  <methodparam><parameter
			 role="keyword">use_stock</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>use_stock</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>If <literal>True</literal> the button should use a
stock item</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_use_stock</methodname>() method sets the
"use_stock" property to the value of <parameter>use_stock</parameter>. If
<parameter>use_stock</parameter> is <literal>True</literal>, the label set
on the button is used as a stock id to select the stock item for the
button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-use-stock">
      <title>gtk.Button.get_use_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_use_stock</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem>
	    <simpara>the value of the "use_stock" property.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_use_stock</methodname>() method returns the
value of the "use_stock" property. If <literal>True</literal> the button
label is used to select a stock item instead of being used directly as the
label text.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-focus-on-click">
      <title>gtk.Button.set_focus_on_click</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_focus_on_click</methodname>
	  <methodparam><parameter
			 role="keyword">focus_on_click</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>focus_on_click</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>If <literal>True</literal> the button grabs focus when
	    clicked with the mouse.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_focus_on_click</methodname>() method sets
the "focus-on-click" property to the value of
<parameter>focus_on_click</parameter>. If
<parameter>focus_on_click</parameter> is <literal>True</literal>, the button
grabs focus when it is clicked by the mouse.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-focus-on-click">
      <title>gtk.Button.get_focus_on_click</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_focus_on_click</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem>
	    <simpara>the value of the "focus-on-click" property.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_focus_on_click</methodname>() method returns
the value of the "focus-on-click" property. If <literal>True</literal> the
button grabs focus when it is clicked by the mouse .</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-alignment">
      <title>gtk.Button.set_alignment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_alignment</methodname>
	  <methodparam><parameter
			 role="keyword">xalign</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">yalign</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>xalign</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>the horizontal alignment of the child widget. The value
	    ranges from 0.0 to 1.0 and represents the fraction of freespace
	    to the left of the child widget.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>yalign</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>the vertical alignment of the child widget. The value
	    ranges from 0.0 to 1.0 and represents the fraction of freespace
	    above the child widget.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_alignment</methodname>() method sets the
"xalign" and "yalign" properties to the value of
<parameter>xalign</parameter> and <parameter>yalign</parameter>
respectively. This property has no effect unless the child is a <link
linkend="class-gtkmisc"><classname>gtk.Misc</classname></link> or a <link
linkend="class-gtkalignment"><classname>gtk.Alignment</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-alignment">
      <title>gtk.Button.get_alignment</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_alignment</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem>
	    <simpara>a 2-tuple containing the values of the "xalign" and
	    "yalign" properties.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_alignment</methodname>() method returns the
values of the "xalign" and "yalign" properties. See the <link linkend="method-gtkbutton--set-alignment"><methodname>set_alignment</methodname>()</link> method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--set-image">
      <title>gtk.Button.set_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_image</methodname>
	  <methodparam><parameter
			 role="keyword">image</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter>image</parameter>&nbsp;:</term>
	  <listitem>
	    <simpara>the widget to set as the image for the button.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_image</methodname>() method sets the "image"
property to the value of <parameter>image</parameter>. This property has no
effect unless the "gtk-button-images" property is
<literal>True</literal>. See the <link
linkend="class-gtksettings"><classname>gtk.Settings</classname></link>
reference for more information. Note you do not have to call the <link
linkend="method-gtkwidget--show"><methodname>gtk.Widget.show</methodname>()</link>
method for <parameter>image</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-image">
      <title>gtk.Button.get_image</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_image</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem>
	    <simpara>the <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> used as
the button image or <literal>None</literal> if there is no image.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_image</methodname>() method returns the
value of the "image" property. See the <link
linkend="method-gtkbutton--set-image"><methodname>set_image</methodname>()</link>
method for more information.</para>

    </refsect2>

   <refsect2 id="method-gtkbutton--set-image-position">
      <title>gtk.Button.set_image_position</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_image_position</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>the position of the image relative to the text inside the button.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>set_image_position</methodname>() method sets the
      position of the image relative to the text inside the button. The value of
      <parameter>position</parameter> can be one of the <xref linkend="gtk-position-type-constants"
      endterm="gtk-position-type-constants-title"></xref>.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-image-position">
      <title>gtk.Button.get_image_position</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_image_position</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the position of the image relative to the text inside the button.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_image_position</methodname>() method returns the
      position of the image relative to the text inside the button.</para>

    </refsect2>

    <refsect2 id="method-gtkbutton--get-event-window">
      <title>gtk.Button.get_event_window</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_event_window</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the button's event window if it is realized, <literal>None</literal> otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_event_window</methodname>() method returns the
      the button's event window if it is realized, <literal>None</literal> otherwise.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkbutton--activate">
      <title>The "activate" gtk.Button Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>button</parameter>&nbsp;:</term>
	  <listitem><simpara>the button that received the "activate"
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 "activate" signal is emitted when the <link
linkend="method-gtkwidget--activate"><methodname>gtk.Widget.activate</methodname>()</link> 
method is called. For a button it causes the "clicked" signal to be
emitted.</para>

    </refsect2>

    <refsect2 id="signal-gtkbutton--clicked">
      <title>The "clicked" gtk.Button Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>button</parameter>&nbsp;:</term>
	  <listitem><simpara>the button 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 mouse button is pressed
and released while the pointer is over the button or when the button is triggered
with the keyboard.</para>

    </refsect2>

    <refsect2 id="signal-gtkbutton--enter">
      <title>The "enter" gtk.Button Signal</title>

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

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

      <warning>
        <para>This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--enter-notify-event">enter-notify-event</link>"
        signal.</para>
      </warning>

      <para>The "enter" signal is emitted when the pointer enters the
button.</para>

    </refsect2>

    <refsect2 id="signal-gtkbutton--leave">
      <title>The "leave" gtk.Button Signal</title>

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

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

      <warning>
        <para>This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--leave-notify-event">leave-notify-event</link>"
        signal.</para>
      </warning>

      <para>The "leave" signal is emitted when the pointer leaves the
button.</para>

    </refsect2>

    <refsect2 id="signal-gtkbutton--pressed">
      <title>The "pressed" gtk.Button Signal</title>

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

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

      <warning>
        <para>This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--button-press-event">button-press-event</link>"
        signal.</para>
      </warning>

      <para>The "pressed" signal is emitted when the mouse button is pressed
while the pointer is over the button.</para>

    </refsect2>

    <refsect2 id="signal-gtkbutton--released">
      <title>The "released" gtk.Button Signal</title>

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

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

      <warning>
        <para>This signal is deprecated since GTK+ 2.8 and should not be used in newly-written code.
        Use the "<link linkend="signal-gtkwidget--button-release-event">button-release-event</link>"
        signal.</para>
      </warning>

      <para>The "released" signal is emitted when the button is released no
matter where the pointer is.</para>

    </refsect2>

  </refsect1>

</refentry>