GI.Gtk.Objects.Button

The Button widget is generally used to trigger a callback function that is called when the button is pressed. The various signals and how to use them are outlined below.

The Button widget can hold any valid child widget. That is, it can hold almost any other standard Widget. The most commonly used child is the Label.

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.

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, FontButton or FileChooserButton use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain GtkButton.

Exported types

newtype Button

Constructors

Button (ManagedPtr Button)

Instances

GObject Button

Methods

gobjectType :: Button -> IO GType

IsImplementorIface Button

IsObject Button

IsWidget Button

IsContainer Button

IsButton Button

IsBin Button

IsBuildable Button

IsActivatable Button

IsActionable Button

class GObject o => IsButton o

Instances

(GObject a, UnknownAncestorError Constraint Button a) => IsButton a

IsButton ToggleButton

IsButton ScaleButton

IsButton RadioButton

IsButton CheckButton

IsButton Button

IsButton ColorButton

IsButton FontButton

IsButton LinkButton

IsButton LockButton

IsButton VolumeButton

IsButton MenuButton

IsButton ModelButton

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

noButton :: Maybe Button

Methods

clicked

buttonClicked

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to send the signal to.

-> m ()

Emits a Button::clicked signal to the given Button.

enter

buttonEnter

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to send the signal to.

-> m ()

Deprecated: (Since version 2.20)Use the Widget::enter-notify-event signal.

Emits a Button::enter signal to the given Button.

getAlignment

buttonGetAlignment

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m (Float, Float)

Deprecated: (Since version 3.14)Access the child widget directly if you need to controlits alignment.

Gets the alignment of the child in the button.

Since: 2.4

getAlwaysShowImage

buttonGetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m Bool

Returns: True if the button will always show the image

Returns whether the button will ignore the Settings:gtk-button-images setting and always show the image, if available.

Since: 3.6

getEventWindow

buttonGetEventWindow

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m Window

Returns: button’s event window.

Returns the button’s event window if it is realized, Nothing otherwise. This function should be rarely needed.

Since: 2.22

getFocusOnClick

buttonGetFocusOnClick

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m Bool

Returns: True if the button grabs focus when it is clicked with the mouse.

Deprecated: (Since version 3.20)Use widgetGetFocusOnClick instead

Returns whether the button grabs focus when it is clicked with the mouse. See buttonSetFocusOnClick.

Since: 2.4

getImage

buttonGetImage

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m (Maybe Widget)

Returns: a Widget or Nothing in case there is no image

Gets the widget that is currenty set as the image of button. This may have been explicitly set by buttonSetImage or constructed by buttonNewFromStock.

Since: 2.6

getImagePosition

buttonGetImagePosition

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m PositionType

Returns: the position

Gets the position of the image relative to the text inside the button.

Since: 2.10

getLabel

buttonGetLabel

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m 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, as set by buttonSetLabel. If the label text has not been set the return value will be Nothing. This will be the case if you create an empty button with buttonNew to use as a container.

getRelief

buttonGetRelief

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want the ReliefStyle from.

-> m ReliefStyle

Returns: The current ReliefStyle

Returns the current relief style of the given Button.

getUseStock

buttonGetUseStock

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m Bool

Returns: True if the button label is used to select a stock item instead of being used directly as the label text.

Deprecated: (Since version 3.10)

Returns whether the button label is a stock item.

getUseUnderline

buttonGetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> m Bool

Returns: True if an embedded underline in the button label indicates the mnemonic accelerator keys.

Returns whether an embedded underline in the button label indicates a mnemonic. See gtk_button_set_use_underline ().

leave

buttonLeave

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to send the signal to.

-> m ()

Deprecated: (Since version 2.20)Use the Widget::leave-notify-event signal.

Emits a Button::leave signal to the given Button.

new

buttonNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Button

Returns: The newly created Button widget.

Creates a new Button widget. To add a child widget to the button, use containerAdd.

newFromIconName

buttonNewFromIconName

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

iconName: an icon name or Nothing

-> Int32

size: an icon size (IconSize)

-> m Button

Returns: a new Button 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.

This function is a convenience wrapper around buttonNew and buttonSetImage.

Since: 3.10

newFromStock

buttonNewFromStock

Arguments

:: (HasCallStack, MonadIO m)

=> Text

stockId: the name of the stock item

-> m Button

Returns: a new Button

Deprecated: (Since version 3.10)Use buttonNewWithLabel instead.

Creates a new Button containing the image and text from a stock item. Some stock ids have preprocessor macros like STOCK_OK and STOCK_APPLY.

If stockId is unknown, then it will be treated as a mnemonic label (as for buttonNewWithMnemonic).

newWithLabel

buttonNewWithLabel

Arguments

:: (HasCallStack, MonadIO m)

=> Text

label: The text you want the Label to hold.

-> m Button

Returns: The newly created Button widget.

Creates a Button widget with a Label child containing the given text.

newWithMnemonic

buttonNewWithMnemonic

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 Button

Creates a new Button 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 Alt and that key activates the button.

