HildonButton

HildonButton — Two-label buttons in the Hildon framework.

Synopsis


#include <hildon/hildon.h>

                    HildonButton;
enum                HildonButtonArrangement;
enum                HildonButtonStyle;
GtkWidget*          hildon_button_new                   (HildonSizeType size,
                                                         HildonButtonArrangement arrangement);
GtkWidget*          hildon_button_new_with_text         (HildonSizeType size,
                                                         HildonButtonArrangement arrangement,
                                                         const gchar *title,
                                                         const gchar *value);
void                hildon_button_set_title             (HildonButton *button,
                                                         const gchar *title);
void                hildon_button_set_value             (HildonButton *button,
                                                         const gchar *value);
const gchar*        hildon_button_get_title             (HildonButton *button);
const gchar*        hildon_button_get_value             (HildonButton *button);
void                hildon_button_set_text              (HildonButton *button,
                                                         const gchar *title,
                                                         const gchar *value);
void                hildon_button_set_image             (HildonButton *button,
                                                         GtkWidget *image);
GtkWidget*          hildon_button_get_image             (HildonButton *button);
void                hildon_button_set_image_position    (HildonButton *button,
                                                         GtkPositionType position);
void                hildon_button_set_alignment         (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign,
                                                         gfloat xscale,
                                                         gfloat yscale);
void                hildon_button_set_title_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);
void                hildon_button_set_value_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);
void                hildon_button_set_image_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);
void                hildon_button_add_title_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);
void                hildon_button_add_value_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);
void                hildon_button_add_image_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);
void                hildon_button_add_size_groups       (HildonButton *button,
                                                         GtkSizeGroup *title_size_group,
                                                         GtkSizeGroup *value_size_group,
                                                         GtkSizeGroup *image_size_group);
void                hildon_button_set_style             (HildonButton *button,
                                                         HildonButtonStyle style);
HildonButtonStyle   hildon_button_get_style             (HildonButton *button);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkButton
                                       +----HildonButton
                                             +----HildonPickerButton

Implemented Interfaces

HildonButton implements AtkImplementorIface and GtkBuildable.

Properties

  "arrangement"              HildonButtonArrangement  : Write / Construct Only
  "size"                     HildonSizeType        : Write / Construct Only
  "style"                    HildonButtonStyle     : Read / Write
  "title"                    gchar*                : Read / Write
  "value"                    gchar*                : Read / Write

Style Properties

  "horizontal-spacing"       guint                 : Read
  "vertical-spacing"         guint                 : Read

Description

HildonButton is a clickable button for Hildon applications. It is derived from the GtkButton widget and provides additional commodities specific to the Hildon framework.

The height of a HildonButton can be set to either "finger" height or "thumb" height. It can also be configured to use halfscreen or fullscreen width. Alternatively, either dimension can be set to "auto" so it behaves like a standard GtkButton.

