![]() |
![]() |
![]() |
Hildon Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBin +----GtkButton +----HildonButton +----HildonPickerButton
"arrangement" HildonButtonArrangement : Write / Construct Only "size" HildonSizeType : Write / Construct Only "style" HildonButtonStyle : Read / Write "title" gchar* : Read / Write "value" gchar* : Read / Write
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; }
typedef enum { HILDON_BUTTON_ARRANGEMENT_HORIZONTAL, HILDON_BUTTON_ARRANGEMENT_VERTICAL } HildonButtonArrangement;
Describes the arrangement of labels inside a HildonButton
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 |
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
HildonButtonStyle hildon_button_get_style (HildonButton *button);
Gets the visual style of the button.
button : |
A HildonButton |
Returns : | a HildonButtonStyle |
Since 2.2
"arrangement"
property"arrangement" HildonButtonArrangement : Write / Construct Only
How the button contents must be arranged.
Default value: HILDON_BUTTON_ARRANGEMENT_HORIZONTAL
"style"
property"style" HildonButtonStyle : Read / Write
Visual style of the button.
Default value: HILDON_BUTTON_STYLE_NORMAL
"title"
property"title" gchar* : Read / Write
Text of the title label inside the button.
Default value: NULL
"value"
property"value" gchar* : Read / Write
Text of the value label inside the button.
Default value: NULL
"horizontal-spacing"
style property"horizontal-spacing" guint : Read
Horizontal spacing between the title and value labels, when in horizontal mode.
Default value: 25
"vertical-spacing"
style property"vertical-spacing" guint : Read
Vertical spacing between the title and value labels, when in vertical mode.
Default value: 5