Gnome::Gtk3::ToggleButton

Table of Contents

Description
Css Nodes
See Also
Synopsis
Declaration
Uml Diagram

Methods
new
default, no options
:label
:native-object
:build-id
get-active
get-inconsistent
get-mode
set-active
set-inconsistent
set-mode
toggled
_gtk_toggle_button_new
_gtk_toggle_button_new_with_label
_gtk_toggle_button_new_with_mnemonic
Signals
First method
Second method
Supported signals
toggled
Properties
Supported properties
Active: active
Draw Indicator: draw-indicator
Inconsistent: inconsistent
[gtk_] toggle_button_new
[[gtk_] toggle_button_] new_with_label
[[gtk_] toggle_button_] new_with_mnemonic
[[gtk_] toggle_button_] set_mode
[[gtk_] toggle_button_] get_mode
[[gtk_] toggle_button_] set_active
[[gtk_] toggle_button_] get_active
[gtk_] toggle_button_toggled
[[gtk_] toggle_button_] set_inconsistent
[[gtk_] toggle_button_] get_inconsistent
Signals
First method
Second method
Supported signals
toggled

Create buttons which retain their state

Description

A Gnome::Gtk3::ToggleButton is a Gnome::Gtk3::Button 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_toggle_button_new() or gtk_toggle_button_new_with_label(). If using the former, it is advisable to pack a widget, (such as a Gnome::Gtk3::Label and/or a Gnome::Gtk3::Image), into the toggle button’s container. (See Gnome::Gtk3::Button for more information).

The state of a Gnome::Gtk3::ToggleButton can be set specifically using gtk_toggle_button_set_active(), and retrieved using gtk_toggle_button_get_active().

To simply switch the state of a toggle button, use gtk_toggle_button_toggled().

Css Nodes

Gnome::Gtk3::ToggleButton has a single CSS node with name button. To differentiate it from a plain Gnome::Gtk3::Button, it gets the .toggle style class.

Synopsis

Declaration

unit class Gnome::Gtk3::ToggleButton;
also is Gnome::Gtk3::Button;

Uml Diagram

Methods

new

default, no options

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

multi method new ( )

:label

Create a Gnome::Gtk3::ToggleButton with a label.

multi method new ( Str :$label! )

:native-object

Create a ToggleButton object using a native object from elsewhere. See also Gnome::N::TopLevelClassSupport.

multi method new ( N-GObject :$native-object! )

:build-id

Create a ToggleButton object using a native object returned from a builder. See also Gnome::GObject::Object.

multi method new ( Str :$build-id! )

get-active

Queries a Gnome::Gtk3::ToggleButton and returns its current state. Returns True if the toggle button is pressed in and False if it is raised.

Returns: a gboolean value.

method get-active ( --> Bool )

get-inconsistent

Gets the value set by set-inconsistent().

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

method get-inconsistent ( --> Bool )

get-mode

Retrieves whether the button is displayed as a separate indicator and label. See set-mode().

Returns: True if the togglebutton is drawn as a separate indicator and label.

method get-mode ( --> Bool )

set-active

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

method set-active ( Bool $is-active )

Bool $is-active; True for pressed in, False otherwise

set-inconsistent

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, you may want to display the toggle in an “in between” state. This function turns on “in between” display. Normally you would turn off the inconsistent state again if the user toggles the toggle button. This has to be done manually, set-inconsistent() only affects visual appearance, it doesn’t affect the semantics of the button.

method set-inconsistent ( Bool $setting )

Bool $setting; True if state is inconsistent

set-mode

Sets whether the button is displayed as a separate indicator and label. You can call this function on a checkbutton or a radiobutton with $draw-indicator = False to make the button look like a normal button.

This can be used to create linked strip of buttons that work like a Gnome::Gtk3::StackSwitcher.

This function only affects instances of classes like Gnome::Gtk3::CheckButton and Gnome::Gtk3::RadioButton that derive from Gnome::Gtk3::ToggleButton, not instances of Gnome::Gtk3::ToggleButton itself.