A HildonButton can hold any valid child widget, but it usually contains two labels, named title and value, and it can also contain an image. The contents of the button are packed together inside a GtkAlignment and they do not expand by default (they don't use the full space of the button).

To change the alignment of both labels, use gtk_button_set_alignment()

To make them expand and use the full space of the button, use hildon_button_set_alignment().

To change the relative alignment of each label, use hildon_button_set_title_alignment() and hildon_button_set_value_alignment().

In hildon-button-example.c included in the Hildon distribution you can see examples of how to create the most common button layouts.

If only one label is needed, GtkButton can be used as well, see also hildon_gtk_button_new().

Example 5. Creating a HildonButton

void
button_clicked (HildonButton *button, gpointer user_data)
{
    const gchar *title, *value;

    title = hildon_button_get_title (button);
    value = hildon_button_get_value (button);
    g_debug ("Button clicked with title '%s' and value '%s'", title, value);
}

GtkWidget *
create_button (void)
{
    GtkWidget *button;
    GtkWidget *image;

    button = hildon_button_new (HILDON_SIZE_AUTO_WIDTH | HILDON_SIZE_FINGER_HEIGHT,
                                HILDON_BUTTON_ARRANGEMENT_VERTICAL);
    hildon_button_set_text (HILDON_BUTTON (button), "Some title", "Some value");

    image = gtk_image_new_from_stock (GTK_STOCK_INFO, GTK_ICON_SIZE_BUTTON);
    hildon_button_set_image (HILDON_BUTTON (button), image);
    hildon_button_set_image_position (HILDON_BUTTON (button), GTK_POS_RIGHT);

    gtk_button_set_alignment (GTK_BUTTON (button), 0.0, 0.5);

    g_signal_connect (button, "clicked", G_CALLBACK (button_clicked), NULL);

    return button;
}


Details

HildonButton

typedef struct _HildonButton HildonButton;

enum HildonButtonArrangement

typedef enum {
   HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
   HILDON_BUTTON_ARRANGEMENT_VERTICAL
}                                               HildonButtonArrangement;

Describes the arrangement of labels inside a HildonButton

HILDON_BUTTON_ARRANGEMENT_HORIZONTAL Labels are arranged from left to right
HILDON_BUTTON_ARRANGEMENT_VERTICAL Labels are arranged from top to bottom

enum HildonButtonStyle

typedef enum {
   HILDON_BUTTON_STYLE_NORMAL,
   HILDON_BUTTON_STYLE_PICKER
}                                               HildonButtonStyle;

Describes the visual style of a HildonButton

HILDON_BUTTON_STYLE_NORMAL The button will look like a normal HildonButton
HILDON_BUTTON_STYLE_PICKER The button will look like a HildonPickerButton

hildon_button_new ()

GtkWidget*          hildon_button_new                   (HildonSizeType size,
                                                         HildonButtonArrangement arrangement);

Creates a new HildonButton. To set text in the labels, use hildon_button_set_title() and hildon_button_set_value(). Alternatively, you can add a custom child widget using gtk_container_add().

size : Flags to set the size of the button.
arrangement : How the labels must be arranged.
Returns : a new HildonButton

Since 2.2

hildon_button_new_with_text ()

GtkWidget*          hildon_button_new_with_text         (HildonSizeType size,
                                                         HildonButtonArrangement arrangement,
                                                         const gchar *title,
                                                         const gchar *value);

Creates a new HildonButton with two labels, title and value.

If you just don't want to use one of the labels, set it to NULL. You can set it to a non-NULL value at any time later using hildon_button_set_title() or hildon_button_set_value() .

size : Flags to set the size of the button.
arrangement : How the labels must be arranged.
title : Title of the button (main label), or NULL
value : Value of the button (secondary label), or NULL
Returns : a new HildonButton

Since 2.2

hildon_button_set_title ()

void                hildon_button_set_title             (HildonButton *button,
                                                         const gchar *title);

Sets the title (main label) of button to title.

This will clear any previously set title.

If title is set to NULL or an empty string, the title label will be hidden and the value label will be realigned.

button : a HildonButton
title : a new title (main label) for the button, or NULL

Since 2.2

hildon_button_set_value ()

void                hildon_button_set_value             (HildonButton *button,
                                                         const gchar *value);

Sets the value (secondary label) of button to value.

This will clear any previously set value.

If value is set to NULL or an empty string, the value label will be hidden and the title label will be realigned.

button : a HildonButton
value : a new value (secondary label) for the button, or NULL

Since 2.2

hildon_button_get_title ()

const gchar*        hildon_button_get_title             (HildonButton *button);

Fetches the text from the main label (title) of button, as set by hildon_button_set_title() or hildon_button_set_text(). If the label text has not been set the return value will be NULL. This will be the case if you create an empty button with hildon_button_new() to use as a container.

button : a HildonButton
Returns : The text of the title label. This string is owned by the widget and must not be modified or freed.

Since 2.2

hildon_button_get_value ()

const gchar*        hildon_button_get_value             (HildonButton *button);

Fetches the text from the secondary label (value) of button, as set by hildon_button_set_value() or hildon_button_set_text(). If the label text has not been set the return value will be NULL. This will be the case if you create an empty button with hildon_button_new() to use as a container.

button : a HildonButton
Returns : The text of the value label. This string is owned by the widget and must not be modified or freed.

Since 2.2

hildon_button_set_text ()

void                hildon_button_set_text              (HildonButton *button,
                                                         const gchar *title,
                                                         const gchar *value);

Convenience function to change both labels of a HildonButton

button : a HildonButton
title : new text for the button title (main label)
value : new text for the button value (secondary label)

Since 2.2

hildon_button_set_image ()

void                hildon_button_set_image             (HildonButton *button,
                                                         GtkWidget *image);

Sets the image of button to the given widget. The previous image (if any) will be removed.

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

Since 2.2

hildon_button_get_image ()

GtkWidget*          hildon_button_get_image             (HildonButton *button);

Gets the widget that is currenty set as the image of button, previously set with hildon_button_set_image()

button : a HildonButton
Returns : a GtkWidget or NULL in case there is no image

Since 2.2

hildon_button_set_image_position ()

void                hildon_button_set_image_position    (HildonButton *button,
                                                         GtkPositionType position);

Sets the position of the image inside button. Only GTK_POS_LEFT and GTK_POS_RIGHT are currently supported.

button : a HildonButton
position : the position of the image (GTK_POS_LEFT or GTK_POS_RIGHT)

Since 2.2

hildon_button_set_alignment ()

void                hildon_button_set_alignment         (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign,
                                                         gfloat xscale,
                                                         gfloat yscale);

Sets the alignment of the contents of the widget. If you don't need to change xscale or yscale you can just use gtk_button_set_alignment() instead.

Note that for this method to work properly, the child widget of button must be a GtkAlignment. That's what HildonButton uses by default, so this function will work unless you add a custom widget to button.

button : a HildonButton
xalign : the horizontal alignment of the contents, from 0 (left) to 1 (right).
yalign : the vertical alignment of the contents, from 0 (top) to 1 (bottom).
xscale : the amount that the child widget expands horizontally to fill up unused space, from 0 to 1
yscale : the amount that the child widget expands vertically to fill up unused space, from 0 to 1

Since 2.2

hildon_button_set_title_alignment ()

void                hildon_button_set_title_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);

