St Reference Manual: StButton

## StButton StButton — Button widget |

## Functions

StWidget * | st_button_new ()
StWidget * | st_button_new_with_label ()
const gchar * | st_button_get_label ()
void | st_button_set_label ()
void | st_button_set_toggle_mode ()
gboolean | st_button_get_toggle_mode ()
void | st_button_set_checked ()
gboolean | st_button_get_checked ()
void | st_button_fake_release ()
void | st_button_set_button_mask ()
StButtonMask | st_button_get_button_mask ()

## Properties

StButtonMask | button-mask | Read / Write
gboolean | checked | Read / Write
gchar * | label | Read / Write
gboolean | pressed | Read
gboolean | toggle-mode | Read / Write

## Signals

void | clicked | Run Last

## Types and Values

struct | StButton
enum | StButtonMask

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── StWidget
                    ╰── StBin
                        ╰── StButton

## Implemented Interfaces

StButton implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Description

A button widget with support for either a text label or icon, toggle mode and transitions effects between states.

## Functions

### st_button_new ()

    StWidget *
    st_button_new (void);

Create a new button

#### Returns

a new StButton

### st_button_new_with_label ()

    StWidget *
    st_button_new_with_label (const gchar *text);

Create a new StButton with the specified label

#### Parameters

text | text to set the label to |

#### Returns

a new StButton

### st_button_get_label ()

    const gchar *
    st_button_get_label (StButton *button);

Get the text displayed on the button

#### Parameters

button | a StButton |

#### Returns

the text for the button. This must not be freed by the application

### st_button_set_label ()

    void
    st_button_set_label (StButton *button,
                         const gchar *text);

Sets the text displayed on the button

#### Parameters

button | a Stbutton |
text | text to set the label to |

### st_button_set_toggle_mode ()

    void
    st_button_set_toggle_mode (StButton *button,
                               gboolean toggle);

Enables or disables toggle mode for the button. In toggle mode, the active state will be "toggled" when the user clicks the button.

#### Parameters

button | a Stbutton |
toggle | `TRUE` or `FALSE` |

### st_button_get_toggle_mode ()

    gboolean
    st_button_get_toggle_mode (StButton *button);

Get the toggle mode status of the button.

#### Parameters

button | a StButton |

#### Returns

`TRUE` if toggle mode is set, otherwise `FALSE`

### st_button_set_checked ()

    void
    st_button_set_checked (StButton *button,
                           gboolean checked);

Sets the pressed state of the button. This is only really useful if the button has toggle-mode mode set to `TRUE`.

#### Parameters

button | a Stbutton |
checked | `TRUE` or `FALSE` |

### st_button_get_checked ()

    gboolean
    st_button_get_checked (StButton *button);

Get the state of the button that is in toggle mode.

#### Parameters

button | a StButton |

#### Returns

`TRUE` if the button is checked, or `FALSE` if not

### st_button_fake_release ()

    void
    st_button_fake_release (StButton *button);

If this widget is holding a pointer grab, this function will will ungrab it, and reset the pressed state. The effect is similar to if the user had released the mouse button, but without emitting the clicked signal.

This function is useful if for example you want to do something after the user is holding the mouse button for a given period of time, breaking the grab.

#### Parameters

button | an StButton |

### st_button_set_button_mask ()

    void
    st_button_set_button_mask (StButton *button,
                               StButtonMask mask);

Sets which mouse buttons `button` emits “clicked” for.

#### Parameters

button | a Stbutton |
mask | the mask of mouse buttons that `button` responds to |

### st_button_get_button_mask ()

    StButtonMask
    st_button_get_button_mask (StButton *button);

Gets the mask of mouse buttons that `button` emits the “clicked” signal for.

#### Parameters

button | a StButton |

#### Returns

the mask of mouse buttons that `button` emits the “clicked” signal for.

## Types and Values

### struct StButton

    struct StButton;

The contents of this structure is private and should only be accessed using the provided API.

### enum StButtonMask

A mask representing which mouse buttons an StButton responds to.

#### Members

ST_BUTTON_ONE | button 1 (left) |
ST_BUTTON_TWO | button 2 (middle) |
ST_BUTTON_THREE | button 3 (right) |

## Property Details

### The `“button-mask”` property

      “button-mask”              StButtonMask

Which buttons trigger the 'clicked' signal.

Flags: Read / Write

Default value: ST_BUTTON_ONE

### The `“checked”` property

      “checked”                  gboolean

Indicates if a toggle button is "on" or "off".

Flags: Read / Write

Default value: FALSE

### The `“label”` property

      “label”                    gchar *

Label of the button.

Flags: Read / Write

Default value: NULL

### The `“pressed”` property

      “pressed”                  gboolean

Indicates if the button is pressed in.

Flags: Read

Default value: FALSE

### The `“toggle-mode”` property

      “toggle-mode”              gboolean

Enable or disable toggling.

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“clicked”` signal

    void
    user_function (StButton *button,
                   gint      clicked_button,
                   gpointer  user_data)

Emitted when the user activates the button, either with a mouse press and release or with the keyboard.

#### Parameters

button | the object that received the signal |
clicked_button | the mouse button that was used |
user_data | user data set when the signal handler was connected. |

Flags: Run Last