pressed

buttonPressed

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to send the signal to.

-> m ()

Deprecated: (Since version 2.20)Use the Widget::button-press-event signal.

Emits a Button::pressed signal to the given Button.

released

buttonReleased

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to send the signal to.

-> m ()

Deprecated: (Since version 2.20)Use the Widget::button-release-event signal.

Emits a Button::released signal to the given Button.

setAlignment

buttonSetAlignment

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Float

xalign: the horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned

-> Float

yalign: the vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned

-> m ()

Deprecated: (Since version 3.14)Access the child widget directly if you need to controlits alignment.

Sets the alignment of the child. This property has no effect unless the child is a Misc or a Alignment.

Since: 2.4

setAlwaysShowImage

buttonSetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Bool

alwaysShow: True if the menuitem should always show the image

-> m ()

If True, the button will ignore the Settings:gtk-button-images setting and always show the image, if available.

Use this property if the button would be useless or hard to use without the image.

Since: 3.6

setFocusOnClick

buttonSetFocusOnClick

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Bool

focusOnClick: whether the button grabs focus when clicked with the mouse

-> m ()

Deprecated: (Since version 3.20)Use widgetSetFocusOnClick instead

Sets whether the button will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application.

Since: 2.4

setImage

buttonSetImage

Arguments

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

=> a

button: a Button

-> b

image: a widget to set as the image for the button

-> m ()

Set the image of button to the given widget. The image will be displayed if the label text is Nothing or if Button:always-show-image is True. You don’t have to call widgetShow on image yourself.

Since: 2.6

setImagePosition

buttonSetImagePosition

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> PositionType

position: the position

-> m ()

Sets the position of the image relative to the text inside the button.

Since: 2.10

setLabel

buttonSetLabel

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Text

label: a string

-> m ()

Sets the text of the label of the button to str. This text is also used to select the stock item if buttonSetUseStock is used.

This will also clear any previously set labels.

setRelief

buttonSetRelief

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: The Button you want to set relief styles of

-> ReliefStyle

relief: The GtkReliefStyle as described above

-> m ()

Sets the relief style of the edges of the given Button widget. Two styles exist, ReliefStyleNormal and ReliefStyleNone. The default style is, as one can guess, ReliefStyleNormal. The deprecated value ReliefStyleHalf behaves the same as ReliefStyleNormal.

setUseStock

buttonSetUseStock

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Bool

useStock: True if the button should use a stock item

-> m ()

Deprecated: (Since version 3.10)

If True, the label set on the button is used as a stock id to select the stock item for the button.

setUseUnderline

buttonSetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsButton a)

=> a

button: a Button

-> Bool

useUnderline: True if underlines in the text indicate mnemonics

-> m ()

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

Properties

alwaysShowImage

constructButtonAlwaysShowImage :: IsButton o => Bool -> IO (GValueConstruct o)

getButtonAlwaysShowImage :: (MonadIO m, IsButton o) => o -> m Bool

setButtonAlwaysShowImage :: (MonadIO m, IsButton o) => o -> Bool -> m ()

image

constructButtonImage :: (IsButton o, IsWidget a) => a -> IO (GValueConstruct o)

getButtonImage :: (MonadIO m, IsButton o) => o -> m (Maybe Widget)

setButtonImage :: (MonadIO m, IsButton o, IsWidget a) => o -> a -> m ()

imagePosition

constructButtonImagePosition :: IsButton o => PositionType -> IO (GValueConstruct o)

getButtonImagePosition :: (MonadIO m, IsButton o) => o -> m PositionType

setButtonImagePosition :: (MonadIO m, IsButton o) => o -> PositionType -> m ()

label

constructButtonLabel :: IsButton o => Text -> IO (GValueConstruct o)

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

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

relief

constructButtonRelief :: IsButton o => ReliefStyle -> IO (GValueConstruct o)

getButtonRelief :: (MonadIO m, IsButton o) => o -> m ReliefStyle

setButtonRelief :: (MonadIO m, IsButton o) => o -> ReliefStyle -> m ()

useStock

constructButtonUseStock :: IsButton o => Bool -> IO (GValueConstruct o)

getButtonUseStock :: (MonadIO m, IsButton o) => o -> m Bool

setButtonUseStock :: (MonadIO m, IsButton o) => o -> Bool -> m ()

useUnderline

constructButtonUseUnderline :: IsButton o => Bool -> IO (GValueConstruct o)

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

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

xalign

constructButtonXalign :: IsButton o => Float -> IO (GValueConstruct o)

getButtonXalign :: (MonadIO m, IsButton o) => o -> m Float

setButtonXalign :: (MonadIO m, IsButton o) => o -> Float -> m ()

yalign

constructButtonYalign :: IsButton o => Float -> IO (GValueConstruct o)

getButtonYalign :: (MonadIO m, IsButton o) => o -> m Float

setButtonYalign :: (MonadIO m, IsButton o) => o -> Float -> m ()

Signals

activate

type ButtonActivateCallback = IO ()

