gi-gtk-3.0.31: Gtk bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (inaki@blueleaf.cc)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.Button

Contents

Description

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.

Synopsis

Exported types

newtype Button Source #

Memory-managed wrapper type.

Constructors

Button (ManagedPtr Button) 
Instances
GObject Button Source # 
Instance details

Defined in GI.Gtk.Objects.Button

Methods

gobjectType :: IO GType #

HasParentTypes Button Source # 
Instance details

Defined in GI.Gtk.Objects.Button

type ParentTypes Button Source # 
Instance details

Defined in GI.Gtk.Objects.Button

type ParentTypes Button = Bin ': (Container ': (Widget ': (Object ': (ImplementorIface ': (Actionable ': (Activatable ': (Buildable ': ([] :: [Type]))))))))

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

noButton :: Maybe Button Source #

A convenience alias for Nothing :: Maybe Button.

Methods

clicked

buttonClicked Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Text

stockId: the name of the stock item

-> m Button

Returns: a new Button

Deprecated: (Since version 3.10)Stock items are deprecated. Use buttonNewWithLabelinstead.

Creates a new Button containing the image and text from a [stock item][gtkstock]. 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 Source #

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 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 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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

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

button: a Button

-> Maybe b

image: a widget to set as the image for the button, or Nothing to unset

-> 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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

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

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

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

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

Get the value of the “always-show-image” property. When overloading is enabled, this is equivalent to

get button #alwaysShowImage

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

Set the value of the “always-show-image” property. When overloading is enabled, this is equivalent to

set button [ #alwaysShowImage := value ]

image

The child widget to appear next to the button text.

Since: 2.6

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

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

clear #image

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

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

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

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

get button #image

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

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

set button [ #image := value ]

imagePosition

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

Since: 2.10

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

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

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

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

get button #imagePosition

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

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

set button [ #imagePosition := value ]

label

No description available in the introspection data.

constructButtonLabel :: IsButton o => Text -> IO (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 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 ]

relief

No description available in the introspection data.

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

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

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

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

get button #relief

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

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

set button [ #relief := value ]

useStock

No description available in the introspection data.

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

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

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

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

get button #useStock

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

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

set button [ #useStock := value ]

useUnderline

No description available in the introspection data.

constructButtonUseUnderline :: IsButton o => Bool -> IO (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 ]

xalign

If the child of the button is a Misc or Alignment, this property can be used to control its horizontal alignment. 0.0 is left aligned, 1.0 is right aligned.

Since: 2.4

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

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

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

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

get button #xalign

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

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

set button [ #xalign := value ]

yalign

If the child of the button is a Misc or Alignment, this property can be used to control its vertical alignment. 0.0 is top aligned, 1.0 is bottom aligned.

Since: 2.4

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

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

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

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

get button #yalign

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

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

set button [ #yalign := value ]

Signals

activate

type ButtonActivateCallback = IO () Source #

The ::activate signal on GtkButton 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 Button::clicked signal.

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

Type for the callback on the (unwrapped) C side.

afterButtonActivate :: (IsButton a, MonadIO m) => 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

onButtonActivate :: (IsButton a, MonadIO m) => 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).

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

Type for the callback on the (unwrapped) C side.

afterButtonClicked :: (IsButton a, MonadIO m) => 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

mk_ButtonClickedCallback :: C_ButtonClickedCallback -> IO (FunPtr C_ButtonClickedCallback) Source #

Generate a function pointer callable from C code, from a C_ButtonClickedCallback.

onButtonClicked :: (IsButton a, MonadIO m) => 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

enter

type ButtonEnterCallback = IO () Source #

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

Emitted when the pointer enters the button.

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

Type for the callback on the (unwrapped) C side.

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

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

after button #enter callback

mk_ButtonEnterCallback :: C_ButtonEnterCallback -> IO (FunPtr C_ButtonEnterCallback) Source #

Generate a function pointer callable from C code, from a C_ButtonEnterCallback.

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

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

on button #enter callback

leave

type ButtonLeaveCallback = IO () Source #

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

Emitted when the pointer leaves the button.

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

Type for the callback on the (unwrapped) C side.

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

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

after button #leave callback

mk_ButtonLeaveCallback :: C_ButtonLeaveCallback -> IO (FunPtr C_ButtonLeaveCallback) Source #

Generate a function pointer callable from C code, from a C_ButtonLeaveCallback.

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

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

on button #leave callback

pressed

type ButtonPressedCallback = IO () Source #

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

Emitted when the button is pressed.

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

Type for the callback on the (unwrapped) C side.

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

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

after button #pressed callback

mk_ButtonPressedCallback :: C_ButtonPressedCallback -> IO (FunPtr C_ButtonPressedCallback) Source #

Generate a function pointer callable from C code, from a C_ButtonPressedCallback.

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

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

on button #pressed callback

released

type ButtonReleasedCallback = IO () Source #

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

Emitted when the button is released.

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

Type for the callback on the (unwrapped) C side.

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

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

after button #released callback

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

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

on button #released callback