gtk.ToggleButton
Prev | The gtk Class Reference | Next

## gtk.ToggleButton

gtk.ToggleButton — a button that retains its state

## Synopsis

    class gtk.ToggleButton(gtk.Button):
        gtk.ToggleButton(label=None, use_underline=True)
        def set_mode(draw_indicator)
        def get_mode()
        def set_active(is_active)
        def get_active()
        def toggled()
        def set_inconsistent(setting)
        def get_inconsistent()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.Button
                +-- gtk.ToggleButton

## Implemented Interfaces

`gtk.ToggleButton` implements `gtk.Buildable`

## gtk.ToggleButton Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.Button Properties

"active" | Read-Write | If `True`, the toggle button should be pressed in.
"draw-indicator" | Read-Write | If `True`, the toggle part of the button is displayed.
"inconsistent" | Read-Write | If `True`, the toggle button is in an "in between" state.

## gtk.ToggleButton Style Properties

gtk.Widget Style Properties

gtk.Button Style Properties

## Attributes

"draw_indicator" | Read | If `True`, the toggle part of the button is displayed.

## gtk.ToggleButton Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.Button Signal Prototypes

"toggled" | `def callback(`togglebutton`, `user_param1`, `...`)`

## Description

A `gtk.ToggleButton` is a `gtk.Button` that has two stable states: 'pressed-in' ("on" or "active") and "normal" ("off" or "inactive"). The state changes to the alternate state each time the togglebutton is clicked. The state of a `gtk.ToggleButton` can be set specifically using the `set_active`() method, and retrieved using the `get_active`() method. To simply switch the state of a toggle button, use the `toggled`() method.

## Constructor

        gtk.ToggleButton(label=None, use_underline=True)

`label` : | the text to be displayed by the button label including an underscore to indicate the mnemonic character if desired or `None` if no label is required.
`use_underline` : | if `True`, an underscore in the label 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.
Returns : | a new `gtk.ToggleButton` widget

Creates a new `gtk.ToggleButton` widget with the text label specified by `label`. `label` will be parsed for underscore characters that indicate mnemonic accelerators. If `label` is `None` or not specified, no label will be created.

In PyGTK 2.4 and above the `use_underline` parameter is available and defaults to `True`. If `use_underline` is set to `False` the label text will not be parsed for mnemonic characters.

## Methods

### gtk.ToggleButton.set_mode

        def set_mode(draw_indicator)

`draw_indicator` : | if `True` display the button as an indicator with a label; if `False` just display as a normal button

The `set_mode`() method sets the "draw-indicator" property to the value of`draw_indicator`. If `draw_indicator` is `True` the button is displayed as an indicator with a label; otherwise, the button is displayed as a normal button.

This method only affects subclasses of `gtk.ToggleButton` like `gtk.CheckButton` and `gtk.RadioButton`.

### gtk.ToggleButton.get_mode

        def get_mode()

Returns : | `True` if the button is displayed as an indicator with a label; `False` if displayed as a normal button.

The `get_mode`() method returns the value of the "draw-indicator" property. If "draw-indicator" is `True` the button is displayed as an indicator with a label; if `False`, the button is displayed as a normal button. See the `set_mode`() method.

### gtk.ToggleButton.set_active

        def set_active(is_active)

`is_active` : | if `True` the togglebutton state is active ("on")

The `set_active`() method sets the "active" property to the value of `is_active`. If `is_active` is `True` the `gtk.ToggleButton` is 'pressed in', and if `False` it's 'normal'. This method causes the "toggled" signal to be emitted.

### gtk.ToggleButton.get_active

        def get_active()

Returns : | True if the togglebutton is active

The `get_active`() method returns the value of the "active" property. If "active" is `True` the togglebutton is 'pressed in'; if `False`, it's 'normal'.

### gtk.ToggleButton.toggled

        def toggled()

The `toggled`() method emits the "toggled" signal on the togglebutton.

### gtk.ToggleButton.set_inconsistent

        def set_inconsistent(setting)

`setting` : | if `True` the state is inconsistent

The `set_inconsistent`() method sets the "inconsistent" property to the value of `setting`. If `setting` is `True` the togglebutton is displayed in the inconsistent state - an "in between" state. This method is useful if the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a toggle button, and the current values in that range are inconsistent and you want to indicate that by setting the toggle button to an "in between" display. Normally you would turn off the inconsistent state again if the user clicks the toggle button.

### gtk.ToggleButton.get_inconsistent

        def get_inconsistent()

Returns : | `True` if the state is inconsistent

The `get_inconsistent`() method returns the value of the "inconsistent" property. If "inconsistent" is `True` the togglebutton is displayed in an 'in between' state. See the `set_inconsistent`() method for more details.

## Signals

### The "toggled" gtk.ToggleButton Signal

        def callback(togglebutton, user_param1, ...)

`togglebutton` : | the togglebutton that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "toggled" signal is emitted when the togglebutton state changes either programmatically or by user action.

Prev | Up | Next
gtk.ToggleAction | Home | gtk.ToggleToolButton