2 * This file is a part of hildon
4 * Copyright (C) 2008 Nokia Corporation, all rights reserved.
6 * Contact: Karl Lattimer <karl.lattimer@nokia.com>
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser Public License as published by
10 * the Free Software Foundation; version 2 of the license.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Lesser Public License for more details.
20 * SECTION:hildon-button
21 * @short_description: Widget representing a button in the Hildon framework.
23 * The #HildonButton is a GTK widget which represents a clickable
24 * button. It is derived from the GtkButton widget and provides
25 * additional commodities specific to the Hildon framework.
27 * The height of a #HildonButton can be set to either "finger" height
28 * or "thumb" height. It can also be configured to use halfscreen or
29 * fullscreen width. Alternatively, either dimension can be set to
30 * "auto" so it behaves like a standard GtkButton.
32 * The #HildonButton can hold any valid child widget, but it usually
33 * contains two labels, named title and value, and it can also contain
34 * an image. To change the alignment of the button contents, use
35 * gtk_button_set_alignment()
38 * <title>Creating a HildonButton</title>
41 * button_clicked (HildonButton *button, gpointer user_data)
43 * const gchar *title, *value;
45 * title = hildon_button_get_title (button);
46 * value = hildon_button_get_value (button);
47 * g_debug ("Button clicked with title '%s' and value '%s'", title, value);
51 * create_button (void)
56 * button = hildon_button_new (HILDON_SIZE_AUTO, HILDON_BUTTON_ARRANGEMENT_VERTICAL);
57 * hildon_button_set_text (HILDON_BUTTON (button), "Some title", "Some value");
59 * image = gtk_image_new_from_stock (GTK_STOCK_INFO, GTK_ICON_SIZE_BUTTON);
60 * hildon_button_set_image (HILDON_BUTTON (button), image);
61 * hildon_button_set_image_position (HILDON_BUTTON (button), GTK_POS_RIGHT);
63 * gtk_button_set_alignment (GTK_BUTTON (button), 0.0, 0.5);
65 * g_signal_connect (button, "clicked", G_CALLBACK (button_clicked), NULL);
73 #include "hildon-button.h"
74 #include "hildon-enum-types.h"
75 #include "hildon-gtk.h"
77 G_DEFINE_TYPE (HildonButton, hildon_button, GTK_TYPE_BUTTON);
79 #define HILDON_BUTTON_GET_PRIVATE(obj) \
80 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
81 HILDON_TYPE_BUTTON, HildonButtonPrivate));
83 typedef struct _HildonButtonPrivate HildonButtonPrivate;
85 struct _HildonButtonPrivate
93 GtkPositionType image_position;
104 hildon_button_set_arrangement (HildonButton *button,
105 HildonButtonArrangement arrangement);
108 hildon_button_construct_child (HildonButton *button);
111 hildon_button_set_property (GObject *object,
116 HildonButton *button = HILDON_BUTTON (object);
121 hildon_button_set_title (button, g_value_get_string (value));
124 hildon_button_set_value (button, g_value_get_string (value));
127 hildon_gtk_widget_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
129 case PROP_ARRANGEMENT:
130 hildon_button_set_arrangement (button, g_value_get_enum (value));
133 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
139 hildon_button_get_property (GObject *object,
144 HildonButton *button = HILDON_BUTTON (object);
145 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
150 g_value_set_string (value, gtk_label_get_text (priv->title));
153 g_value_set_string (value, gtk_label_get_text (priv->value));
156 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
162 hildon_button_class_init (HildonButtonClass *klass)
164 GObjectClass *gobject_class = (GObjectClass *)klass;
165 GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
167 gobject_class->set_property = hildon_button_set_property;
168 gobject_class->get_property = hildon_button_get_property;
170 g_object_class_install_property (
173 g_param_spec_string (
176 "Text of the title label inside the button",
178 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
180 g_object_class_install_property (
183 g_param_spec_string (
186 "Text of the value label inside the button",
188 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
190 g_object_class_install_property (
196 "Size request for the button",
197 HILDON_TYPE_SIZE_TYPE,
199 G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
201 g_object_class_install_property (
207 "How the button contents must be arranged",
208 HILDON_TYPE_BUTTON_ARRANGEMENT,
209 HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
210 G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
212 gtk_widget_class_install_style_property (
215 "horizontal-spacing",
216 "Horizontal spacing between labels",
217 "Horizontal spacing between the title and value labels, when in horizontal mode",
221 gtk_widget_class_install_style_property (
225 "Vertical spacing between labels",
226 "Vertical spacing between the title and value labels, when in vertical mode",
230 g_type_class_add_private (klass, sizeof (HildonButtonPrivate));
234 hildon_button_init (HildonButton *self)
236 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (self);
238 priv->title = GTK_LABEL (gtk_label_new (NULL));
239 priv->value = GTK_LABEL (gtk_label_new (NULL));
240 priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
242 priv->image_position = GTK_POS_LEFT;
244 priv->label_box = NULL;
246 gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
247 gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
249 gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
250 gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
252 /* The labels are not shown automatically, see hildon_button_set_(title|value) */
253 gtk_widget_set_no_show_all (GTK_WIDGET (priv->title), TRUE);
254 gtk_widget_set_no_show_all (GTK_WIDGET (priv->value), TRUE);
258 * hildon_button_add_title_size_group:
259 * @button: a #HildonButton
260 * @size_group: A #GtkSizeGroup for the button title (main label)
262 * Adds the title label of @button to @size_group.
265 hildon_button_add_title_size_group (HildonButton *button,
266 GtkSizeGroup *size_group)
268 HildonButtonPrivate *priv;
270 g_return_if_fail (HILDON_IS_BUTTON (button));
271 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
273 priv = HILDON_BUTTON_GET_PRIVATE (button);
275 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->title));
279 * hildon_button_add_value_size_group:
280 * @button: a #HildonButton
281 * @size_group: A #GtkSizeGroup for the button value (secondary label)
283 * Adds the value label of @button to @size_group.
286 hildon_button_add_value_size_group (HildonButton *button,
287 GtkSizeGroup *size_group)
289 HildonButtonPrivate *priv;
291 g_return_if_fail (HILDON_IS_BUTTON (button));
292 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
294 priv = HILDON_BUTTON_GET_PRIVATE (button);
296 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->value));
300 * hildon_button_add_image_size_group:
301 * @button: a #HildonButton
302 * @size_group: A #GtkSizeGroup for the button image
304 * Adds the image of @button to @size_group. You must add an image
305 * using hildon_button_set_image() before calling this function.
308 hildon_button_add_image_size_group (HildonButton *button,
309 GtkSizeGroup *size_group)
311 HildonButtonPrivate *priv;
313 g_return_if_fail (HILDON_IS_BUTTON (button));
314 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
316 priv = HILDON_BUTTON_GET_PRIVATE (button);
318 g_return_if_fail (GTK_IS_WIDGET (priv->image));
320 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->image));
324 * hildon_button_add_size_groups:
325 * @button: a #HildonButton
326 * @title_size_group: A #GtkSizeGroup for the button title (main label), or %NULL
327 * @value_size_group: A #GtkSizeGroup group for the button value (secondary label), or %NULL
328 * @image_size_group: A #GtkSizeGroup group for the button image, or %NULL
330 * Convenience function to add title, value and image to size
331 * groups. %NULL size groups will be ignored.
334 hildon_button_add_size_groups (HildonButton *button,
335 GtkSizeGroup *title_size_group,
336 GtkSizeGroup *value_size_group,
337 GtkSizeGroup *image_size_group)
339 if (title_size_group)
340 hildon_button_add_title_size_group (button, title_size_group);
342 if (value_size_group)
343 hildon_button_add_value_size_group (button, value_size_group);
345 if (image_size_group)
346 hildon_button_add_image_size_group (button, image_size_group);
351 * @size: Flags to set the size of the button.
352 * @arrangement: How the labels must be arranged.
354 * Creates a new #HildonButton. To set text in the labels, use
355 * hildon_button_set_title() and
356 * hildon_button_set_value(). Alternatively, you can add a custom
357 * child widget using gtk_container_add().
359 * Returns: a new #HildonButton
362 hildon_button_new (HildonSizeType size,
363 HildonButtonArrangement arrangement)
365 return hildon_button_new_with_text (size, arrangement, NULL, NULL);
369 * hildon_button_new_with_text:
370 * @size: Flags to set the size of the button.
371 * @arrangement: How the labels must be arranged.
372 * @title: Title of the button (main label), or %NULL
373 * @value: Value of the button (secondary label), or %NULL
375 * Creates a new #HildonButton with two labels, @title and @value.
377 * If you just don't want to use one of the labels, set it to
378 * %NULL. You can set it to a non-%NULL value at any time later.
380 * Returns: a new #HildonButton
383 hildon_button_new_with_text (HildonSizeType size,
384 HildonButtonArrangement arrangement,
391 button = g_object_new (HILDON_TYPE_BUTTON,
395 "arrangement", arrangement,
402 hildon_button_set_arrangement (HildonButton *button,
403 HildonButtonArrangement arrangement)
405 HildonButtonPrivate *priv;
406 guint horizontal_spacing;
407 guint vertical_spacing;
409 priv = HILDON_BUTTON_GET_PRIVATE (button);
411 /* Pack everything */
412 gtk_widget_style_get (GTK_WIDGET (button),
413 "horizontal-spacing", &horizontal_spacing,
414 "vertical-spacing", &vertical_spacing,
417 if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
418 priv->label_box = gtk_vbox_new (FALSE, vertical_spacing);
420 priv->label_box = gtk_hbox_new (FALSE, horizontal_spacing);
423 gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->title), FALSE, FALSE, 0);
424 gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->value), FALSE, FALSE, 0);
426 hildon_button_construct_child (button);
430 * hildon_button_set_title:
431 * @button: a #HildonButton
432 * @title: a new title (main label) for the button, or %NULL
434 * Sets the title (main label) of @button to @title.
436 * This will clear any previously set title.
438 * If @title is set to %NULL, the title label will be hidden and the
439 * value label will be realigned.
442 hildon_button_set_title (HildonButton *button,
445 HildonButtonPrivate *priv;
447 g_return_if_fail (HILDON_IS_BUTTON (button));
449 priv = HILDON_BUTTON_GET_PRIVATE (button);
450 gtk_label_set_text (priv->title, title);
452 /* If the button has no title, hide the label so the value is
453 * properly aligned */
455 hildon_button_construct_child (button);
456 gtk_widget_show (GTK_WIDGET (priv->title));
458 gtk_widget_hide (GTK_WIDGET (priv->title));
461 g_object_notify (G_OBJECT (button), "title");
465 * hildon_button_set_value:
466 * @button: a #HildonButton
467 * @value: a new value (secondary label) for the button, or %NULL
469 * Sets the value (secondary label) of @button to @value.
471 * This will clear any previously set value.
473 * If @value is set to %NULL, the value label will be hidden and the
474 * title label will be realigned.
478 hildon_button_set_value (HildonButton *button,
481 HildonButtonPrivate *priv;
483 g_return_if_fail (HILDON_IS_BUTTON (button));
485 priv = HILDON_BUTTON_GET_PRIVATE (button);
486 gtk_label_set_text (priv->value, value);
488 /* If the button has no value, hide the label so the title is
489 * properly aligned */
491 hildon_button_construct_child (button);
492 gtk_widget_show (GTK_WIDGET (priv->value));
494 gtk_widget_hide (GTK_WIDGET (priv->value));
497 g_object_notify (G_OBJECT (button), "value");
501 * hildon_button_get_title:
502 * @button: a #HildonButton
504 * Gets the text from the main label (title) of @button, or %NULL if
507 * Returns: The text of the title label. This string is owned by the
508 * widget and must not be modified or freed.
511 hildon_button_get_title (HildonButton *button)
513 HildonButtonPrivate *priv;
515 g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
517 priv = HILDON_BUTTON_GET_PRIVATE (button);
519 return gtk_label_get_text (priv->title);
523 * hildon_button_get_value:
524 * @button: a #HildonButton
526 * Gets the text from the secondary label (value) of @button, or %NULL
527 * if none has been set.
529 * Returns: The text of the value label. This string is owned by the
530 * widget and must not be modified or freed.
533 hildon_button_get_value (HildonButton *button)
535 HildonButtonPrivate *priv;
537 g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
539 priv = HILDON_BUTTON_GET_PRIVATE (button);
541 return gtk_label_get_text (priv->value);
545 * hildon_button_set_text:
546 * @button: a #HildonButton
547 * @title: new text for the button title (main label)
548 * @value: new text for the button value (secondary label)
550 * Convenience function to change both labels of a #HildonButton
553 hildon_button_set_text (HildonButton *button,
557 hildon_button_set_title (button, title);
558 hildon_button_set_value (button, value);
562 * hildon_button_set_image:
563 * @button: a #HildonButton
564 * @image: a widget to set as the button image
566 * Sets the image of @button to the given widget. The previous image
567 * (if any) will be removed.
570 hildon_button_set_image (HildonButton *button,
573 HildonButtonPrivate *priv;
575 g_return_if_fail (HILDON_IS_BUTTON (button));
576 g_return_if_fail (!image || GTK_IS_WIDGET (image));
578 priv = HILDON_BUTTON_GET_PRIVATE (button);
580 /* Return if there's nothing to do */
581 if (image == priv->image)
584 if (priv->image && priv->image->parent)
585 gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
589 hildon_button_construct_child (button);
593 * hildon_button_set_image_position:
594 * @button: a #HildonButton
595 * @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
597 * Sets the position of the image inside @button. Only %GTK_POS_LEFT
598 * and %GTK_POS_RIGHT are currently supported.
601 hildon_button_set_image_position (HildonButton *button,
602 GtkPositionType position)
604 HildonButtonPrivate *priv;
606 g_return_if_fail (HILDON_IS_BUTTON (button));
607 g_return_if_fail (position == GTK_POS_LEFT || position == GTK_POS_RIGHT);
609 priv = HILDON_BUTTON_GET_PRIVATE (button);
611 /* Return if there's nothing to do */
612 if (priv->image_position == position)
615 priv->image_position = position;
617 hildon_button_construct_child (button);
621 hildon_button_construct_child (HildonButton *button)
623 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
626 /* Don't do anything if the button is not constructed yet */
627 if (priv->label_box == NULL)
630 /* Save a ref to the image if necessary */
631 if (priv->image && priv->image->parent != NULL) {
632 g_object_ref (priv->image);
633 gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
636 /* Save a ref to the label box if necessary */
637 if (priv->label_box->parent != NULL) {
638 g_object_ref (priv->label_box);
639 gtk_container_remove (GTK_CONTAINER (priv->label_box->parent), priv->label_box);
642 /* Remove the child from the container and add priv->alignment */
643 child = gtk_bin_get_child (GTK_BIN (button));
644 if (child != NULL && child != priv->alignment) {
645 gtk_container_remove (GTK_CONTAINER (button), child);
650 gtk_container_add (GTK_CONTAINER (button), GTK_WIDGET (priv->alignment));
653 /* Create a new hbox */
655 gtk_container_remove (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
657 priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, 10));
658 gtk_container_add (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
660 /* Pack the image and the alignment in the new hbox */
661 if (priv->image && priv->image_position == GTK_POS_LEFT)
662 gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
664 gtk_box_pack_start (priv->hbox, priv->label_box, TRUE, TRUE, 0);
666 if (priv->image && priv->image_position == GTK_POS_RIGHT)
667 gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
669 /* Show everything */
670 gtk_widget_show_all (GTK_WIDGET (priv->alignment));