StButton: St Reference Manual

## 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 ()
const char * | st_button_get_icon_name ()
void | st_button_set_icon_name ()
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 ()
#define | ST_BUTTON_MASK_FROM_BUTTON()
void | st_button_set_button_mask ()
StButtonMask | st_button_get_button_mask ()

## Types and Values

#define | ST_TYPE_BUTTON
struct | StButtonClass
enum | StButtonMask
| StButton

## 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. If the label is empty, an empty string will be returned instead of `NULL`.

#### Parameters

button | a StButton |

#### Returns

the text for the button.

[transfer none]

### 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. | [nullable]

### st_button_get_icon_name ()

    const char *
    st_button_get_icon_name (StButton *button);

Get the icon name of the button. If the button isn't showing an icon, the return value will be `NULL`.

#### Parameters

button | a StButton |

#### Returns

the icon name of the button.

[transfer none][nullable]

### st_button_set_icon_name ()

    void
    st_button_set_icon_name (StButton *button,
                             const char *icon_name);

Adds an `StIcon` with the given icon name as a child.

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

#### Parameters

button | a Stbutton |
icon_name | an icon name |

### 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 checked 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);

Set the “checked” property of the button. This is only really useful if the button has “toggle-mode” property set to `TRUE`.

#### Parameters

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

### st_button_get_checked ()

    gboolean
    st_button_get_checked (StButton *button);

Get the “checked” property of a StButton 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_MASK_FROM_BUTTON()

    #define ST_BUTTON_MASK_FROM_BUTTON(button) (1 << ((button) - 1))

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

### ST_TYPE_BUTTON

    #define ST_TYPE_BUTTON (st_button_get_type ())

### struct StButtonClass

    struct StButtonClass {
      StBinClass parent_class;

      /* vfuncs, not signals */
      void (* transition) (StButton     *button);

      /* signals */
      void (* clicked) (StButton *button, int clicked_button);
    };

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

### StButton

    typedef struct _StButton StButton;