gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.Button

Contents

- Exported types
- Methods
  - getCanShrink
  - getChild
  - getHasFrame
  - getIconName
  - getLabel
  - getUseUnderline
  - new
  - newFromIconName
  - newWithLabel
  - newWithMnemonic
  - setCanShrink
  - setChild
  - setHasFrame
  - setIconName
  - setLabel
  - setUseUnderline
- Properties
  - canShrink
  - child
  - hasFrame
  - iconName
  - label
  - useUnderline
- Signals
  - activate
  - clicked

Description

Calls a callback function when the button is clicked.

<picture> <source srcset="button-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkButton" src="button.png"> </picture>

The `GtkButton` widget can hold any valid child widget. That is, it can hold almost any other standard `GtkWidget`. The most commonly used child is the `GtkLabel`.

# Shortcuts and Gestures

The following signals have default keybindings:

- Button::activate

# CSS nodes

`GtkButton` has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class.

Other style classes that are commonly used with `GtkButton` include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class.

Button-like widgets like `ToggleButton`, `MenuButton`, `VolumeButton`, `LockButton`, `ColorButton` or `FontButton` use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain `GtkButton`.

# Accessibility

`GtkButton` uses the `AccessibleRoleButton` role.

Synopsis

- newtype Button = Button (ManagedPtr Button)
- class (GObject o, IsDescendantOf Button o) => IsButton o
- toButton :: (MonadIO m, IsButton o) => o -> m Button
- buttonGetCanShrink :: (HasCallStack, MonadIO m, IsButton a) => a -> m Bool
- buttonGetChild :: (HasCallStack, MonadIO m, IsButton a) => a -> m (Maybe Widget)
- buttonGetHasFrame :: (HasCallStack, MonadIO m, IsButton a) => a -> m Bool
- buttonGetIconName :: (HasCallStack, MonadIO m, IsButton a) => a -> m (Maybe Text)
- buttonGetLabel :: (HasCallStack, MonadIO m, IsButton a) => a -> m (Maybe Text)
- buttonGetUseUnderline :: (HasCallStack, MonadIO m, IsButton a) => a -> m Bool
- buttonNew :: (HasCallStack, MonadIO m) => m Button
- buttonNewFromIconName :: (HasCallStack, MonadIO m) => Text -> m Button
- buttonNewWithLabel :: (HasCallStack, MonadIO m) => Text -> m Button
- buttonNewWithMnemonic :: (HasCallStack, MonadIO m) => Text -> m Button
- buttonSetCanShrink :: (HasCallStack, MonadIO m, IsButton a) => a -> Bool -> m ()
- buttonSetChild :: (HasCallStack, MonadIO m, IsButton a, IsWidget b) => a -> Maybe b -> m ()
- buttonSetHasFrame :: (HasCallStack, MonadIO m, IsButton a) => a -> Bool -> m ()
- buttonSetIconName :: (HasCallStack, MonadIO m, IsButton a) => a -> Text -> m ()
- buttonSetLabel :: (HasCallStack, MonadIO m, IsButton a) => a -> Text -> m ()
- buttonSetUseUnderline :: (HasCallStack, MonadIO m, IsButton a) => a -> Bool -> m ()
- constructButtonCanShrink :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o)
- getButtonCanShrink :: (MonadIO m, IsButton o) => o -> m Bool
- setButtonCanShrink :: (MonadIO m, IsButton o) => o -> Bool -> m ()
- clearButtonChild :: (MonadIO m, IsButton o) => o -> m ()
- constructButtonChild :: (IsButton o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)
- getButtonChild :: (MonadIO m, IsButton o) => o -> m (Maybe Widget)
- setButtonChild :: (MonadIO m, IsButton o, IsWidget a) => o -> a -> m ()
- constructButtonHasFrame :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o)
- getButtonHasFrame :: (MonadIO m, IsButton o) => o -> m Bool
- setButtonHasFrame :: (MonadIO m, IsButton o) => o -> Bool -> m ()
- constructButtonIconName :: (IsButton o, MonadIO m) => Text -> m (GValueConstruct o)
- getButtonIconName :: (MonadIO m, IsButton o) => o -> m (Maybe Text)
- setButtonIconName :: (MonadIO m, IsButton o) => o -> Text -> m ()
- constructButtonLabel :: (IsButton o, MonadIO m) => Text -> m (GValueConstruct o)
- getButtonLabel :: (MonadIO m, IsButton o) => o -> m (Maybe Text)
- setButtonLabel :: (MonadIO m, IsButton o) => o -> Text -> m ()
- constructButtonUseUnderline :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o)
- getButtonUseUnderline :: (MonadIO m, IsButton o) => o -> m Bool
- setButtonUseUnderline :: (MonadIO m, IsButton o) => o -> Bool -> m ()
- type ButtonActivateCallback = IO ()
- afterButtonActivate :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonActivateCallback) -> m SignalHandlerId
- onButtonActivate :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonActivateCallback) -> m SignalHandlerId
- type ButtonClickedCallback = IO ()
- afterButtonClicked :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonClickedCallback) -> m SignalHandlerId
- onButtonClicked :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonClickedCallback) -> m SignalHandlerId