Sets the alignment of the title label. See also hildon_button_set_alignment() to set the alignment of the whole contents of the button.

button : a HildonButton
xalign : the horizontal alignment of the title label, from 0 (left) to 1 (right).
yalign : the vertical alignment of the title label, from 0 (top) to 1 (bottom).

Since 2.2

hildon_button_set_value_alignment ()

void                hildon_button_set_value_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);

Sets the alignment of the value label. See also hildon_button_set_alignment() to set the alignment of the whole contents of the button.

button : a HildonButton
xalign : the horizontal alignment of the value label, from 0 (left) to 1 (right).
yalign : the vertical alignment of the value label, from 0 (top) to 1 (bottom).

Since 2.2

hildon_button_set_image_alignment ()

void                hildon_button_set_image_alignment   (HildonButton *button,
                                                         gfloat xalign,
                                                         gfloat yalign);

Sets the alignment of the image. See also hildon_button_set_alignment() to set the alignment of the whole contents of the button.

button : a HildonButton
xalign : the horizontal alignment of the image, from 0 (left) to 1 (right).
yalign : the vertical alignment of the image, from 0 (top) to 1 (bottom).

Since 2.2

hildon_button_add_title_size_group ()

void                hildon_button_add_title_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);

Adds the title label of button to size_group.

button : a HildonButton
size_group : A GtkSizeGroup for the button title (main label)

Since 2.2

hildon_button_add_value_size_group ()

void                hildon_button_add_value_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);

Adds the value label of button to size_group.

button : a HildonButton
size_group : A GtkSizeGroup for the button value (secondary label)

Since 2.2

hildon_button_add_image_size_group ()

void                hildon_button_add_image_size_group  (HildonButton *button,
                                                         GtkSizeGroup *size_group);

Adds the image of button to size_group. You must add an image using hildon_button_set_image() before calling this function.

button : a HildonButton
size_group : A GtkSizeGroup for the button image

Since 2.2

hildon_button_add_size_groups ()

void                hildon_button_add_size_groups       (HildonButton *button,
                                                         GtkSizeGroup *title_size_group,
                                                         GtkSizeGroup *value_size_group,
                                                         GtkSizeGroup *image_size_group);

Convenience function to add title, value and image to size groups. NULL size groups will be ignored.

button : a HildonButton
title_size_group : A GtkSizeGroup for the button title (main label), or NULL
value_size_group : A GtkSizeGroup group for the button value (secondary label), or NULL
image_size_group : A GtkSizeGroup group for the button image, or NULL

Since 2.2

hildon_button_set_style ()

void                hildon_button_set_style             (HildonButton *button,
                                                         HildonButtonStyle style);

Sets the style of button to style. This changes the visual appearance of the button (colors, font sizes) according to the particular style chosen, but the general layout is not altered.

Use HILDON_BUTTON_STYLE_NORMAL to make it look like a normal HildonButton, or HILDON_BUTTON_STYLE_PICKER to make it look like a HildonPickerButton.

button : A HildonButton
style : A HildonButtonStyle for button

Since 2.2

hildon_button_get_style ()

HildonButtonStyle   hildon_button_get_style             (HildonButton *button);

Gets the visual style of the button.

button : A HildonButton
Returns : a HildonButtonStyle

Since 2.2

Property Details

The "arrangement" property

  "arrangement"              HildonButtonArrangement  : Write / Construct Only

How the button contents must be arranged.

Default value: HILDON_BUTTON_ARRANGEMENT_HORIZONTAL

The "size" property

  "size"                     HildonSizeType        : Write / Construct Only

Size request for the button.

The "style" property

  "style"                    HildonButtonStyle     : Read / Write

Visual style of the button.

Default value: HILDON_BUTTON_STYLE_NORMAL

The "title" property

  "title"                    gchar*                : Read / Write

Text of the title label inside the button.

Default value: NULL

The "value" property

  "value"                    gchar*                : Read / Write

Text of the value label inside the button.

Default value: NULL

Style Property Details

The "horizontal-spacing" style property

  "horizontal-spacing"       guint                 : Read

Horizontal spacing between the title and value labels, when in horizontal mode.

Default value: 25

The "vertical-spacing" style property

  "vertical-spacing"         guint                 : Read

Vertical spacing between the title and value labels, when in vertical mode.

Default value: 5

Generated by GTK-Doc V1.10