type C_ButtonActivateCallback = Ptr () -> Ptr () -> IO ()

afterButtonActivate :: (IsButton a, MonadIO m) => a -> ButtonActivateCallback -> m SignalHandlerId

genClosure_ButtonActivate :: ButtonActivateCallback -> IO Closure

mk_ButtonActivateCallback :: C_ButtonActivateCallback -> IO (FunPtr C_ButtonActivateCallback)

noButtonActivateCallback :: Maybe ButtonActivateCallback

onButtonActivate :: (IsButton a, MonadIO m) => a -> ButtonActivateCallback -> m SignalHandlerId

wrap_ButtonActivateCallback :: ButtonActivateCallback -> Ptr () -> Ptr () -> IO ()

clicked

type ButtonClickedCallback = IO ()

type C_ButtonClickedCallback = Ptr () -> Ptr () -> IO ()

afterButtonClicked :: (IsButton a, MonadIO m) => a -> ButtonClickedCallback -> m SignalHandlerId

genClosure_ButtonClicked :: ButtonClickedCallback -> IO Closure

mk_ButtonClickedCallback :: C_ButtonClickedCallback -> IO (FunPtr C_ButtonClickedCallback)

noButtonClickedCallback :: Maybe ButtonClickedCallback

onButtonClicked :: (IsButton a, MonadIO m) => a -> ButtonClickedCallback -> m SignalHandlerId

wrap_ButtonClickedCallback :: ButtonClickedCallback -> Ptr () -> Ptr () -> IO ()

enter

type ButtonEnterCallback = IO ()

Deprecated: (Since version 2.8)Use the Widget::enter-notify-event signal.

type C_ButtonEnterCallback = Ptr () -> Ptr () -> IO ()

afterButtonEnter :: (IsButton a, MonadIO m) => a -> ButtonEnterCallback -> m SignalHandlerId

genClosure_ButtonEnter :: ButtonEnterCallback -> IO Closure

mk_ButtonEnterCallback :: C_ButtonEnterCallback -> IO (FunPtr C_ButtonEnterCallback)

noButtonEnterCallback :: Maybe ButtonEnterCallback

onButtonEnter :: (IsButton a, MonadIO m) => a -> ButtonEnterCallback -> m SignalHandlerId

wrap_ButtonEnterCallback :: ButtonEnterCallback -> Ptr () -> Ptr () -> IO ()

leave

type ButtonLeaveCallback = IO ()

Deprecated: (Since version 2.8)Use the Widget::leave-notify-event signal.

type C_ButtonLeaveCallback = Ptr () -> Ptr () -> IO ()

afterButtonLeave :: (IsButton a, MonadIO m) => a -> ButtonLeaveCallback -> m SignalHandlerId

genClosure_ButtonLeave :: ButtonLeaveCallback -> IO Closure

mk_ButtonLeaveCallback :: C_ButtonLeaveCallback -> IO (FunPtr C_ButtonLeaveCallback)

noButtonLeaveCallback :: Maybe ButtonLeaveCallback

onButtonLeave :: (IsButton a, MonadIO m) => a -> ButtonLeaveCallback -> m SignalHandlerId

wrap_ButtonLeaveCallback :: ButtonLeaveCallback -> Ptr () -> Ptr () -> IO ()

pressed

type ButtonPressedCallback = IO ()

Deprecated: (Since version 2.8)Use the Widget::button-press-event signal.

type C_ButtonPressedCallback = Ptr () -> Ptr () -> IO ()

afterButtonPressed :: (IsButton a, MonadIO m) => a -> ButtonPressedCallback -> m SignalHandlerId

genClosure_ButtonPressed :: ButtonPressedCallback -> IO Closure

mk_ButtonPressedCallback :: C_ButtonPressedCallback -> IO (FunPtr C_ButtonPressedCallback)

noButtonPressedCallback :: Maybe ButtonPressedCallback

onButtonPressed :: (IsButton a, MonadIO m) => a -> ButtonPressedCallback -> m SignalHandlerId

wrap_ButtonPressedCallback :: ButtonPressedCallback -> Ptr () -> Ptr () -> IO ()

released

type ButtonReleasedCallback = IO ()

Deprecated: (Since version 2.8)Use the Widget::button-release-event signal.

type C_ButtonReleasedCallback = Ptr () -> Ptr () -> IO ()

afterButtonReleased :: (IsButton a, MonadIO m) => a -> ButtonReleasedCallback -> m SignalHandlerId

genClosure_ButtonReleased :: ButtonReleasedCallback -> IO Closure

mk_ButtonReleasedCallback :: C_ButtonReleasedCallback -> IO (FunPtr C_ButtonReleasedCallback)

noButtonReleasedCallback :: Maybe ButtonReleasedCallback

onButtonReleased :: (IsButton a, MonadIO m) => a -> ButtonReleasedCallback -> m SignalHandlerId

wrap_ButtonReleasedCallback :: ButtonReleasedCallback -> Ptr () -> Ptr () -> IO ()