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;
106 hildon_button_set_arrangement (HildonButton *button,
107 HildonButtonArrangement arrangement);
110 hildon_button_construct_child (HildonButton *button);
113 hildon_button_set_property (GObject *object,
118 HildonButton *button = HILDON_BUTTON (object);
123 hildon_button_set_title (button, g_value_get_string (value));
126 hildon_button_set_value (button, g_value_get_string (value));
129 hildon_gtk_widget_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
131 case PROP_ARRANGEMENT:
132 hildon_button_set_arrangement (button, g_value_get_enum (value));
135 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
141 hildon_button_get_property (GObject *object,
146 HildonButton *button = HILDON_BUTTON (object);
147 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
152 g_value_set_string (value, gtk_label_get_text (priv->title));
155 g_value_set_string (value, gtk_label_get_text (priv->value));
158 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
164 hildon_button_style_set (GtkWidget *widget,
165 GtkStyle *previous_style)
167 guint horizontal_spacing, vertical_spacing, image_spacing;
168 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (widget);
170 if (GTK_WIDGET_CLASS (hildon_button_parent_class)->style_set)
171 GTK_WIDGET_CLASS (hildon_button_parent_class)->style_set (widget, previous_style);
173 gtk_widget_style_get (widget,
174 "horizontal-spacing", &horizontal_spacing,
175 "vertical-spacing", &vertical_spacing,
176 "image-spacing", &image_spacing,
179 if (GTK_IS_HBOX (priv->label_box)) {
180 gtk_box_set_spacing (GTK_BOX (priv->label_box), horizontal_spacing);
182 gtk_box_set_spacing (GTK_BOX (priv->label_box), vertical_spacing);
185 if (GTK_IS_BOX (priv->hbox)) {
186 gtk_box_set_spacing (priv->hbox, image_spacing);
191 hildon_button_class_init (HildonButtonClass *klass)
193 GObjectClass *gobject_class = (GObjectClass *)klass;
194 GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
196 gobject_class->set_property = hildon_button_set_property;
197 gobject_class->get_property = hildon_button_get_property;
198 widget_class->style_set = hildon_button_style_set;
200 g_object_class_install_property (
203 g_param_spec_string (
206 "Text of the title label inside the button",
208 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
210 g_object_class_install_property (
213 g_param_spec_string (
216 "Text of the value label inside the button",
218 G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
220 g_object_class_install_property (
226 "Size request for the button",
227 HILDON_TYPE_SIZE_TYPE,
229 G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
231 g_object_class_install_property (
237 "How the button contents must be arranged",
238 HILDON_TYPE_BUTTON_ARRANGEMENT,
239 HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
240 G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
242 gtk_widget_class_install_style_property (
245 "horizontal-spacing",
246 "Horizontal spacing between labels",
247 "Horizontal spacing between the title and value labels, when in horizontal mode",
251 gtk_widget_class_install_style_property (
255 "Vertical spacing between labels",
256 "Vertical spacing between the title and value labels, when in vertical mode",
260 g_type_class_add_private (klass, sizeof (HildonButtonPrivate));
264 hildon_button_init (HildonButton *self)
266 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (self);
268 priv->title = GTK_LABEL (gtk_label_new (NULL));
269 priv->value = GTK_LABEL (gtk_label_new (NULL));
270 priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
272 priv->image_position = GTK_POS_LEFT;
273 priv->image_xalign = 0.0;
274 priv->image_yalign = 0.0;
276 priv->label_box = NULL;
278 gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
279 gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
281 gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
282 gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
284 /* The labels are not shown automatically, see hildon_button_set_(title|value) */
285 gtk_widget_set_no_show_all (GTK_WIDGET (priv->title), TRUE);
286 gtk_widget_set_no_show_all (GTK_WIDGET (priv->value), TRUE);
290 * hildon_button_add_title_size_group:
291 * @button: a #HildonButton
292 * @size_group: A #GtkSizeGroup for the button title (main label)
294 * Adds the title label of @button to @size_group.
297 hildon_button_add_title_size_group (HildonButton *button,
298 GtkSizeGroup *size_group)
300 HildonButtonPrivate *priv;
302 g_return_if_fail (HILDON_IS_BUTTON (button));
303 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
305 priv = HILDON_BUTTON_GET_PRIVATE (button);
307 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->title));
311 * hildon_button_add_value_size_group:
312 * @button: a #HildonButton
313 * @size_group: A #GtkSizeGroup for the button value (secondary label)
315 * Adds the value label of @button to @size_group.
318 hildon_button_add_value_size_group (HildonButton *button,
319 GtkSizeGroup *size_group)
321 HildonButtonPrivate *priv;
323 g_return_if_fail (HILDON_IS_BUTTON (button));
324 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
326 priv = HILDON_BUTTON_GET_PRIVATE (button);
328 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->value));
332 * hildon_button_add_image_size_group:
333 * @button: a #HildonButton
334 * @size_group: A #GtkSizeGroup for the button image
336 * Adds the image of @button to @size_group. You must add an image
337 * using hildon_button_set_image() before calling this function.
340 hildon_button_add_image_size_group (HildonButton *button,
341 GtkSizeGroup *size_group)
343 HildonButtonPrivate *priv;
345 g_return_if_fail (HILDON_IS_BUTTON (button));
346 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
348 priv = HILDON_BUTTON_GET_PRIVATE (button);
350 g_return_if_fail (GTK_IS_WIDGET (priv->image));
352 gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->image));
356 * hildon_button_add_size_groups:
357 * @button: a #HildonButton
358 * @title_size_group: A #GtkSizeGroup for the button title (main label), or %NULL
359 * @value_size_group: A #GtkSizeGroup group for the button value (secondary label), or %NULL
360 * @image_size_group: A #GtkSizeGroup group for the button image, or %NULL
362 * Convenience function to add title, value and image to size
363 * groups. %NULL size groups will be ignored.
366 hildon_button_add_size_groups (HildonButton *button,
367 GtkSizeGroup *title_size_group,
368 GtkSizeGroup *value_size_group,
369 GtkSizeGroup *image_size_group)
371 if (title_size_group)
372 hildon_button_add_title_size_group (button, title_size_group);
374 if (value_size_group)
375 hildon_button_add_value_size_group (button, value_size_group);
377 if (image_size_group)
378 hildon_button_add_image_size_group (button, image_size_group);
383 * @size: Flags to set the size of the button.
384 * @arrangement: How the labels must be arranged.
386 * Creates a new #HildonButton. To set text in the labels, use
387 * hildon_button_set_title() and
388 * hildon_button_set_value(). Alternatively, you can add a custom
389 * child widget using gtk_container_add().
391 * Returns: a new #HildonButton
394 hildon_button_new (HildonSizeType size,
395 HildonButtonArrangement arrangement)
397 return hildon_button_new_with_text (size, arrangement, NULL, NULL);
401 * hildon_button_new_with_text:
402 * @size: Flags to set the size of the button.
403 * @arrangement: How the labels must be arranged.
404 * @title: Title of the button (main label), or %NULL
405 * @value: Value of the button (secondary label), or %NULL
407 * Creates a new #HildonButton with two labels, @title and @value.
409 * If you just don't want to use one of the labels, set it to
410 * %NULL. You can set it to a non-%NULL value at any time later.
412 * Returns: a new #HildonButton
415 hildon_button_new_with_text (HildonSizeType size,
416 HildonButtonArrangement arrangement,
423 button = g_object_new (HILDON_TYPE_BUTTON,
427 "arrangement", arrangement,
434 hildon_button_set_arrangement (HildonButton *button,
435 HildonButtonArrangement arrangement)
437 HildonButtonPrivate *priv;
439 priv = HILDON_BUTTON_GET_PRIVATE (button);
441 /* Pack everything */
442 if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
443 priv->label_box = gtk_vbox_new (FALSE, 0);
445 priv->label_box = gtk_hbox_new (FALSE, 0);
448 gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->title), TRUE, TRUE, 0);
449 gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->value), TRUE, TRUE, 0);
451 hildon_button_construct_child (button);
455 * hildon_button_set_title:
456 * @button: a #HildonButton
457 * @title: a new title (main label) for the button, or %NULL
459 * Sets the title (main label) of @button to @title.
461 * This will clear any previously set title.
463 * If @title is set to %NULL, the title label will be hidden and the
464 * value label will be realigned.
467 hildon_button_set_title (HildonButton *button,
470 HildonButtonPrivate *priv;
472 g_return_if_fail (HILDON_IS_BUTTON (button));
474 priv = HILDON_BUTTON_GET_PRIVATE (button);
475 gtk_label_set_text (priv->title, title);
477 /* If the button has no title, hide the label so the value is
478 * properly aligned */
480 hildon_button_construct_child (button);
481 gtk_widget_show (GTK_WIDGET (priv->title));
483 gtk_widget_hide (GTK_WIDGET (priv->title));
486 g_object_notify (G_OBJECT (button), "title");
490 * hildon_button_set_value:
491 * @button: a #HildonButton
492 * @value: a new value (secondary label) for the button, or %NULL
494 * Sets the value (secondary label) of @button to @value.
496 * This will clear any previously set value.
498 * If @value is set to %NULL, the value label will be hidden and the
499 * title label will be realigned.
503 hildon_button_set_value (HildonButton *button,
506 HildonButtonPrivate *priv;
508 g_return_if_fail (HILDON_IS_BUTTON (button));
510 priv = HILDON_BUTTON_GET_PRIVATE (button);
511 gtk_label_set_text (priv->value, value);
513 /* If the button has no value, hide the label so the title is
514 * properly aligned */
516 hildon_button_construct_child (button);
517 gtk_widget_show (GTK_WIDGET (priv->value));
519 gtk_widget_hide (GTK_WIDGET (priv->value));
522 g_object_notify (G_OBJECT (button), "value");
526 * hildon_button_get_title:
527 * @button: a #HildonButton
529 * Gets the text from the main label (title) of @button, or %NULL if
532 * Returns: The text of the title label. This string is owned by the
533 * widget and must not be modified or freed.
536 hildon_button_get_title (HildonButton *button)
538 HildonButtonPrivate *priv;
540 g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
542 priv = HILDON_BUTTON_GET_PRIVATE (button);
544 return gtk_label_get_text (priv->title);
548 * hildon_button_get_value:
549 * @button: a #HildonButton
551 * Gets the text from the secondary label (value) of @button, or %NULL
552 * if none has been set.
554 * Returns: The text of the value label. This string is owned by the
555 * widget and must not be modified or freed.
558 hildon_button_get_value (HildonButton *button)
560 HildonButtonPrivate *priv;
562 g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
564 priv = HILDON_BUTTON_GET_PRIVATE (button);
566 return gtk_label_get_text (priv->value);
570 * hildon_button_set_text:
571 * @button: a #HildonButton
572 * @title: new text for the button title (main label)
573 * @value: new text for the button value (secondary label)
575 * Convenience function to change both labels of a #HildonButton
578 hildon_button_set_text (HildonButton *button,
582 hildon_button_set_title (button, title);
583 hildon_button_set_value (button, value);
587 * hildon_button_set_image:
588 * @button: a #HildonButton
589 * @image: a widget to set as the button image
591 * Sets the image of @button to the given widget. The previous image
592 * (if any) will be removed.
595 hildon_button_set_image (HildonButton *button,
598 HildonButtonPrivate *priv;
600 g_return_if_fail (HILDON_IS_BUTTON (button));
601 g_return_if_fail (!image || GTK_IS_WIDGET (image));
603 priv = HILDON_BUTTON_GET_PRIVATE (button);
605 /* Return if there's nothing to do */
606 if (image == priv->image)
609 if (priv->image && priv->image->parent)
610 gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
614 hildon_button_construct_child (button);
618 * hildon_button_set_image_position:
619 * @button: a #HildonButton
620 * @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
622 * Sets the position of the image inside @button. Only %GTK_POS_LEFT
623 * and %GTK_POS_RIGHT are currently supported.
626 hildon_button_set_image_position (HildonButton *button,
627 GtkPositionType position)
629 HildonButtonPrivate *priv;
631 g_return_if_fail (HILDON_IS_BUTTON (button));
632 g_return_if_fail (position == GTK_POS_LEFT || position == GTK_POS_RIGHT);
634 priv = HILDON_BUTTON_GET_PRIVATE (button);
636 /* Return if there's nothing to do */
637 if (priv->image_position == position)
640 priv->image_position = position;
642 hildon_button_construct_child (button);
646 * hildon_button_set_alignment:
647 * @button: a #HildonButton
648 * @xalign: the horizontal alignment of the contents, from 0 (left) to 1 (right).
649 * @yalign: the vertical alignment of the contents, from 0 (top) to 1 (bottom).
650 * @xscale: the amount that the child widget expands horizontally to fill up unused space, from 0 to 1
651 * @yscale: the amount that the child widget expands vertically to fill up unused space, from 0 to 1
653 * Sets the alignment of the contents of the widget. If you don't need
654 * to change @xscale or @yscale you can just use
655 * gtk_button_set_alignment() instead.
658 hildon_button_set_alignment (HildonButton *button,
664 HildonButtonPrivate *priv;
667 g_return_if_fail (HILDON_IS_BUTTON (button));
669 priv = HILDON_BUTTON_GET_PRIVATE (button);
671 child = gtk_bin_get_child (GTK_BIN (button));
673 if (GTK_IS_ALIGNMENT (child)) {
674 gtk_button_set_alignment (GTK_BUTTON (button), xalign, yalign);
675 g_object_set (child, "xscale", xscale, "yscale", yscale, NULL);
680 * hildon_button_set_title_alignment:
681 * @button: a #HildonButton
682 * @xalign: the horizontal alignment of the title label, from 0 (left) to 1 (right).
683 * @yalign: the vertical alignment of the title label, from 0 (top) to 1 (bottom).
685 * Sets the alignment of the title label. See also
686 * hildon_button_set_alignment() to set the alignment of the whole
687 * contents of the button.
690 hildon_button_set_title_alignment (HildonButton *button,
694 HildonButtonPrivate *priv;
696 g_return_if_fail (HILDON_IS_BUTTON (button));
698 priv = HILDON_BUTTON_GET_PRIVATE (button);
700 gtk_misc_set_alignment (GTK_MISC (priv->title), xalign, yalign);
704 * hildon_button_set_value_alignment:
705 * @button: a #HildonButton
706 * @xalign: the horizontal alignment of the value label, from 0 (left) to 1 (right).
707 * @yalign: the vertical alignment of the value label, from 0 (top) to 1 (bottom).
709 * Sets the alignment of the value label. See also
710 * hildon_button_set_alignment() to set the alignment of the whole
711 * contents of the button.
714 hildon_button_set_value_alignment (HildonButton *button,
718 HildonButtonPrivate *priv;
720 g_return_if_fail (HILDON_IS_BUTTON (button));
722 priv = HILDON_BUTTON_GET_PRIVATE (button);
724 gtk_misc_set_alignment (GTK_MISC (priv->value), xalign, yalign);
728 * hildon_button_set_image_alignment:
729 * @button: a #HildonButton
730 * @xalign: the horizontal alignment of the image, from 0 (left) to 1 (right).
731 * @yalign: the vertical alignment of the image, from 0 (top) to 1 (bottom).
733 * Sets the alignment of the image. See also
734 * hildon_button_set_alignment() to set the alignment of the whole
735 * contents of the button.
738 hildon_button_set_image_alignment (HildonButton *button,
742 HildonButtonPrivate *priv;
744 g_return_if_fail (HILDON_IS_BUTTON (button));
746 priv = HILDON_BUTTON_GET_PRIVATE (button);
748 /* Return if there's nothing to do */
749 if (priv->image_xalign == xalign && priv->image_yalign == yalign)
752 priv->image_xalign = xalign;
753 priv->image_yalign = yalign;
755 hildon_button_construct_child (button);
759 hildon_button_construct_child (HildonButton *button)
761 HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
765 /* Don't do anything if the button is not constructed yet */
766 if (priv->label_box == NULL)
769 /* Save a ref to the image if necessary */
770 if (priv->image && priv->image->parent != NULL) {
771 g_object_ref (priv->image);
772 gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
775 /* Save a ref to the label box if necessary */
776 if (priv->label_box->parent != NULL) {
777 g_object_ref (priv->label_box);
778 gtk_container_remove (GTK_CONTAINER (priv->label_box->parent), priv->label_box);
781 /* Remove the child from the container and add priv->alignment */
782 child = gtk_bin_get_child (GTK_BIN (button));
783 if (child != NULL && child != priv->alignment) {
784 gtk_container_remove (GTK_CONTAINER (button), child);
789 gtk_container_add (GTK_CONTAINER (button), GTK_WIDGET (priv->alignment));
792 /* Create a new hbox */
794 gtk_container_remove (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
796 gtk_widget_style_get (GTK_WIDGET (button), "image-spacing", &image_spacing, NULL);
797 priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, image_spacing));
798 gtk_container_add (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
800 /* Pack the image and the alignment in the new hbox */
801 if (priv->image && priv->image_position == GTK_POS_LEFT)
802 gtk_box_pack_start (priv->hbox, priv->image, TRUE, TRUE, 0);
804 gtk_box_pack_start (priv->hbox, priv->label_box, TRUE, TRUE, 0);
806 if (priv->image && priv->image_position == GTK_POS_RIGHT)
807 gtk_box_pack_start (priv->hbox, priv->image, TRUE, TRUE, 0);
809 /* Set image alignment */
811 gtk_misc_set_alignment (GTK_MISC (priv->image), priv->image_xalign, priv->image_yalign);
813 /* Show everything */
814 gtk_widget_show_all (GTK_WIDGET (priv->alignment));