## MxButton MxButton — Button widget |

## Synopsis

    struct              MxButton;
    struct              MxButtonClass;
    ClutterActor *      mx_button_new                       (void);
    ClutterActor *      mx_button_new_with_label            (const gchar *text);
    const gchar *       mx_button_get_label                 (MxButton *button);
    void                mx_button_set_label                 (MxButton *button,
                                                             const gchar *text);
    const gchar *       mx_button_get_icon_name             (MxButton *button);
    void                mx_button_set_icon_name             (MxButton *button,
                                                             const gchar *icon_name);
    guint               mx_button_get_icon_size             (MxButton *button);
    void                mx_button_set_icon_size             (MxButton *button,
                                                             guint icon_size);
    void                mx_button_set_is_toggle             (MxButton *button,
                                                             gboolean toggle);
    gboolean            mx_button_get_is_toggle             (MxButton *button);
    void                mx_button_set_toggled               (MxButton *button,
                                                             gboolean toggled);
    gboolean            mx_button_get_toggled               (MxButton *button);
    void                mx_button_set_action                (MxButton *button,
                                                             MxAction *action);
    MxAction *          mx_button_get_action                (MxButton *button);
    void                mx_button_set_icon_position         (MxButton *button,
                                                             MxPosition position);
    MxPosition          mx_button_get_icon_position         (MxButton *button);
    void                mx_button_set_icon_visible          (MxButton *button,
                                                             gboolean visible);
    gboolean            mx_button_get_icon_visible          (MxButton *button);
    void                mx_button_set_label_visible         (MxButton *button,
                                                             gboolean visible);
    gboolean            mx_button_get_label_visible         (MxButton *button);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----MxWidget
                         +----MxBin
                               +----MxButton

## Implemented Interfaces

MxButton implements ClutterScriptable, ClutterAnimatable, AtkImplementorIface, MxStylable, ClutterContainer and MxFocusable.

## Properties

      "action"                   MxAction*             : Read / Write
      "icon-name"                gchar*                : Read / Write
      "icon-position"            MxPosition            : Read / Write
      "icon-size"                guint                 : Read / Write
      "icon-visible"             gboolean              : Read / Write
      "is-toggle"                gboolean              : Read / Write
      "label"                    gchar*                : Read / Write
      "label-visible"            gboolean              : Read / Write
      "toggled"                  gboolean              : Read / Write

## Signals

      "clicked"                                        : Run Last

## Description

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

## Details

### struct MxButton

    struct MxButton;

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

### struct MxButtonClass

    struct MxButtonClass {
      MxBinClass parent_class;

      /* signals */
      void     (* clicked)    (MxButton          *button);

      /* padding for future expansion */
      void (*_padding_0) (void);
      void (*_padding_1) (void);
      void (*_padding_2) (void);
      void (*_padding_3) (void);
      void (*_padding_4) (void);
    };

### mx_button_new ()

    ClutterActor *      mx_button_new                       (void);

Create a new button

Returns : | a new MxButton

### mx_button_new_with_label ()

    ClutterActor *      mx_button_new_with_label            (const gchar *text);

Create a new MxButton with the specified label

`text` : | text to set the label to
Returns : | a new MxButton

### mx_button_get_label ()

    const gchar *       mx_button_get_label                 (MxButton *button);

Get the text displayed on the button

`button` : | a MxButton
Returns : | the text for the button. This must not be freed by the application

### mx_button_set_label ()

    void                mx_button_set_label                 (MxButton *button,
                                                             const gchar *text);

Sets the text displayed on the button

`button` : | a MxButton
`text` : | text to set the label to

### mx_button_get_icon_name ()

    const gchar *       mx_button_get_icon_name             (MxButton *button);

Get the icon-name being used on the button.

`button` : | a MxButton
Returns : | the icon-name. This must not be freed by the application. `NULL` if no icon has been set

Since 1.2

### mx_button_set_icon_name ()

    void                mx_button_set_icon_name             (MxButton *button,
                                                             const gchar *icon_name);

Sets the icon-name used to display an icon on the button. Setting `NULL` will remove the icon name, or resort to the icon-name set in the current style. Setting an icon name overrides any icon set in the style.

`button` : | a MxButton
`icon_name` : | icon-name to use on the button. [allow-none]

Since 1.2

### mx_button_get_icon_size ()

    guint               mx_button_get_icon_size             (MxButton *button);

Retrieves the icon-size being used for the displayed icon inside the button.

`button` : | a MxButton
Returns : | The icon-size being used for the button icon, in pixels

Since 1.2

