GI.Gtk.Objects.CheckButton

A GtkCheckButton places a label next to an indicator.

A GtkCheckButton is created by calling either checkButtonNew or checkButtonNewWithLabel.

The state of a GtkCheckButton can be set specifically using checkButtonSetActive, and retrieved using checkButtonGetActive.

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 checkButtonSetInconsistent.

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*.

To add a GtkCheckButton to a group, use checkButtonSetGroup.

CSS nodes

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

A GtkCheckButton has a main node with name checkbutton. If the CheckButton:label or 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 AccessibleRoleCheckbox role.

Exported types

newtype CheckButton

Memory-managed wrapper type.

Constructors

CheckButton (ManagedPtr CheckButton)

Instances

Eq CheckButton

Defined in GI.Gtk.Objects.CheckButton

Methods

(==) :: CheckButton -> CheckButton -> Bool

(/=) :: CheckButton -> CheckButton -> Bool

GObject CheckButton

Defined in GI.Gtk.Objects.CheckButton

ManagedPtrNewtype CheckButton

Defined in GI.Gtk.Objects.CheckButton

Methods

toManagedPtr :: CheckButton -> ManagedPtr CheckButton

TypedObject CheckButton

Defined in GI.Gtk.Objects.CheckButton

Methods

glibType :: IO GType

HasParentTypes CheckButton

Defined in GI.Gtk.Objects.CheckButton

IsGValue (Maybe CheckButton)

Convert CheckButton to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.CheckButton

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe CheckButton -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe CheckButton)

type ParentTypes CheckButton

Defined in GI.Gtk.Objects.CheckButton

type ParentTypes CheckButton = '[Widget, Object, Accessible, Actionable, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf CheckButton o) => IsCheckButton o

Type class for types which can be safely cast to CheckButton, for instance with toCheckButton.

Instances

(GObject o, IsDescendantOf CheckButton o) => IsCheckButton o

Defined in GI.Gtk.Objects.CheckButton

toCheckButton :: (MonadIO m, IsCheckButton o) => o -> m CheckButton

Cast to CheckButton, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleRole, getActionName, getActionTargetValue, getActive, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getBuildableId, getCanFocus, getCanTarget, getChild, getChildVisible, getClipboard, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getInconsistent, getLabel, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getUseUnderline, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setActionName, setActionTargetValue, setActive, setCanFocus, setCanTarget, setChild, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDetailedActionName, setDirection, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setGroup, setHalign, setHasTooltip, setHexpand, setHexpandSet, setInconsistent, setLabel, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setUseUnderline, setValign, setVexpand, setVexpandSet, setVisible.

getActive

checkButtonGetActive

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> m Bool

Returns: whether the check button is active

Returns whether the check button is active.

getChild

checkButtonGetChild

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

button: a GtkCheckButton

-> m (Maybe Widget)

Returns: the child widget of button

Gets the child widget of button or NULL if [propertycheckButton:label] is set.

Since: 4.8

getInconsistent

checkButtonGetInconsistent

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

checkButton: a GtkCheckButton

-> m Bool

Returns: True if checkButton is currently in an inconsistent state

Returns whether the check button is in an inconsistent state.

getLabel

checkButtonGetLabel

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> m (Maybe Text)

Returns: The label self shows next to the indicator. If no label is shown, Nothing will be returned.

Returns the label of the check button or NULL if [propertycheckButton:child] is set.

getUseUnderline

checkButtonGetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> m Bool

Returns: The value of the CheckButton:useUnderline property. See checkButtonSetUseUnderline for details on how to set a new value.

Returns whether underlines in the label indicate mnemonics.

new

checkButtonNew

Arguments

:: (HasCallStack, MonadIO m)

=> m CheckButton

Returns: a new GtkCheckButton

Creates a new GtkCheckButton.

newWithLabel

checkButtonNewWithLabel

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

label: the text for the check button.

-> m CheckButton

Returns: a new GtkCheckButton

Creates a new GtkCheckButton with the given text.

newWithMnemonic

checkButtonNewWithMnemonic

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

label: The text of the button, with an underscore in front of the mnemonic character

-> m CheckButton

Returns: a new GtkCheckButton

Creates a new GtkCheckButton with the given text and a mnemonic.

setActive

checkButtonSetActive

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> Bool

setting: the new value to set

-> m ()

Changes the check buttons active state.

setChild

checkButtonSetChild

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a, IsWidget b)

=> a

button: a GtkCheckButton

-> Maybe b

child: the child widget

-> m ()

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 button explicitly, or you'll set a labelled-by or described-by relations from child to button.

Since: 4.8

setGroup

checkButtonSetGroup

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a, IsCheckButton b)

=> a

self: a GtkCheckButton

-> Maybe b

group: another GtkCheckButton to form a group with

-> m ()

Adds self 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.

setInconsistent

checkButtonSetInconsistent

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

checkButton: a GtkCheckButton

-> Bool

inconsistent: True if state is inconsistent

-> m ()

Sets the GtkCheckButton to inconsistent state.

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

setLabel

checkButtonSetLabel

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> Maybe Text

label: The text shown next to the indicator, or Nothing to show no text

-> m ()

Sets the text of self.

If CheckButton:useUnderline is True, an underscore in label is interpreted as mnemonic indicator, see checkButtonSetUseUnderline for details on this behavior.