method set-mode ( Bool $draw-indicator )

Bool $draw-indicator; if True, draw the button as a separate indicator and label; if False, draw the button like a normal button

toggled

Emits the toggled signal on the Gnome::Gtk3::ToggleButton. There is no good reason for an application ever to call this function.

method toggled ( )

_gtk_toggle_button_new

Creates a new toggle button. A widget should be packed into the button, as in gtk-button-new().

Returns: a new toggle button.

method _gtk_toggle_button_new ( --> N-GObject )

_gtk_toggle_button_new_with_label

Creates a new toggle button with a text label.

Returns: a new toggle button.

method _gtk_toggle_button_new_with_label ( Str $label --> N-GObject )

Str $label; a string containing the message to be placed in the toggle button.

_gtk_toggle_button_new_with_mnemonic

Creates a new Gnome::Gtk3::ToggleButton containing a label. The label will be created using gtk-label-new-with-mnemonic(), so underscores in label indicate the mnemonic for the button.

Returns: a new Gnome::Gtk3::ToggleButton

method _gtk_toggle_button_new_with_mnemonic ( Str $label --> N-GObject )

Str $label; the text of the button, with an underscore in front of the mnemonic character

Signals

There are two ways to connect to a signal. The first option you have is to use register-signal() from Gnome::GObject::Object. The second option is to use connect-object() directly from Gnome::GObject::Signal.

First method

The positional arguments of the signal handler are all obligatory as well as their types. The named attributes :$widget and user data are optional.

# handler method
method mouse-event ( GdkEvent $event, :$widget ) { ... }

# connect a signal on window object
my Gnome::Gtk3::Window $w .= new( ... );
$w.register-signal( self, 'mouse-event', 'button-press-event');

Second method

my Gnome::Gtk3::Window $w .= new( ... );
my Callable $handler = sub (
  N-GObject $native, GdkEvent $event, OpaquePointer $data
) {
  ...
}

$w.connect-object( 'button-press-event', $handler);

Also here, the types of positional arguments in the signal handler are important. This is because both methods register-signal() and connect-object() are using the signatures of the handler routines to setup the native call interface.

Supported signals

toggled

Should be connected if you wish to perform an action whenever the Gnome::Gtk3::ToggleButton's state is changed.

method handler (
  Int :$_handle_id,
  Gnome::GObject::Object :_widget($togglebutton),
  *%user-options
);

$togglebutton; the object which received the signal.
$_handle_id; the registered event handler id

Properties

An example of using a string type property of a Gnome::Gtk3::Label object. This is just showing how to set/read a property, not that it is the best way to do it. This is because a) The class initialization often provides some options to set some of the properties and b) the classes provide many methods to modify just those properties. In the case below one can use new(:label('my text label')) or .set-text('my text label').

my Gnome::Gtk3::Label $label .= new;
my Gnome::GObject::Value $gv .= new(:init(G_TYPE_STRING));
$label.get-property( 'label', $gv);
$gv.set-string('my text label');

Supported properties

Active: active

If the toggle button should be pressed in Default value: False

The Gnome::GObject::Value type of property active is G_TYPE_BOOLEAN.

Draw Indicator: draw-indicator

If the toggle part of the button is displayed Default value: False

The Gnome::GObject::Value type of property draw-indicator is G_TYPE_BOOLEAN.

Inconsistent: inconsistent

If the toggle button is in an \in between\ state Default value: False

The Gnome::GObject::Value type of property inconsistent is G_TYPE_BOOLEAN.

[gtk_] toggle_button_new

Creates a new toggle button. A widget should be packed into the button, as in gtk_button_new().

Returns: a new toggle button.

method gtk_toggle_button_new ( --> N-GObject  )

[[gtk_] toggle_button_] new_with_label

Creates a new toggle button with a text label.

Returns: a new toggle button.

method gtk_toggle_button_new_with_label ( Str $label --> N-GObject  )

