Gtk.ToggleButton

Gtk.ToggleButton — Create buttons which retain their state

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.Button
                        ╰── Gtk.ToggleButton
                            ├── Gtk.CheckButton
                            ╰── Gtk.MenuButton

See also:

Gtk.Button, Gtk.CheckButton, Gtk.CheckMenuItem

Functions:

• new () -> Gtk.Widget
• new_with_label (label:str) -> Gtk.Widget
• new_with_mnemonic (label:str) -> Gtk.Widget
• set_mode (self, draw_indicator:bool)
• get_mode (self) -> bool
• toggled (self)
• get_active (self) -> bool
• set_active (self, is_active:bool)
• get_inconsistent (self) -> bool
• set_inconsistent (self, setting:bool)

Description:

A Gtk.ToggleButton is a GtkButton which will remain pressed-in when clicked. Clicking again will cause the toggle button to return to its normal state.

A toggle button is created by calling either Gtk.ToggleButton::new() or Gtk.ToggleButton::new_with_label(). If using the former, it is advisable to pack a widget, (such as a Gtk.Label and/or a GtkImage), into the toggle button’s container. (See Gtk.Button for more information).

The state of a Gtk.ToggleButton can be set specifically using Gtk.ToggleButton::set_active(), and retrieved using Gtk.ToggleButton::get_active().

To simply switch the state of a toggle button, use Gtk.ToggleButton::toggled().

Creating two Gtk.ToggleButton widgets.

    def add_toggle_buttons(self, grid):
        togglebutton1 = Gtk.ToggleButton("ToggleButton 1")
        togglebutton1.connect("toggled", self.on_toggle_button_toggled)
        grid.attach(togglebutton1, 0, 0, 1, 1)

        togglebutton2 = Gtk.ToggleButton("ToggleButton 2")
        togglebutton2.connect("toggled", self.on_toggle_button_toggled)
        grid.attach(togglebutton2, 0, 1, 1, 1)

    def on_toggle_button_toggled(self, togglebutton):
        if togglebutton.get_active():
            print("%s has been toggled on" % (togglebutton.get_label()))
        else:
            print("%s has been toggled off" % (togglebutton.get_label()))

Function Details:

new()

new () -> Gtk.Widget

Creates a new toggle button. A widget should be packed into the button, as in `Gtk.Button:new()`.

• Returns: a new toggle button.

new_with_label()

new_with_label (label:str) -> Gtk.Widget

Creates a new toggle button with a text label.

• Returns: a new toggle button.

new_with_mnemonic()

new_with_mnemonic (label:str) -> Gtk.Widget

Creates a new Gtk.ToggleButton containing a label. The labelwill be created using `Gtk.Label:new_with_mnemonic(), so underscoresinlabel` indicate the mnemonic for the button.

• Returns: a new Gtk.ToggleButton

set_mode()

set_mode (self, draw_indicator:bool)

Sets whether the button is displayed as a separate indicator and label.You can call this function on a checkbutton or a radiobutton withdraw_indicator = FALSE to make the button look like a normal button This function only affects instances of classes like Gtk.CheckButtonand Gtk.RadioButton that derive from Gtk.ToggleButton,not instances of Gtk.ToggleButton itself.

get_mode()

get_mode (self) -> bool

Retrieves whether the button is displayed as a separate indicatorand label. See Gtk.ToggleButton:set_mode().

• Returns: True if the togglebutton is drawn as a separate indicatorand label.

toggled()

toggled (self)

Emits the “toggled” signal on theGtk.ToggleButton. There is no good reason for anapplication ever to call this function.

get_active()

get_active (self) -> bool

Queries a Gtk.ToggleButton and returns its current state. Returns True ifthe toggle button is pressed in and FALSE if it is raised.

• Returns: a gboolean value.

set_active()

set_active (self, is_active:bool)

Sets the status of the toggle button. Set to True if you want theGtk.ToggleButton to be “pressed in”, and FALSE to raise it.This action causes the “toggled” signal and the“clicked” signal to be emitted.

get_inconsistent()

get_inconsistent (self) -> bool

Gets the value set by Gtk.ToggleButton:set_inconsistent().

• Returns: True if the button is displayed as inconsistent, FALSE otherwise

set_inconsistent()

set_inconsistent (self, setting:bool)

If the user has selected a range of elements (such as some text orspreadsheet cells) that are affected by a toggle button, and thecurrent values in that range are inconsistent, you may want todisplay the toggle in an “in between” state. This function turns on“in between” display. Normally you would turn off the inconsistentstate again if the user toggles the toggle button. This has to bedone manually, Gtk.ToggleButton:set_inconsistent() only affectsvisual appearance, it doesn’t affect the semantics of the button.

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class ToggleButton(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("ToggleButton")
        self.connect("destroy", Gtk.main_quit)

        grid = Gtk.Grid()
        self.add(grid)

        togglebutton1 = Gtk.ToggleButton("ToggleButton 1")
        togglebutton1.connect("toggled", self.on_toggle_button_toggled)
        grid.attach(togglebutton1, 0, 0, 1, 1)

        togglebutton2 = Gtk.ToggleButton("ToggleButton 2")
        togglebutton2.connect("toggled", self.on_toggle_button_toggled)
        grid.attach(togglebutton2, 0, 1, 1, 1)

    def on_toggle_button_toggled(self, togglebutton):
        if togglebutton.get_active():
            print("%s has been toggled on" % (togglebutton.get_label()))
        else:
            print("%s has been toggled off" % (togglebutton.get_label()))

window = ToggleButton()
window.show_all()

Gtk.main()