Class CheckButton

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.gtk.CheckButton
All Implemented Interfaces:
Accessible, Actionable, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class CheckButton extends Widget implements Accessible, Actionable, Buildable, ConstraintTarget

Places a label next to an indicator.

Example GtkCheckButtons

A GtkCheckButton is created by calling either CheckButton() or withLabel(String).

The state of a GtkCheckButton can be set specifically using setActive(boolean), and retrieved using getActive().

Inconsistent state

In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent.

To set a GtkCheckButton to inconsistent state, use setInconsistent(boolean).

Grouping

Check buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off.

Grouped check buttons use a different indicator, and are commonly referred to as radio buttons.

Example GtkRadioButtons

To add a GtkCheckButton to a group, use setGroup(CheckButton).

When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful GAction with a target for each button. Using the toggled signals to keep track of the group changes and state is discouraged.

Shortcuts and Gestures

GtkCheckButton supports the following keyboard shortcuts:

  • ␣ or Enter activates the button.

CSS nodes

checkbutton[.text-button][.grouped]
├── check
╰── [label]

A GtkCheckButton has a main node with name checkbutton. If the Gtk.CheckButton:label or Gtk.CheckButton:child properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons.

Accessibility

GtkCheckButton uses the Gtk.AccessibleRole.checkbox role.

  • Constructor Details

    • CheckButton

      public CheckButton(MemorySegment address)
      Create a CheckButton instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • CheckButton

      public CheckButton()
      Create a new CheckButton.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the CheckButton class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected CheckButton asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • withLabel

      public static CheckButton withLabel(@Nullable String label)
      Creates a new GtkCheckButton with the given text.
      Parameters:
      label - the text for the check button.
      Returns:
      a new GtkCheckButton

    • withMnemonic

      public static CheckButton withMnemonic(@Nullable String label)
      Creates a new GtkCheckButton with the given text and a mnemonic.
      Parameters:
      label - The text of the button, with an underscore in front of the mnemonic character
      Returns:
      a new GtkCheckButton

    • getActive

      public boolean getActive()
      Returns whether the check button is active.
      Returns:
      whether the check button is active

    • getChild

      public @Nullable Widget getChild()
      Gets the child widget of this CheckButton or NULL if CheckButton:label is set.
      Returns:
      the child widget of this CheckButton
      Since:
      4.8

    • getInconsistent

      public boolean getInconsistent()
      Returns whether the check button is in an inconsistent state.
      Returns:
      true if this CheckButton is currently in an inconsistent state

    • getLabel

      public @Nullable String getLabel()
      Returns the label of the check button or NULL if CheckButton:child is set.
      Returns:
      The label this CheckButton shows next to the indicator. If no label is shown, null will be returned.

    • getUseUnderline

      public boolean getUseUnderline()
      Returns whether underlines in the label indicate mnemonics.
      Returns:
      The value of the Gtk.CheckButton:use-underline property. See setUseUnderline(boolean) for details on how to set a new value.

    • setActive

      public void setActive(boolean setting)
      Changes the check buttons active state.
      Parameters:
      setting - the new value to set

    • setChild

      public void setChild(@Nullable Widget child)

      Sets the child widget of button.

      Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for button. Most likely, you'll either set the accessibility label or description for this CheckButton explicitly, or you'll set a labelled-by or described-by relations from child to button.

      Parameters:
      child - the child widget
      Since:
      4.8

    • setGroup

      public void setGroup(@Nullable CheckButton group)

      Adds this CheckButton to the group of group.

      In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly known as a radio button.

      Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'.

      Setting up groups in a cycle leads to undefined behavior.

      Note that the same effect can be achieved via the Actionable API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value.

      Parameters:
      group - another GtkCheckButton to form a group with

    • setInconsistent

      public void setInconsistent(boolean inconsistent)

      Sets the GtkCheckButton to inconsistent state.

      You should turn off the inconsistent state again if the user checks the check button. This has to be done manually.

      Parameters:
      inconsistent - true if state is inconsistent

    • setLabel

      public void setLabel(@Nullable String label)

      Sets the text of self.

      If Gtk.CheckButton:use-underline is true, an underscore in label is interpreted as mnemonic indicator, see setUseUnderline(boolean) for details on this behavior.

      Parameters:
      label - The text shown next to the indicator, or null to show no text

    • setUseUnderline

      public void setUseUnderline(boolean setting)

      Sets whether underlines in the label indicate mnemonics.

      If setting is true, an underscore character in self's label indicates a mnemonic accelerator key. This behavior is similar to Gtk.Label:use-underline.

      Parameters:
      setting - the new value to set

    • activate

      protected void activate()

    • toggled

      protected void toggled()

    • onActivate

      public SignalConnection<CheckButton.ActivateCallback> onActivate(CheckButton.ActivateCallback handler)

      Emitted to when the check button is activated.

      The ::activate signal on GtkCheckButton is an action signal and emitting it causes the button to animate press then release.

      Applications should never connect to this signal, but use the Gtk.CheckButton::toggled signal.

      The default bindings for this signal are all forms of the ␣ and Enter keys.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      4.2
      See Also:

    • emitActivate

      public void emitActivate()
      Emits the "activate" signal. See onActivate(CheckButton.ActivateCallback).

    • onToggled

      public SignalConnection<CheckButton.ToggledCallback> onToggled(CheckButton.ToggledCallback handler)
      Emitted when the buttons's Gtk.CheckButton:active property changes.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitToggled

      public void emitToggled()
      Emits the "toggled" signal. See onToggled(CheckButton.ToggledCallback).

    • builder

      public static CheckButton.Builder<? extends CheckButton.Builder> builder()
      A CheckButton.Builder object constructs a CheckButton with the specified properties. Use the various set...() methods to set properties, and finish construction with CheckButton.Builder.build().
      Returns:
      the builder object