### mx_button_set_icon_size ()

    void                mx_button_set_icon_size             (MxButton *button,
                                                             guint icon_size);

Sets the icon-size to use for the icon displayed inside the button. This will override the icon-size set in the style. Setting a value of `0` resets to the size from the style.

`button` : | a MxButton

Since 1.2

### mx_button_set_is_toggle ()

    void                mx_button_set_is_toggle             (MxButton *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.

`button` : | a MxButton
`toggle` : | TRUE or FALSE

### mx_button_get_is_toggle ()

    gboolean            mx_button_get_is_toggle             (MxButton *button);

Get the toggle mode status of the button.

`button` : | a MxButton
Returns : | TRUE if toggle mode is set, otherwise FALSE

### mx_button_set_toggled ()

    void                mx_button_set_toggled               (MxButton *button,
                                                             gboolean toggled);

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

`button` : | a MxButton
`toggled` : | TRUE or FALSE

### mx_button_get_toggled ()

    gboolean            mx_button_get_toggled               (MxButton *button);

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

`button` : | a MxButton
Returns : | TRUE if the button is toggled, or FALSE if not

### mx_button_set_action ()

    void                mx_button_set_action                (MxButton *button,
                                                             MxAction *action);

Sets `action` as the action for `button`. `Button` will take its label and icon from `action`.

`button` : | A MxButton
`action` : | A MxAction

Since 1.2

### mx_button_get_action ()

    MxAction *          mx_button_get_action                (MxButton *button);

Retrieves the MxAction associated with `button`.

`button` : | A MxButton
Returns : | A MxAction. [transfer none]

Since 1.2

### mx_button_set_icon_position ()

    void                mx_button_set_icon_position         (MxButton *button,
                                                             MxPosition position);

Sets the icon position, relative to the text on the button.

`button` : | A MxButton
`position` : | A MxPosition

Since 1.2

### mx_button_get_icon_position ()

    MxPosition          mx_button_get_icon_position         (MxButton *button);

Retrieves the icon's relative position to the text.

`button` : | A MxButton
Returns : | A MxPosition

Since 1.2

### mx_button_set_icon_visible ()

    void                mx_button_set_icon_visible          (MxButton *button,
                                                             gboolean visible);

Sets the visibility of the icon associated with the button's action.

`button` : | A MxButton
`visible` : | `TRUE` if the icon should be visible

Since 1.2

### mx_button_get_icon_visible ()

    gboolean            mx_button_get_icon_visible          (MxButton *button);

Retrieves the visibility of the icon associated with the button's action.

`button` : | A MxButton
Returns : | `TRUE` if the icon is visible, `FALSE` otherwise

Since 1.2

### mx_button_set_label_visible ()

    void                mx_button_set_label_visible         (MxButton *button,
                                                             gboolean visible);

Sets the visibility of the text associated with the button's action.

`button` : | A MxButton
`visible` : | `TRUE` if the text should be visible

Since 1.2

### mx_button_get_label_visible ()

    gboolean            mx_button_get_label_visible         (MxButton *button);

Retrieves the visibility of the text associated with the button's action.

`button` : | A MxButton
Returns : | `TRUE` if the text is visible, `FALSE` otherwise

Since 1.2

## Property Details

### The `"action"` property

      "action"                   MxAction*             : Read / Write

Associated action.

### The `"icon-name"` property

      "icon-name"                gchar*                : Read / Write

Icon name of the button.

Default value: NULL

### The `"icon-position"` property

      "icon-position"            MxPosition            : Read / Write

The position of the icon, relative to the text.

Default value: MX_POSITION_LEFT

### The `"icon-size"` property

      "icon-size"                guint                 : Read / Write

The size to use for the button icon (in pixels).

Default value: 0

### The `"icon-visible"` property

      "icon-visible"             gboolean              : Read / Write

Whether to show the icon.

Default value: TRUE

### The `"is-toggle"` property

      "is-toggle"                gboolean              : Read / Write

Enable or disable toggling.

Default value: FALSE

### The `"label"` property

      "label"                    gchar*                : Read / Write

Label of the button.

Default value: NULL

### The `"label-visible"` property

      "label-visible"            gboolean              : Read / Write

Whether to show the label.

Default value: TRUE

### The `"toggled"` property

      "toggled"                  gboolean              : Read / Write

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

Default value: FALSE

## Signal Details

### The `"clicked"` signal

    void                user_function                      (MxButton *button,
                                                            gpointer  user_data)      : Run Last

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

`button` : | the object that received the signal
`user_data` : | user data set when the signal handler was connected.