Str $label; a string containing the message to be placed in the toggle button.

[[gtk_] toggle_button_] new_with_mnemonic

Creates a new Gnome::Gtk3::ToggleButton containing a label. The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the mnemonic for the button.

Returns: a new Gnome::Gtk3::ToggleButton

method gtk_toggle_button_new_with_mnemonic ( Str $label --> N-GObject  )

Str $label; the text of the button, with an underscore in front of the mnemonic character

[[gtk_] toggle_button_] set_mode

Sets whether the button is displayed as a separate indicator and label. You can call this function on a checkbutton or a radiobutton with $draw-indicator = 0 to make the button look like a normal button.

This can be used to create linked strip of buttons that work like a Gnome::Gtk3::StackSwitcher.

method gtk_toggle_button_set_mode ( Int $draw-indicator )

Int $draw-indicator; if 1, draw the button as a separate indicator and label; if 0, draw the button like a normal button

[[gtk_] toggle_button_] get_mode

Retrieves whether the button is displayed as a separate indicator and label. See gtk_toggle_button_set_mode().

Returns: 1 if the togglebutton is drawn as a separate indicator and label.

method gtk_toggle_button_get_mode ( --> Int  )

[[gtk_] toggle_button_] set_active

Sets the status of the toggle button. Set to 1 if you want the Gnome::Gtk3::ToggleButton to be “pressed in”, and 0 to raise it. This action causes the toggled signal and the clicked signal to be emitted.

method gtk_toggle_button_set_active ( Int $is-active )

Int $is-active; 1 or 0.

[[gtk_] toggle_button_] get_active

Queries a Gnome::Gtk3::ToggleButton and returns its current state. Returns 1 if the toggle button is pressed in and 0 if it is raised.

Returns: a Int value.

method gtk_toggle_button_get_active ( --> Int  )

[gtk_] toggle_button_toggled

Emits the toggled signal on the Gnome::Gtk3::ToggleButton. There is no good reason for an application ever to call this function.

method gtk_toggle_button_toggled ( )

[[gtk_] toggle_button_] set_inconsistent

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, you may want to display the toggle in an “in between” state. This function turns on “in between” display. Normally you would turn off the inconsistent state again if the user toggles the toggle button. This has to be done manually, gtk_toggle_button_set_inconsistent() only affects visual appearance, it doesn’t affect the semantics of the button.

method gtk_toggle_button_set_inconsistent ( Int $setting )

Int $setting; 1 if state is inconsistent

[[gtk_] toggle_button_] get_inconsistent

Gets the value set by gtk_toggle_button_set_inconsistent().

Returns: 1 if the button is displayed as inconsistent, 0 otherwise

method gtk_toggle_button_get_inconsistent ( --> Int  )

Signals

There are two ways to connect to a signal. The first option you have is to use register-signal() from Gnome::GObject::Object. The second option is to use g_signal_connect_object() directly from Gnome::GObject::Signal.

First method

The positional arguments of the signal handler are all obligatory as well as their types. The named attributes :$widget and user data are optional.

# handler method
method mouse-event ( N-GdkEvent $event, :$widget ) { ... }

# connect a signal on window object
my Gnome::Gtk3::Window $w .= new( ... );
$w.register-signal( self, 'mouse-event', 'button-press-event');

Second method

my Gnome::Gtk3::Window $w .= new( ... );
my Callable $handler = sub (
  N-GObject $native, N-GdkEvent $event, OpaquePointer $data
) {
  ...
}

$w.connect-object( 'button-press-event', $handler);

Also here, the types of positional arguments in the signal handler are important. This is because both methods register-signal() and g_signal_connect_object() are using the signatures of the handler routines to setup the native call interface.

Supported signals

toggled

Should be connected if you wish to perform an action whenever the Gnome::Gtk3::ToggleButton's state is changed.

method handler (
  Int :$_handler_id,
  Gnome::GObject::Object :_widget($togglebutton),
  *%user-options
);

$togglebutton; the object which received the signal.