setUseUnderline

checkButtonSetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsCheckButton a)

=> a

self: a GtkCheckButton

-> Bool

setting: the new value to set

-> m ()

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 Label:useUnderline.

Properties

active

If the check button is active.

Setting active to True will add the :checked: state to both the check button and the indicator CSS node.

constructCheckButtonActive :: (IsCheckButton o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “active” property. This is rarely needed directly, but it is used by new.

getCheckButtonActive :: (MonadIO m, IsCheckButton o) => o -> m Bool

Get the value of the “active” property. When overloading is enabled, this is equivalent to

get checkButton #active

setCheckButtonActive :: (MonadIO m, IsCheckButton o) => o -> Bool -> m ()

Set the value of the “active” property. When overloading is enabled, this is equivalent to

set checkButton [ #active := value ]

child

The child widget.

Since: 4.8

clearCheckButtonChild :: (MonadIO m, IsCheckButton o) => o -> m ()

Set the value of the “child” property to Nothing. When overloading is enabled, this is equivalent to

clear #child

constructCheckButtonChild :: (IsCheckButton o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “child” property. This is rarely needed directly, but it is used by new.

getCheckButtonChild :: (MonadIO m, IsCheckButton o) => o -> m (Maybe Widget)

Get the value of the “child” property. When overloading is enabled, this is equivalent to

get checkButton #child

setCheckButtonChild :: (MonadIO m, IsCheckButton o, IsWidget a) => o -> a -> m ()

Set the value of the “child” property. When overloading is enabled, this is equivalent to

set checkButton [ #child := value ]

group

The check button whose group this widget belongs to.

clearCheckButtonGroup :: (MonadIO m, IsCheckButton o) => o -> m ()

Set the value of the “group” property to Nothing. When overloading is enabled, this is equivalent to

clear #group

constructCheckButtonGroup :: (IsCheckButton o, MonadIO m, IsCheckButton a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “group” property. This is rarely needed directly, but it is used by new.

setCheckButtonGroup :: (MonadIO m, IsCheckButton o, IsCheckButton a) => o -> a -> m ()

Set the value of the “group” property. When overloading is enabled, this is equivalent to

set checkButton [ #group := value ]

inconsistent

If the check button is in an “in between” state.

The inconsistent state only affects visual appearance, not the semantics of the button.

constructCheckButtonInconsistent :: (IsCheckButton o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “inconsistent” property. This is rarely needed directly, but it is used by new.

getCheckButtonInconsistent :: (MonadIO m, IsCheckButton o) => o -> m Bool

Get the value of the “inconsistent” property. When overloading is enabled, this is equivalent to

get checkButton #inconsistent

setCheckButtonInconsistent :: (MonadIO m, IsCheckButton o) => o -> Bool -> m ()

Set the value of the “inconsistent” property. When overloading is enabled, this is equivalent to

set checkButton [ #inconsistent := value ]

label

Text of the label inside the check button, if it contains a label widget.

clearCheckButtonLabel :: (MonadIO m, IsCheckButton o) => o -> m ()

Set the value of the “label” property to Nothing. When overloading is enabled, this is equivalent to

clear #label

constructCheckButtonLabel :: (IsCheckButton o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “label” property. This is rarely needed directly, but it is used by new.

getCheckButtonLabel :: (MonadIO m, IsCheckButton o) => o -> m (Maybe Text)

Get the value of the “label” property. When overloading is enabled, this is equivalent to

get checkButton #label

setCheckButtonLabel :: (MonadIO m, IsCheckButton o) => o -> Text -> m ()

Set the value of the “label” property. When overloading is enabled, this is equivalent to

set checkButton [ #label := value ]

useUnderline

If set, an underline in the text indicates that the following character is to be used as mnemonic.

constructCheckButtonUseUnderline :: (IsCheckButton o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “use-underline” property. This is rarely needed directly, but it is used by new.

getCheckButtonUseUnderline :: (MonadIO m, IsCheckButton o) => o -> m Bool

Get the value of the “use-underline” property. When overloading is enabled, this is equivalent to

get checkButton #useUnderline

setCheckButtonUseUnderline :: (MonadIO m, IsCheckButton o) => o -> Bool -> m ()

Set the value of the “use-underline” property. When overloading is enabled, this is equivalent to

set checkButton [ #useUnderline := value ]

Signals

activate

type CheckButtonActivateCallback = IO ()

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 CheckButton::toggled signal.

Since: 4.2

afterCheckButtonActivate :: (IsCheckButton a, MonadIO m) => a -> ((?self :: a) => CheckButtonActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after checkButton #activate callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onCheckButtonActivate :: (IsCheckButton a, MonadIO m) => a -> ((?self :: a) => CheckButtonActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on checkButton #activate callback

toggled

type CheckButtonToggledCallback = IO ()

Emitted when the buttons's CheckButton:active property changes.

afterCheckButtonToggled :: (IsCheckButton a, MonadIO m) => a -> ((?self :: a) => CheckButtonToggledCallback) -> m SignalHandlerId

Connect a signal handler for the toggled signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after checkButton #toggled callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onCheckButtonToggled :: (IsCheckButton a, MonadIO m) => a -> ((?self :: a) => CheckButtonToggledCallback) -> m SignalHandlerId

Connect a signal handler for the toggled signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on checkButton #toggled callback