2008-08-13 Alberto Garcia <agarcia@igalia.com>
[hildon] / src / hildon-button.c
1 /*
2  * This file is a part of hildon
3  *
4  * Copyright (C) 2008 Nokia Corporation, all rights reserved.
5  *
6  * Contact: Karl Lattimer <karl.lattimer@nokia.com>
7  *
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.
11  *
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.
16  *
17  */
18
19 /**
20  * SECTION:hildon-button
21  * @short_description: Widget representing a button in the Hildon framework.
22  *
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.
26  *
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.
31  *
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()
36  *
37  * <example>
38  * <title>Creating a HildonButton</title>
39  * <programlisting>
40  * void
41  * button_clicked (HildonButton *button, gpointer user_data)
42  * {
43  *     const gchar *title, *value;
44  * <!-- -->
45  *     title = hildon_button_get_title (button);
46  *     value = hildon_button_get_value (button);
47  *     g_debug ("Button clicked with title '&percnt;s' and value '&percnt;s'", title, value);
48  * }
49  * <!-- -->
50  * GtkWidget *
51  * create_button (void)
52  * {
53  *     GtkWidget *button;
54  *     GtkWidget *image;
55  * <!-- -->
56  *     button = hildon_button_new (HILDON_SIZE_AUTO, HILDON_BUTTON_ARRANGEMENT_VERTICAL);
57  *     hildon_button_set_text (HILDON_BUTTON (button), "Some title", "Some value");
58  * <!-- -->
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);
62  * <!-- -->
63  *     gtk_button_set_alignment (GTK_BUTTON (button), 0.0, 0.5);
64  * <!-- -->
65  *     g_signal_connect (button, "clicked", G_CALLBACK (button_clicked), NULL);
66  * <!-- -->
67  *     return button;
68  * }
69  * </programlisting>
70  * </example>
71  */
72
73 #include                                        "hildon-button.h"
74 #include                                        "hildon-enum-types.h"
75 #include                                        "hildon-gtk.h"
76
77 G_DEFINE_TYPE                                   (HildonButton, hildon_button, GTK_TYPE_BUTTON);
78
79 #define                                         HILDON_BUTTON_GET_PRIVATE(obj) \
80                                                 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
81                                                 HILDON_TYPE_BUTTON, HildonButtonPrivate));
82
83 typedef struct                                  _HildonButtonPrivate HildonButtonPrivate;
84
85 struct                                          _HildonButtonPrivate
86 {
87     GtkLabel *title;
88     GtkLabel *value;
89     GtkBox *hbox;
90     GtkWidget *label_box;
91     GtkWidget *alignment;
92     GtkWidget *image;
93     GtkPositionType image_position;
94 };
95
96 enum {
97     PROP_TITLE = 1,
98     PROP_VALUE,
99     PROP_SIZE,
100     PROP_ARRANGEMENT
101 };
102
103 static void
104 hildon_button_set_arrangement                   (HildonButton            *button,
105                                                  HildonButtonArrangement  arrangement);
106
107 static void
108 hildon_button_construct_child                   (HildonButton *button);
109
110 static void
111 hildon_button_set_property                      (GObject      *object,
112                                                  guint         prop_id,
113                                                  const GValue *value,
114                                                  GParamSpec   *pspec)
115 {
116     HildonButton *button = HILDON_BUTTON (object);
117
118     switch (prop_id)
119     {
120     case PROP_TITLE:
121         hildon_button_set_title (button, g_value_get_string (value));
122         break;
123     case PROP_VALUE:
124         hildon_button_set_value (button, g_value_get_string (value));
125         break;
126     case PROP_SIZE:
127         hildon_gtk_widget_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
128         break;
129     case PROP_ARRANGEMENT:
130         hildon_button_set_arrangement (button, g_value_get_enum (value));
131         break;
132     default:
133         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
134         break;
135     }
136 }
137
138 static void
139 hildon_button_get_property                      (GObject    *object,
140                                                  guint       prop_id,
141                                                  GValue     *value,
142                                                  GParamSpec *pspec)
143 {
144     HildonButton *button = HILDON_BUTTON (object);
145     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
146
147     switch (prop_id)
148     {
149     case PROP_TITLE:
150         g_value_set_string (value, gtk_label_get_text (priv->title));
151         break;
152     case PROP_VALUE:
153         g_value_set_string (value, gtk_label_get_text (priv->value));
154         break;
155     default:
156         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
157         break;
158     }
159 }
160
161 static void
162 hildon_button_class_init                        (HildonButtonClass *klass)
163 {
164     GObjectClass *gobject_class = (GObjectClass *)klass;
165     GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
166
167     gobject_class->set_property = hildon_button_set_property;
168     gobject_class->get_property = hildon_button_get_property;
169
170     g_object_class_install_property (
171         gobject_class,
172         PROP_TITLE,
173         g_param_spec_string (
174             "title",
175             "Title",
176             "Text of the title label inside the button",
177             NULL,
178             G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
179
180     g_object_class_install_property (
181         gobject_class,
182         PROP_VALUE,
183         g_param_spec_string (
184             "value",
185             "Value",
186             "Text of the value label inside the button",
187             NULL,
188             G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
189
190     g_object_class_install_property (
191         gobject_class,
192         PROP_SIZE,
193         g_param_spec_flags (
194             "size",
195             "Size",
196             "Size request for the button",
197             HILDON_TYPE_SIZE_TYPE,
198             HILDON_SIZE_AUTO,
199             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
200
201     g_object_class_install_property (
202         gobject_class,
203         PROP_ARRANGEMENT,
204         g_param_spec_enum (
205             "arrangement",
206             "Arrangement",
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));
211
212     gtk_widget_class_install_style_property (
213         widget_class,
214         g_param_spec_uint (
215             "horizontal-spacing",
216             "Horizontal spacing between labels",
217             "Horizontal spacing between the title and value labels, when in horizontal mode",
218             0, G_MAXUINT, 25,
219             G_PARAM_READABLE));
220
221     gtk_widget_class_install_style_property (
222         widget_class,
223         g_param_spec_uint (
224             "vertical-spacing",
225             "Vertical spacing between labels",
226             "Vertical spacing between the title and value labels, when in vertical mode",
227             0, G_MAXUINT, 5,
228             G_PARAM_READABLE));
229
230     g_type_class_add_private (klass, sizeof (HildonButtonPrivate));
231 }
232
233 static void
234 hildon_button_init                              (HildonButton *self)
235 {
236     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (self);
237
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);
241     priv->image = NULL;
242     priv->image_position = GTK_POS_LEFT;
243     priv->hbox = NULL;
244     priv->label_box = NULL;
245
246     gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
247     gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
248
249     gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
250     gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
251
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);
255 }
256
257 /**
258  * hildon_button_add_title_size_group:
259  * @button: a #HildonButton
260  * @size_group: A #GtkSizeGroup for the button title (main label)
261  *
262  * Adds the title label of @button to @size_group.
263  **/
264 void
265 hildon_button_add_title_size_group              (HildonButton *button,
266                                                  GtkSizeGroup *size_group)
267 {
268     HildonButtonPrivate *priv;
269
270     g_return_if_fail (HILDON_IS_BUTTON (button));
271     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
272
273     priv = HILDON_BUTTON_GET_PRIVATE (button);
274
275     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->title));
276 }
277
278 /**
279  * hildon_button_add_value_size_group:
280  * @button: a #HildonButton
281  * @size_group: A #GtkSizeGroup for the button value (secondary label)
282  *
283  * Adds the value label of @button to @size_group.
284  **/
285 void
286 hildon_button_add_value_size_group              (HildonButton *button,
287                                                  GtkSizeGroup *size_group)
288 {
289     HildonButtonPrivate *priv;
290
291     g_return_if_fail (HILDON_IS_BUTTON (button));
292     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
293
294     priv = HILDON_BUTTON_GET_PRIVATE (button);
295
296     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->value));
297 }
298
299 /**
300  * hildon_button_add_image_size_group:
301  * @button: a #HildonButton
302  * @size_group: A #GtkSizeGroup for the button image
303  *
304  * Adds the image of @button to @size_group. You must add an image
305  * using hildon_button_set_image() before calling this function.
306  **/
307 void
308 hildon_button_add_image_size_group              (HildonButton *button,
309                                                  GtkSizeGroup *size_group)
310 {
311     HildonButtonPrivate *priv;
312
313     g_return_if_fail (HILDON_IS_BUTTON (button));
314     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
315
316     priv = HILDON_BUTTON_GET_PRIVATE (button);
317
318     g_return_if_fail (GTK_IS_WIDGET (priv->image));
319
320     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->image));
321 }
322
323 /**
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
329  *
330  * Convenience function to add title, value and image to size
331  * groups. %NULL size groups will be ignored.
332  **/
333 void
334 hildon_button_add_size_groups                   (HildonButton *button,
335                                                  GtkSizeGroup *title_size_group,
336                                                  GtkSizeGroup *value_size_group,
337                                                  GtkSizeGroup *image_size_group)
338 {
339     if (title_size_group)
340         hildon_button_add_title_size_group (button, title_size_group);
341
342     if (value_size_group)
343         hildon_button_add_value_size_group (button, value_size_group);
344
345     if (image_size_group)
346         hildon_button_add_image_size_group (button, image_size_group);
347 }
348
349 /**
350  * hildon_button_new:
351  * @size: Flags to set the size of the button.
352  * @arrangement: How the labels must be arranged.
353  *
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().
358  *
359  * Returns: a new #HildonButton
360  **/
361 GtkWidget *
362 hildon_button_new                               (HildonSizeType          size,
363                                                  HildonButtonArrangement arrangement)
364 {
365     return hildon_button_new_with_text (size, arrangement, NULL, NULL);
366 }
367
368 /**
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
374  *
375  * Creates a new #HildonButton with two labels, @title and @value.
376  *
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.
379  *
380  * Returns: a new #HildonButton
381  **/
382 GtkWidget *
383 hildon_button_new_with_text                     (HildonSizeType           size,
384                                                  HildonButtonArrangement  arrangement,
385                                                  const gchar             *title,
386                                                  const gchar             *value)
387 {
388     GtkWidget *button;
389
390     /* Create widget */
391     button = g_object_new (HILDON_TYPE_BUTTON,
392                            "size", size,
393                            "title", title,
394                            "value", value,
395                            "arrangement", arrangement,
396                            NULL);
397
398     return button;
399 }
400
401 static void
402 hildon_button_set_arrangement                   (HildonButton            *button,
403                                                  HildonButtonArrangement  arrangement)
404 {
405     HildonButtonPrivate *priv;
406     guint horizontal_spacing;
407     guint vertical_spacing;
408
409     priv = HILDON_BUTTON_GET_PRIVATE (button);
410
411     /* Pack everything */
412     gtk_widget_style_get (GTK_WIDGET (button),
413                           "horizontal-spacing", &horizontal_spacing,
414                           "vertical-spacing", &vertical_spacing,
415                           NULL);
416
417     if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
418         priv->label_box = gtk_vbox_new (FALSE, vertical_spacing);
419     } else {
420         priv->label_box = gtk_hbox_new (FALSE, horizontal_spacing);
421     }
422
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);
425
426     hildon_button_construct_child (button);
427 }
428
429 /**
430  * hildon_button_set_title:
431  * @button: a #HildonButton
432  * @title: a new title (main label) for the button, or %NULL
433  *
434  * Sets the title (main label) of @button to @title.
435  *
436  * This will clear any previously set title.
437  *
438  * If @title is set to %NULL, the title label will be hidden and the
439  * value label will be realigned.
440  **/
441 void
442 hildon_button_set_title                         (HildonButton *button,
443                                                  const gchar  *title)
444 {
445     HildonButtonPrivate *priv;
446
447     g_return_if_fail (HILDON_IS_BUTTON (button));
448
449     priv = HILDON_BUTTON_GET_PRIVATE (button);
450     gtk_label_set_text (priv->title, title);
451
452     /* If the button has no title, hide the label so the value is
453      * properly aligned */
454     if (title) {
455         hildon_button_construct_child (button);
456         gtk_widget_show (GTK_WIDGET (priv->title));
457     } else {
458         gtk_widget_hide (GTK_WIDGET (priv->title));
459     }
460
461     g_object_notify (G_OBJECT (button), "title");
462 }
463
464 /**
465  * hildon_button_set_value:
466  * @button: a #HildonButton
467  * @value: a new value (secondary label) for the button, or %NULL
468  *
469  * Sets the value (secondary label) of @button to @value.
470  *
471  * This will clear any previously set value.
472  *
473  * If @value is set to %NULL, the value label will be hidden and the
474  * title label will be realigned.
475  *
476  **/
477 void
478 hildon_button_set_value                         (HildonButton *button,
479                                                  const gchar  *value)
480 {
481     HildonButtonPrivate *priv;
482
483     g_return_if_fail (HILDON_IS_BUTTON (button));
484
485     priv = HILDON_BUTTON_GET_PRIVATE (button);
486     gtk_label_set_text (priv->value, value);
487
488     /* If the button has no value, hide the label so the title is
489      * properly aligned */
490     if (value) {
491         hildon_button_construct_child (button);
492         gtk_widget_show (GTK_WIDGET (priv->value));
493     } else {
494         gtk_widget_hide (GTK_WIDGET (priv->value));
495     }
496
497     g_object_notify (G_OBJECT (button), "value");
498 }
499
500 /**
501  * hildon_button_get_title:
502  * @button: a #HildonButton
503  *
504  * Gets the text from the main label (title) of @button, or %NULL if
505  * none has been set.
506  *
507  * Returns: The text of the title label. This string is owned by the
508  * widget and must not be modified or freed.
509  **/
510 const gchar *
511 hildon_button_get_title                         (HildonButton *button)
512 {
513     HildonButtonPrivate *priv;
514
515     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
516
517     priv = HILDON_BUTTON_GET_PRIVATE (button);
518
519     return gtk_label_get_text (priv->title);
520 }
521
522 /**
523  * hildon_button_get_value:
524  * @button: a #HildonButton
525  *
526  * Gets the text from the secondary label (value) of @button, or %NULL
527  * if none has been set.
528  *
529  * Returns: The text of the value label. This string is owned by the
530  * widget and must not be modified or freed.
531  **/
532 const gchar *
533 hildon_button_get_value                         (HildonButton *button)
534 {
535     HildonButtonPrivate *priv;
536
537     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
538
539     priv = HILDON_BUTTON_GET_PRIVATE (button);
540
541     return gtk_label_get_text (priv->value);
542 }
543
544 /**
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)
549  *
550  * Convenience function to change both labels of a #HildonButton
551  **/
552 void
553 hildon_button_set_text                          (HildonButton *button,
554                                                  const gchar  *title,
555                                                  const gchar  *value)
556 {
557     hildon_button_set_title (button, title);
558     hildon_button_set_value (button, value);
559 }
560
561 /**
562  * hildon_button_set_image:
563  * @button: a #HildonButton
564  * @image: a widget to set as the button image
565  *
566  * Sets the image of @button to the given widget. The previous image
567  * (if any) will be removed.
568  **/
569 void
570 hildon_button_set_image                         (HildonButton *button,
571                                                  GtkWidget    *image)
572 {
573     HildonButtonPrivate *priv;
574
575     g_return_if_fail (HILDON_IS_BUTTON (button));
576     g_return_if_fail (!image || GTK_IS_WIDGET (image));
577
578     priv = HILDON_BUTTON_GET_PRIVATE (button);
579
580     /* Return if there's nothing to do */
581     if (image == priv->image)
582         return;
583
584     if (priv->image && priv->image->parent)
585         gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
586
587     priv->image = image;
588
589     hildon_button_construct_child (button);
590 }
591
592 /**
593  * hildon_button_set_image_position:
594  * @button: a #HildonButton
595  * @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
596  *
597  * Sets the position of the image inside @button. Only %GTK_POS_LEFT
598  * and %GTK_POS_RIGHT are currently supported.
599  **/
600 void
601 hildon_button_set_image_position                (HildonButton    *button,
602                                                  GtkPositionType  position)
603 {
604     HildonButtonPrivate *priv;
605
606     g_return_if_fail (HILDON_IS_BUTTON (button));
607     g_return_if_fail (position == GTK_POS_LEFT || position == GTK_POS_RIGHT);
608
609     priv = HILDON_BUTTON_GET_PRIVATE (button);
610
611     /* Return if there's nothing to do */
612     if (priv->image_position == position)
613         return;
614
615     priv->image_position = position;
616
617     hildon_button_construct_child (button);
618 }
619
620 static void
621 hildon_button_construct_child                   (HildonButton *button)
622 {
623     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
624     GtkWidget *child;
625
626     /* Don't do anything if the button is not constructed yet */
627     if (priv->label_box == NULL)
628         return;
629
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);
634     }
635
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);
640     }
641
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);
646         child = NULL;
647     }
648
649     if (child == NULL) {
650         gtk_container_add (GTK_CONTAINER (button), GTK_WIDGET (priv->alignment));
651     }
652
653     /* Create a new hbox */
654     if (priv->hbox) {
655         gtk_container_remove (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
656     }
657     priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, 10));
658     gtk_container_add (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
659
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);
663
664     gtk_box_pack_start (priv->hbox, priv->label_box, TRUE, TRUE, 0);
665
666     if (priv->image && priv->image_position == GTK_POS_RIGHT)
667         gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
668
669     /* Show everything */
670     gtk_widget_show_all (GTK_WIDGET (priv->alignment));
671 }