button_widgets.txt

Button Widgets
==============

Button
------

The Button widget is another commonly used widget. It is generally used to
attach a function that is called when the button is pressed.

The :class:`Gtk.Button` widget can hold any valid child widget. That is it can
hold most any other standard :class:`Gtk.Widget`. The most commonly used child
is the :class:`Gtk.Label`.

Usually, you want to connect to the button's "clicked" signal which is emitted
when the button has been pressed and released.

Example
^^^^^^^

.. image:: ../images/button_example.png

.. literalinclude:: ../examples/button_example.py
    :linenos:

ToggleButton
------------

A :class:`Gtk.ToggleButton` is very similar to a normal :class:`Gtk.Button`,
but when clicked they remain activated, or pressed, until clicked again.
When the state of the button is changed, the "toggled" signal is emitted.

To retrieve the state of the :class:`Gtk.ToggleButton`, you can use the
:meth:`Gtk.ToggleButton.get_active` method. This returns ``True`` if the button
is "down". You can also set the toggle button's state, with
:meth:`Gtk.ToggleButton.set_active`. Note that, if you do this, and the state
actually changes, it causes the "toggled" signal to be emitted.

Example
^^^^^^^

.. image:: ../images/togglebutton_example.png

.. literalinclude:: ../examples/togglebutton_example.py
    :linenos:

CheckButton
-----------
:class:`Gtk.CheckButton` inherits from :class:`Gtk.ToggleButton`. The only real
difference between the two is :class:`Gtk.CheckButton`'s appearance.
A :class:`Gtk.CheckButton` places a discrete :class:`Gtk.ToggleButton` next to
a widget, (usually a :class:`Gtk.Label`).
The "toggled" signal, :meth:`Gtk.ToggleButton.set_active` and
:meth:`Gtk.ToggleButton.get_active` are inherited.

RadioButton
-----------
Like checkboxes, radio buttons also inherit from :class:`Gtk.ToggleButton`,
but these work in groups, and only one :class:`Gtk.RadioButton` in a group can
be selected at any one time. Therefore, a :class:`Gtk.RadioButton` is one way
of giving the user a choice from many options.

Radio buttons can be created with one of the static methods
:meth:`Gtk.RadioButton.new_from_widget`,
:meth:`Gtk.RadioButton.new_with_label_from_widget` or
:meth:`Gtk.RadioButton.new_with_mnemonic_from_widget`.
The first radio button in a group will be created passing ``None`` as the
*group* argument. In subsequent calls, the group you
wish to add this button to should be passed as an argument.

When first run, the first radio button in the group will be active.
This can be changed by calling :meth:`Gtk.ToggleButton.set_active` with ``True``
as first argument.

Changing a :class:`Gtk.RadioButton`'s widget group after its creation can be
achieved by calling :meth:`Gtk.RadioButton.join_group`.

Example
^^^^^^^

.. image:: ../images/radiobutton_example.png

.. literalinclude:: ../examples/radiobutton_example.py
    :linenos:

LinkButton
----------
A :class:`Gtk.LinkButton` is a :class:`Gtk.Button` with a hyperlink, similar
to the one used by web browsers, which triggers an action when clicked. It is
useful to show quick links to resources.

The URI bound to a :class:`Gtk.LinkButton` can be set specifically using
:meth:`Gtk.LinkButton.set_uri`, and retrieved using :meth:`Gtk.LinkButton.get_uri`.

Example
^^^^^^^

.. image:: ../images/linkbutton_example.png

.. literalinclude:: ../examples/linkbutton_example.py
    :linenos:

SpinButton
----------
A :class:`Gtk.SpinButton` is an ideal way to allow the user to set the value of
some attribute. Rather than having to directly type a number into a
:class:`Gtk.Entry`, :class:`Gtk.SpinButton` allows the user to click on one of
two arrows to increment or decrement the displayed value. A value can still be
typed in, with the bonus that it can be checked to ensure it is in a given range. 
The main properties of a :class:`Gtk.SpinButton` are set through
:class:`Gtk.Adjustment`.

To change the value that :class:`Gtk.SpinButton` is showing, use
:meth:`Gtk.SpinButton.set_value`. The value entered can either be an integer or
float, depending on your requirements, use :meth:`Gtk.SpinButton.get_value` or
:meth:`Gtk.SpinButton.get_value_as_int`, respectively.

When you allow the displaying of float values in the spin button, you may wish
to adjust the number of decimal spaces displayed by calling
:meth:`Gtk.SpinButton.set_digits`.

By default, :class:`Gtk.SpinButton` accepts textual data. If you wish to limit
this to numerical values only, call :meth:`Gtk.SpinButton.set_numeric` with ``True``
as argument.

We can also adjust the update policy of :class:`Gtk.SpinButton`. There are two
options here; by default the spin button updates the value even if the data
entered is invalid. Alternatively, we can set the policy to only update when the
value entered is valid by calling :meth:`Gtk.SpinButton.set_update_policy`.

Example
^^^^^^^

.. image:: ../images/spinbutton_example.png

.. literalinclude:: ../examples/spinbutton_example.py
    :linenos:

Switch
------
A :class:`Gtk.Switch` is a widget that has two states: on or off. The user can
control which state should be active by clicking the empty area, or by dragging
the handle.

You shouldn't use the "activate" signal on the Gtk.Switch which is an action
signal and emitting it causes the switch to animate. Applications should never
connect to this signal, but use the "notify::active" signal, see the example
here below.

Example
^^^^^^^

.. image:: ../images/switch_example.png

.. literalinclude:: ../examples/switch_example.py
    :linenos: