* SECTION:hildon-button
* @short_description: Widget representing a button in the Hildon framework.
*
- * The HildonButton is a GTK widget which represent a clickable
+ * The #HildonButton is a GTK widget which represents a clickable
* button. 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.
+ *
+ * The #HildonButton can hold any valid child widget, but it usually
+ * contains two labels: title and value (the latter being
+ * optional). To change the alignment of the labels, use
+ * gtk_button_set_alignment()
*/
#include "hildon-button.h"
+#include "hildon-enum-types.h"
#define FINGER_BUTTON_HEIGHT 70
#define THUMB_BUTTON_HEIGHT 105
{
GtkLabel *title;
GtkLabel *value;
+ GtkWidget *alignment;
};
enum {
PROP_TITLE = 1,
PROP_VALUE,
- PROP_ARRANGEMENT_FLAGS
+ PROP_SIZE_FLAGS,
+ PROP_ARRANGEMENT
};
-static void hildon_button_set_arrangement (HildonButton *button, HildonButtonFlags flags);
+static void
+hildon_button_set_arrangement (HildonButton *button,
+ HildonButtonArrangement arrangement);
+
+static void
+hildon_button_construct_child (HildonButton *button);
static void
hildon_button_set_property (GObject *object,
case PROP_VALUE:
hildon_button_set_value (button, g_value_get_string (value));
break;
- case PROP_ARRANGEMENT_FLAGS:
- hildon_button_set_arrangement (button, g_value_get_int (value));
+ case PROP_SIZE_FLAGS:
+ hildon_helper_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
+ break;
+ case PROP_ARRANGEMENT:
+ hildon_button_set_arrangement (button, g_value_get_enum (value));
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
g_object_class_install_property (
- gobject_class,
- PROP_ARRANGEMENT_FLAGS,
- g_param_spec_int ("arrangement-flags",
- "Arrangement flags",
- "How the button contents must be arranged",
- 0, 64,
- HILDON_BUTTON_WITH_HORIZONTAL_VALUE,
- G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
+ gobject_class,
+ PROP_SIZE_FLAGS,
+ g_param_spec_flags (
+ "size-flags",
+ "Size flags",
+ "Size request for the button",
+ HILDON_TYPE_SIZE_TYPE,
+ HILDON_SIZE_AUTO,
+ G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
+
+ g_object_class_install_property (
+ gobject_class,
+ PROP_ARRANGEMENT,
+ g_param_spec_enum (
+ "arrangement",
+ "Arrangement",
+ "How the button contents must be arranged",
+ HILDON_TYPE_BUTTON_ARRANGEMENT,
+ HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
+ G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
gtk_widget_class_install_style_property (
widget_class,
priv->title = GTK_LABEL (gtk_label_new (NULL));
priv->value = GTK_LABEL (gtk_label_new (NULL));
+ priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
+
+ /* The value label is not shown automatically, see hildon_button_set_value() */
+ gtk_widget_set_no_show_all (GTK_WIDGET (priv->value), TRUE);
}
+/**
+ * hildon_button_set_size_groups:
+ * @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
+ *
+ * Adds the title and value labels of @button to @title_size_group and
+ * @value_size_group respectively. %NULL size groups will be ignored.
+ **/
void
hildon_button_set_size_groups (HildonButton *button,
GtkSizeGroup *title_size_group,
HildonButtonPrivate *priv;
g_return_if_fail (HILDON_IS_BUTTON (button));
+ g_return_if_fail (!title_size_group || GTK_IS_SIZE_GROUP (title_size_group));
+ g_return_if_fail (!value_size_group || GTK_IS_SIZE_GROUP (value_size_group));
priv = HILDON_BUTTON_GET_PRIVATE (button);
gtk_size_group_add_widget (value_size_group, GTK_WIDGET (priv->value));
}
+/**
+ * hildon_button_new:
+ * @size: Flags to set the size of the button.
+ * @arrangement: How the labels must be arranged.
+ *
+ * Creates a new #HildonButton. To add a child widget use gtk_container_add().
+ *
+ * Returns: a new #HildonButton
+ **/
+GtkWidget *
+hildon_button_new (HildonSizeType size,
+ HildonButtonArrangement arrangement)
+{
+ return hildon_button_new_full (size, arrangement, NULL, NULL, NULL, NULL);
+}
+
+/**
+ * hildon_button_new_with_text:
+ * @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
+ *
+ * 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.
+ *
+ * Returns: a new #HildonButton
+ **/
GtkWidget *
-hildon_button_new (HildonButtonFlags flags,
- const char *title,
- const char *value)
+hildon_button_new_with_text (HildonSizeType size,
+ HildonButtonArrangement arrangement,
+ const gchar *title,
+ const gchar *value)
{
- return hildon_button_new_full (flags, title, value, NULL, NULL);
+ return hildon_button_new_full (size, arrangement, title, value, NULL, NULL);
}
+/**
+ * hildon_button_new_full:
+ * @size: Flags to set the size of the button.
+ * @arrangement: How the labels must be arranged.
+ * @title: Title of the button (main label)
+ * @value: Value of the button (secondary label), or %NULL
+ * @title_size_group: a #GtkSizeGroup for the @title label, or %NULL
+ * @value_size_group: a #GtkSizeGroup for the @value label, or %NULL
+ *
+ * Creates a new #HildonButton with two labels, @title and @value, and
+ * their respective size groups.
+ *
+ * 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.
+ *
+ * @title and @value will be added to @title_size_group and
+ * @value_size_group, respectively, if present.
+ *
+ * Returns: a new #HildonButton
+ **/
GtkWidget *
-hildon_button_new_full (HildonButtonFlags flags,
- const char *title,
- const char *value,
- GtkSizeGroup *title_size_group,
- GtkSizeGroup *value_size_group)
+hildon_button_new_full (HildonSizeType size,
+ HildonButtonArrangement arrangement,
+ const gchar *title,
+ const gchar *value,
+ GtkSizeGroup *title_size_group,
+ GtkSizeGroup *value_size_group)
{
GtkWidget *button;
/* Create widget */
button = g_object_new (HILDON_TYPE_BUTTON,
- "arrangement-flags", flags,
+ "size-flags", size,
+ "arrangement", arrangement,
"title", title,
"value", value,
"name", "hildon-button",
}
static void
-hildon_button_set_arrangement (HildonButton *button,
- HildonButtonFlags flags)
+hildon_button_set_arrangement (HildonButton *button,
+ HildonButtonArrangement arrangement)
{
GtkWidget *box;
- GtkWidget *alignment;
HildonButtonPrivate *priv;
guint horizontal_spacing;
guint vertical_spacing;
- gint width = -1;
- gint height = -1;
- const char *widget_name = NULL;
priv = HILDON_BUTTON_GET_PRIVATE (button);
- /* Requested height */
- if (flags & HILDON_BUTTON_FINGER_HEIGHT) {
- height = FINGER_BUTTON_HEIGHT;
- widget_name = "hildon-finger-button";
- } else if (flags & HILDON_BUTTON_THUMB_HEIGHT) {
- height = THUMB_BUTTON_HEIGHT;
- widget_name = "hildon-thumb-button";
- }
-
- if (widget_name) {
- gtk_widget_set_name (GTK_WIDGET (button), widget_name);
- }
-
- /* Requested width */
- if (flags & HILDON_BUTTON_HALFSCREEN_WIDTH) {
- width = HALFSCREEN_BUTTON_WIDTH;
- } else if (flags & HILDON_BUTTON_FULLSCREEN_WIDTH) {
- width = FULLSCREEN_BUTTON_WIDTH;
- }
-
- g_object_set (button,
- "width-request", width,
- "height-request", height,
- NULL);
-
/* Pack everything */
gtk_widget_style_get (GTK_WIDGET (button),
"horizontal-spacing", &horizontal_spacing,
"vertical-spacing", &vertical_spacing,
NULL);
- if (flags & HILDON_BUTTON_WITH_VERTICAL_VALUE) {
+ if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
box = gtk_vbox_new (FALSE, vertical_spacing);
} else {
box = gtk_hbox_new (FALSE, horizontal_spacing);
}
- alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
-
gtk_box_pack_start (GTK_BOX (box), GTK_WIDGET (priv->title), TRUE, TRUE, 0);
gtk_box_pack_start (GTK_BOX (box), GTK_WIDGET (priv->value), TRUE, TRUE, 0);
- gtk_container_add (GTK_CONTAINER (alignment), box);
- gtk_container_add (GTK_CONTAINER (button), alignment);
-
- gtk_widget_show_all (alignment);
+ gtk_container_add (GTK_CONTAINER (priv->alignment), box);
}
+/**
+ * hildon_button_set_title:
+ * @button: a #HildonButton
+ * @title: a new title (main label) for the button.
+ *
+ * Sets the title (main label) of @button to @title.
+ *
+ * This will clear the previously set title.
+ **/
void
hildon_button_set_title (HildonButton *button,
- const char *title)
+ const gchar *title)
{
HildonButtonPrivate *priv;
priv = HILDON_BUTTON_GET_PRIVATE (button);
gtk_label_set_text (priv->title, title);
+ if (title)
+ hildon_button_construct_child (button);
+
g_object_notify (G_OBJECT (button), "title");
}
+/**
+ * hildon_button_set_value:
+ * @button: a #HildonButton
+ * @value: a new value (secondary label) for the button, or %NULL
+ *
+ * Sets the value (secondary label) of @button to @value.
+ *
+ * This will clear the previously set value.
+ *
+ * If @value is set to %NULL, the value label will be hidden and the
+ * title label will be realigned.
+ *
+ **/
void
hildon_button_set_value (HildonButton *button,
- const char *value)
+ const gchar *value)
{
HildonButtonPrivate *priv;
priv = HILDON_BUTTON_GET_PRIVATE (button);
gtk_label_set_text (priv->value, value);
+ /* If the button has no value, hide the label so the title is
+ * properly aligned */
+ if (value)
+ gtk_widget_show (GTK_WIDGET (priv->value));
+ else
+ gtk_widget_hide (GTK_WIDGET (priv->value));
+
g_object_notify (G_OBJECT (button), "value");
}
-const char *
+/**
+ * hildon_button_get_title:
+ * @button: a #HildonButton
+ *
+ * Gets the text from the main label (title) of @button, or %NULL if
+ * none has been set.
+ *
+ * Returns: The text of the title label. This string is owned by the
+ * widget and must not be modified or freed.
+ **/
+const gchar *
hildon_button_get_title (HildonButton *button)
{
HildonButtonPrivate *priv;
return gtk_label_get_text (priv->title);
}
-const char *
+/**
+ * hildon_button_get_value:
+ * @button: a #HildonButton
+ *
+ * Gets the text from the secondary label (value) of @button, or %NULL
+ * if none has been set.
+ *
+ * Returns: The text of the value label. This string is owned by the
+ * widget and must not be modified or freed.
+ **/
+const gchar *
hildon_button_get_value (HildonButton *button)
{
HildonButtonPrivate *priv;
return gtk_label_get_text (priv->value);
}
+/**
+ * hildon_button_set_text:
+ * @button: a #HildonButton
+ * @title: new text for the button title (main label)
+ * @value: new text for the button value (secondary label)
+ *
+ * Convenience function to change both labels of a #HildonButton
+ **/
void
-hildon_button_set_title_and_value (HildonButton *button,
- const char *title,
- const char *value)
+hildon_button_set_text (HildonButton *button,
+ const gchar *title,
+ const gchar *value)
{
hildon_button_set_title (button, title);
hildon_button_set_value (button, value);
}
+
+static void
+hildon_button_construct_child (HildonButton *button)
+{
+ HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
+ GtkBin *bin = GTK_BIN (button);
+
+ /* Return if there's nothing to do */
+ if (bin->child == priv->alignment)
+ return;
+
+ if (bin->child) {
+ gtk_container_remove (GTK_CONTAINER (button), bin->child);
+ }
+
+ gtk_container_add (GTK_CONTAINER (button), priv->alignment);
+ gtk_widget_show_all (priv->alignment);
+}
projects / hildon / blobdiff