# Exported types

newtype Button Source #

Memory-managed wrapper type.

Constructors

Button (ManagedPtr Button) |

#### Instances

Instances details

Eq Button Source # |
Instance details Defined in GI.Gtk.Objects.Button Methods (==) :: Button -> Button -> Bool Source # (/=) :: Button -> Button -> Bool Source #
GObject Button Source # |
Instance details Defined in GI.Gtk.Objects.Button
ManagedPtrNewtype Button Source # |
Instance details Defined in GI.Gtk.Objects.Button Methods toManagedPtr :: Button -> ManagedPtr Button Source #
TypedObject Button Source # |
Instance details Defined in GI.Gtk.Objects.Button Methods glibType :: IO GType Source #
HasParentTypes Button Source # |
Instance details Defined in GI.Gtk.Objects.Button
IsGValue (Maybe Button) Source # | Convert `Button` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.Button Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Button -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Button) Source #
type ParentTypes Button Source # |
Instance details Defined in GI.Gtk.Objects.Button type ParentTypes Button = '[Widget, Object, Accessible, Actionable, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf Button o) => IsButton o Source #

Type class for types which can be safely cast to `Button`, for instance with `toButton`.

#### Instances

Instances details

(GObject o, IsDescendantOf Button o) => IsButton o Source # |
Instance details Defined in GI.Gtk.Objects.Button

toButton :: (MonadIO m, IsButton o) => o -> m Button Source #

Cast to `Button`, 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

Expand

#### Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, 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, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getActionName, getActionTargetValue, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanShrink, getCanTarget, getChild, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasFrame, getHasTooltip, getHeight, getHexpand, getHexpandSet, getIconName, getLabel, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, 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

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

## getCanShrink

buttonGetCanShrink Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a button
-> m Bool | Returns: true if the button can shrink, and false otherwise

Retrieves whether the button can be smaller than the natural size of its contents.

Since: 4.12

## getChild

buttonGetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> m (Maybe Widget) | Returns: the child widget of `button`

Gets the child widget of `button`.

## getHasFrame

buttonGetHasFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> m Bool | Returns: `True` if the button has a frame

Returns whether the button has a frame.

## getIconName

buttonGetIconName Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: A `GtkButton`
-> m (Maybe Text) | Returns: The icon name set via `buttonSetIconName`

Returns the icon name of the button.

If the icon name has not been set with `buttonSetIconName` the return value will be `Nothing`. This will be the case if you create an empty button with `buttonNew` to use as a container.

## getLabel

buttonGetLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> m (Maybe Text) | Returns: The text of the label widget. This string is owned by the widget and must not be modified or freed.

Fetches the text from the label of the button.

If the label text has not been set with `buttonSetLabel` the return value will be `Nothing`. This will be the case if you create an empty button with `buttonNew` to use as a container.

## getUseUnderline

buttonGetUseUnderline Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> m Bool | Returns: `True` if an embedded underline in the button label indicates the mnemonic accelerator keys.

gets whether underlines are interpreted as mnemonics.

See `buttonSetUseUnderline`.

## new

buttonNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m Button | Returns: The newly created `GtkButton` widget.

Creates a new `GtkButton` widget.

To add a child widget to the button, use `buttonSetChild`.

## newFromIconName

buttonNewFromIconName Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `iconName`: an icon name
-> m Button | Returns: a new `GtkButton` displaying the themed icon

Creates a new button containing an icon from the current icon theme.

If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately.

## newWithLabel

buttonNewWithLabel Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `label`: The text you want the `GtkLabel` to hold
-> m Button | Returns: The newly created `GtkButton` widget

Creates a `GtkButton` widget with a `GtkLabel` child.

## newWithMnemonic

buttonNewWithMnemonic Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `label`: The text of the button, with an underscore in front of the mnemonic character
-> m Button | Returns: a new `GtkButton`

Creates a new `GtkButton` containing a label.

If characters in `label` are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing <kbd>Alt</kbd> and that key activates the button.

## setCanShrink

buttonSetCanShrink Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a button
-> Bool | `canShrink`: whether the button can shrink
-> m () |

Sets whether the button size can be smaller than the natural size of its contents.

For text buttons, setting `canShrink` to true will ellipsize the label.

For icons and custom children, this function has no effect.

Since: 4.12

## setChild

buttonSetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a, IsWidget b) |
=> a | `button`: a `GtkButton`
-> 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`.

## setHasFrame

buttonSetHasFrame Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> Bool | `hasFrame`: whether the button should have a visible frame
-> m () |

Sets the style of the button.

Buttons can have a flat appearance or have a frame drawn around them.

## setIconName

buttonSetIconName Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: A `GtkButton`
-> Text | `iconName`: An icon name
-> m () |

Adds a `GtkImage` with the given icon name as a child.

If `button` already contains a child widget, that child widget will be removed and replaced with the image.

## setLabel

buttonSetLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> Text | `label`: a string
-> m () |

Sets the text of the label of the button to `label`.

This will also clear any previously set labels.

## setUseUnderline

buttonSetUseUnderline Source #

Arguments

:: (HasCallStack, MonadIO m, IsButton a) |
=> a | `button`: a `GtkButton`
-> Bool | `useUnderline`: `True` if underlines in the text indicate mnemonics
-> m () |

Sets whether to use underlines as mnemonics.

If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.

# Properties

## canShrink

Whether the size of the button can be made smaller than the natural size of its contents.

For text buttons, setting this property will allow ellipsizing the label.

If the contents of a button are an icon or a custom widget, setting this property has no effect.

Since: 4.12

constructButtonCanShrink :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getButtonCanShrink :: (MonadIO m, IsButton o) => o -> m Bool Source #

Get the value of the “`can-shrink`” property. When overloading is enabled, this is equivalent to

    get button #canShrink

setButtonCanShrink :: (MonadIO m, IsButton o) => o -> Bool -> m () Source #

Set the value of the “`can-shrink`” property. When overloading is enabled, this is equivalent to

    set button [ #canShrink := value ]

## child

The child widget.

clearButtonChild :: (MonadIO m, IsButton o) => o -> m () Source #

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

    clear #child

constructButtonChild :: (IsButton o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o) Source #

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

getButtonChild :: (MonadIO m, IsButton o) => o -> m (Maybe Widget) Source #

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

    get button #child

setButtonChild :: (MonadIO m, IsButton o, IsWidget a) => o -> a -> m () Source #

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

    set button [ #child := value ]

## hasFrame

Whether the button has a frame.

constructButtonHasFrame :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getButtonHasFrame :: (MonadIO m, IsButton o) => o -> m Bool Source #

Get the value of the “`has-frame`” property. When overloading is enabled, this is equivalent to

    get button #hasFrame

setButtonHasFrame :: (MonadIO m, IsButton o) => o -> Bool -> m () Source #

Set the value of the “`has-frame`” property. When overloading is enabled, this is equivalent to

    set button [ #hasFrame := value ]

## iconName

The name of the icon used to automatically populate the button.

constructButtonIconName :: (IsButton o, MonadIO m) => Text -> m (GValueConstruct o) Source #

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

getButtonIconName :: (MonadIO m, IsButton o) => o -> m (Maybe Text) Source #

Get the value of the “`icon-name`” property. When overloading is enabled, this is equivalent to

    get button #iconName

setButtonIconName :: (MonadIO m, IsButton o) => o -> Text -> m () Source #

Set the value of the “`icon-name`” property. When overloading is enabled, this is equivalent to

    set button [ #iconName := value ]

## label

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

constructButtonLabel :: (IsButton o, MonadIO m) => Text -> m (GValueConstruct o) Source #

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

getButtonLabel :: (MonadIO m, IsButton o) => o -> m (Maybe Text) Source #

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

    get button #label

setButtonLabel :: (MonadIO m, IsButton o) => o -> Text -> m () Source #

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

    set button [ #label := value ]

## useUnderline

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

constructButtonUseUnderline :: (IsButton o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getButtonUseUnderline :: (MonadIO m, IsButton o) => o -> m Bool Source #

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

    get button #useUnderline

setButtonUseUnderline :: (MonadIO m, IsButton o) => o -> Bool -> m () Source #

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

    set button [ #useUnderline := value ]

# Signals

## activate

type ButtonActivateCallback = IO () Source #

Emitted to animate press then release.

This is an action signal. Applications should never connect to this signal, but use the Button::clicked signal.

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

afterButtonActivate :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonActivateCallback) -> m SignalHandlerId Source #

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

    after button #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.

onButtonActivate :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonActivateCallback) -> m SignalHandlerId Source #

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

    on button #activate callback

## clicked

type ButtonClickedCallback = IO () Source #

Emitted when the button has been activated (pressed and released).

afterButtonClicked :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonClickedCallback) -> m SignalHandlerId Source #

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

    after button #clicked 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.

onButtonClicked :: (IsButton a, MonadIO m) => a -> ((?self :: a) => ButtonClickedCallback) -> m SignalHandlerId Source #

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

    on button #clicked callback