git.maemo.org Git - hildon/blob - hildon/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: Rodrigo Novo <rodrigo.novo@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: Two-label buttons in the Hildon framework.
  22  *
  23  * The #HildonButton is a clickable button for Hildon applications.
  24  * 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. The contents of the button are packed together inside a
  35  * #GtkAlignment and they do not expand by default (they don't use the
  36  * full space of the button).
  37  *
  38  * To change the alignment of both labels, use gtk_button_set_alignment()
  39  *
  40  * To make them expand and use the full space of the button, use
  41  * hildon_button_set_alignment().
  42  *
  43  * To change the relative alignment of each label, use
  44  * hildon_button_set_title_alignment() and
  45  * hildon_button_set_value_alignment().
  46  *
  47  * In hildon-button-example.c included in the Hildon distribution you
  48  * can see examples of how to create the most common button
  49  * layouts.
  50  *
  51  * If only one label is needed, #GtkButton can be used as well, see
  52  * also hildon_gtk_button_new().
  53  *
  54  * <example>
  55  * <title>Creating a HildonButton</title>
  56  * <programlisting>
  57  * void
  58  * button_clicked (HildonButton *button, gpointer user_data)
  59  * {
  60  *     const gchar *title, *value;
  61  * <!-- -->
  62  *     title = hildon_button_get_title (button);
  63  *     value = hildon_button_get_value (button);
  64  *     g_debug ("Button clicked with title '&percnt;s' and value '&percnt;s'", title, value);
  65  * }
  66  * <!-- -->
  67  * GtkWidget *
  68  * create_button (void)
  69  * {
  70  *     GtkWidget *button;
  71  *     GtkWidget *image;
  72  * <!-- -->
  73  *     button = hildon_button_new (HILDON_SIZE_AUTO_WIDTH | HILDON_SIZE_FINGER_HEIGHT,
  74  *                                 HILDON_BUTTON_ARRANGEMENT_VERTICAL);
  75  *     hildon_button_set_text (HILDON_BUTTON (button), "Some title", "Some value");
  76  * <!-- -->
  77  *     image = gtk_image_new_from_stock (GTK_STOCK_INFO, GTK_ICON_SIZE_BUTTON);
  78  *     hildon_button_set_image (HILDON_BUTTON (button), image);
  79  *     hildon_button_set_image_position (HILDON_BUTTON (button), GTK_POS_RIGHT);
  80  * <!-- -->
  81  *     gtk_button_set_alignment (GTK_BUTTON (button), 0.0, 0.5);
  82  * <!-- -->
  83  *     g_signal_connect (button, "clicked", G_CALLBACK (button_clicked), NULL);
  84  * <!-- -->
  85  *     return button;
  86  * }
  87  * </programlisting>
  88  * </example>
  89  */
  90
  91 #include                                        "hildon-button.h"
  92 #include                                        "hildon-enum-types.h"
  93 #include                                        "hildon-gtk.h"
  94
  95 G_DEFINE_TYPE                                   (HildonButton, hildon_button, GTK_TYPE_BUTTON);
  96
  97 #define                                         HILDON_BUTTON_GET_PRIVATE(obj) \
  98                                                 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
  99                                                 HILDON_TYPE_BUTTON, HildonButtonPrivate));
 100
 101 typedef struct                                  _HildonButtonPrivate HildonButtonPrivate;
 102
 103 struct                                          _HildonButtonPrivate
 104 {
 105     GtkLabel *title;
 106     GtkLabel *value;
 107     GtkBox *hbox;
 108     GtkWidget *label_box;
 109     GtkWidget *alignment;
 110     GtkWidget *image;
 111     GtkPositionType image_position;
 112     gfloat image_xalign;
 113     gfloat image_yalign;
 114     HildonButtonStyle style;
 115     guint setting_style : 1;
 116 };
 117
 118 enum {
 119     PROP_TITLE = 1,
 120     PROP_VALUE,
 121     PROP_SIZE,
 122     PROP_ARRANGEMENT,
 123     PROP_STYLE
 124 };
 125
 126 static void
 127 hildon_button_set_arrangement                   (HildonButton            *button,
 128                                                  HildonButtonArrangement  arrangement);
 129
 130 static void
 131 hildon_button_construct_child                   (HildonButton *button);
 132
 133 static void
 134 hildon_button_set_property                      (GObject      *object,
 135                                                  guint         prop_id,
 136                                                  const GValue *value,
 137                                                  GParamSpec   *pspec)
 138 {
 139     HildonButton *button = HILDON_BUTTON (object);
 140
 141     switch (prop_id)
 142     {
 143     case PROP_TITLE:
 144         hildon_button_set_title (button, g_value_get_string (value));
 145         break;
 146     case PROP_VALUE:
 147         hildon_button_set_value (button, g_value_get_string (value));
 148         break;
 149     case PROP_SIZE:
 150         hildon_gtk_widget_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
 151         break;
 152     case PROP_ARRANGEMENT:
 153         hildon_button_set_arrangement (button, g_value_get_enum (value));
 154         break;
 155     case PROP_STYLE:
 156         hildon_button_set_style (button, g_value_get_enum (value));
 157         break;
 158     default:
 159         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 160         break;
 161     }
 162 }
 163
 164 static void
 165 hildon_button_get_property                      (GObject    *object,
 166                                                  guint       prop_id,
 167                                                  GValue     *value,
 168                                                  GParamSpec *pspec)
 169 {
 170     HildonButton *button = HILDON_BUTTON (object);
 171
 172     switch (prop_id)
 173     {
 174     case PROP_TITLE:
 175         g_value_set_string (value, hildon_button_get_title (button));
 176         break;
 177     case PROP_VALUE:
 178         g_value_set_string (value, hildon_button_get_value (button));
 179         break;
 180     case PROP_STYLE:
 181         g_value_set_enum (value, hildon_button_get_style (button));
 182         break;
 183     default:
 184         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 185         break;
 186     }
 187 }
 188
 189 static void
 190 set_logical_font                                (GtkWidget *button)
 191 {
 192     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
 193
 194     /* In buttons with vertical arrangement, the 'value' label uses a
 195      * different font */
 196     if (GTK_IS_VBOX (priv->label_box)) {
 197         GtkStyle *style = gtk_rc_get_style_by_paths (
 198             gtk_settings_get_default (), "SmallSystemFont", NULL, G_TYPE_NONE);
 199         if (style != NULL) {
 200             PangoFontDescription *font_desc = style->font_desc;
 201             if (font_desc != NULL) {
 202                 priv->setting_style = TRUE;
 203                 gtk_widget_modify_font (GTK_WIDGET (priv->value), font_desc);
 204                 priv->setting_style = FALSE;
 205             }
 206         }
 207     }
 208 }
 209
 210 static void
 211 set_logical_color                               (GtkWidget *button)
 212 {
 213     GdkColor color;
 214     const gchar *colorname;
 215     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
 216     GtkWidget *label = GTK_WIDGET (priv->value);
 217
 218     switch (priv->style) {
 219     case HILDON_BUTTON_STYLE_NORMAL:
 220         colorname = "SecondaryTextColor";
 221         break;
 222     case HILDON_BUTTON_STYLE_PICKER:
 223         colorname = "ActiveTextColor";
 224         break;
 225     default:
 226         g_return_if_reached ();
 227     }
 228
 229     gtk_widget_ensure_style (label);
 230     if (gtk_style_lookup_color (label->style, colorname, &color) == TRUE) {
 231         priv->setting_style = TRUE;
 232         gtk_widget_modify_fg (label, GTK_STATE_NORMAL, &color);
 233         gtk_widget_modify_fg (label, GTK_STATE_PRELIGHT, &color);
 234         priv->setting_style = FALSE;
 235     }
 236 }
 237
 238 static void
 239 hildon_button_style_set                         (GtkWidget *widget,
 240                                                  GtkStyle  *previous_style)
 241 {
 242     guint horizontal_spacing, vertical_spacing, image_spacing;
 243     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (widget);
 244
 245     if (GTK_WIDGET_CLASS (hildon_button_parent_class)->style_set)
 246         GTK_WIDGET_CLASS (hildon_button_parent_class)->style_set (widget, previous_style);
 247
 248     /* Prevent infinite recursion when calling set_logical_font() and
 249      * set_logical_color() */
 250     if (priv->setting_style)
 251         return;
 252
 253     gtk_widget_style_get (widget,
 254                           "horizontal-spacing", &horizontal_spacing,
 255                           "vertical-spacing", &vertical_spacing,
 256                           "image-spacing", &image_spacing,
 257                           NULL);
 258
 259     if (GTK_IS_HBOX (priv->label_box)) {
 260         gtk_box_set_spacing (GTK_BOX (priv->label_box), horizontal_spacing);
 261     } else {
 262         gtk_box_set_spacing (GTK_BOX (priv->label_box), vertical_spacing);
 263     }
 264
 265     if (GTK_IS_BOX (priv->hbox)) {
 266         gtk_box_set_spacing (priv->hbox, image_spacing);
 267     }
 268
 269     set_logical_font (widget);
 270     set_logical_color (widget);
 271 }
 272
 273 static void
 274 hildon_button_finalize                          (GObject *object)
 275 {
 276     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (object);
 277
 278     g_object_unref (priv->alignment);
 279     g_object_unref (priv->label_box);
 280
 281     G_OBJECT_CLASS (hildon_button_parent_class)->finalize (object);
 282 }
 283
 284 static void
 285 hildon_button_class_init                        (HildonButtonClass *klass)
 286 {
 287     GObjectClass *gobject_class = (GObjectClass *)klass;
 288     GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
 289
 290     gobject_class->set_property = hildon_button_set_property;
 291     gobject_class->get_property = hildon_button_get_property;
 292     gobject_class->finalize = hildon_button_finalize;
 293     widget_class->style_set = hildon_button_style_set;
 294
 295     g_object_class_install_property (
 296         gobject_class,
 297         PROP_TITLE,
 298         g_param_spec_string (
 299             "title",
 300             "Title",
 301             "Text of the title label inside the button",
 302             NULL,
 303             G_PARAM_READWRITE));
 304
 305     g_object_class_install_property (
 306         gobject_class,
 307         PROP_VALUE,
 308         g_param_spec_string (
 309             "value",
 310             "Value",
 311             "Text of the value label inside the button",
 312             NULL,
 313             G_PARAM_READWRITE));
 314
 315     g_object_class_install_property (
 316         gobject_class,
 317         PROP_SIZE,
 318         g_param_spec_flags (
 319             "size",
 320             "Size",
 321             "Size request for the button",
 322             HILDON_TYPE_SIZE_TYPE,
 323             HILDON_SIZE_AUTO,
 324             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 325
 326     g_object_class_install_property (
 327         gobject_class,
 328         PROP_ARRANGEMENT,
 329         g_param_spec_enum (
 330             "arrangement",
 331             "Arrangement",
 332             "How the button contents must be arranged",
 333             HILDON_TYPE_BUTTON_ARRANGEMENT,
 334             HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
 335             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 336
 337     g_object_class_install_property (
 338         gobject_class,
 339         PROP_STYLE,
 340         g_param_spec_enum (
 341             "style",
 342             "Style",
 343             "Visual style of the button",
 344             HILDON_TYPE_BUTTON_STYLE,
 345             HILDON_BUTTON_STYLE_NORMAL,
 346             G_PARAM_READWRITE));
 347
 348     gtk_widget_class_install_style_property (
 349         widget_class,
 350         g_param_spec_uint (
 351             "horizontal-spacing",
 352             "Horizontal spacing between labels",
 353             "Horizontal spacing between the title and value labels, when in horizontal mode",
 354             0, G_MAXUINT, 25,
 355             G_PARAM_READABLE));
 356
 357     gtk_widget_class_install_style_property (
 358         widget_class,
 359         g_param_spec_uint (
 360             "vertical-spacing",
 361             "Vertical spacing between labels",
 362             "Vertical spacing between the title and value labels, when in vertical mode",
 363             0, G_MAXUINT, 5,
 364             G_PARAM_READABLE));
 365
 366     g_type_class_add_private (klass, sizeof (HildonButtonPrivate));
 367 }
 368
 369 static void
 370 hildon_button_init                              (HildonButton *self)
 371 {
 372     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (self);
 373
 374     priv->title = GTK_LABEL (gtk_label_new (NULL));
 375     priv->value = GTK_LABEL (gtk_label_new (NULL));
 376     priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
 377     priv->image = NULL;
 378     priv->image_position = GTK_POS_LEFT;
 379     priv->image_xalign = 0.5;
 380     priv->image_yalign = 0.5;
 381     priv->hbox = NULL;
 382     priv->label_box = NULL;
 383     priv->style = HILDON_BUTTON_STYLE_NORMAL;
 384     priv->setting_style = FALSE;
 385
 386     gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
 387     gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
 388
 389     hildon_button_set_style (self, HILDON_BUTTON_STYLE_NORMAL);
 390
 391     gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
 392     gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
 393
 394     g_object_ref_sink (priv->alignment);
 395
 396     /* The labels are not shown automatically, see hildon_button_set_(title|value) */
 397     gtk_widget_set_no_show_all (GTK_WIDGET (priv->title), TRUE);
 398     gtk_widget_set_no_show_all (GTK_WIDGET (priv->value), TRUE);
 399
 400     gtk_button_set_focus_on_click (GTK_BUTTON (self), FALSE);
 401 }
 402
 403 /**
 404  * hildon_button_add_title_size_group:
 405  * @button: a #HildonButton
 406  * @size_group: A #GtkSizeGroup for the button title (main label)
 407  *
 408  * Adds the title label of @button to @size_group.
 409  *
 410  * Since: 2.2
 411  **/
 412 void
 413 hildon_button_add_title_size_group              (HildonButton *button,
 414                                                  GtkSizeGroup *size_group)
 415 {
 416     HildonButtonPrivate *priv;
 417
 418     g_return_if_fail (HILDON_IS_BUTTON (button));
 419     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
 420
 421     priv = HILDON_BUTTON_GET_PRIVATE (button);
 422
 423     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->title));
 424 }
 425
 426 /**
 427  * hildon_button_add_value_size_group:
 428  * @button: a #HildonButton
 429  * @size_group: A #GtkSizeGroup for the button value (secondary label)
 430  *
 431  * Adds the value label of @button to @size_group.
 432  *
 433  * Since: 2.2
 434  **/
 435 void
 436 hildon_button_add_value_size_group              (HildonButton *button,
 437                                                  GtkSizeGroup *size_group)
 438 {
 439     HildonButtonPrivate *priv;
 440
 441     g_return_if_fail (HILDON_IS_BUTTON (button));
 442     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
 443
 444     priv = HILDON_BUTTON_GET_PRIVATE (button);
 445
 446     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->value));
 447 }
 448
 449 /**
 450  * hildon_button_add_image_size_group:
 451  * @button: a #HildonButton
 452  * @size_group: A #GtkSizeGroup for the button image
 453  *
 454  * Adds the image of @button to @size_group. You must add an image
 455  * using hildon_button_set_image() before calling this function.
 456  *
 457  * Since: 2.2
 458  **/
 459 void
 460 hildon_button_add_image_size_group              (HildonButton *button,
 461                                                  GtkSizeGroup *size_group)
 462 {
 463     HildonButtonPrivate *priv;
 464
 465     g_return_if_fail (HILDON_IS_BUTTON (button));
 466     g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
 467
 468     priv = HILDON_BUTTON_GET_PRIVATE (button);
 469
 470     g_return_if_fail (GTK_IS_WIDGET (priv->image));
 471
 472     gtk_size_group_add_widget (size_group, GTK_WIDGET (priv->image));
 473 }
 474
 475 /**
 476  * hildon_button_add_size_groups:
 477  * @button: a #HildonButton
 478  * @title_size_group: A #GtkSizeGroup for the button title (main label), or %NULL
 479  * @value_size_group: A #GtkSizeGroup group for the button value (secondary label), or %NULL
 480  * @image_size_group: A #GtkSizeGroup group for the button image, or %NULL
 481  *
 482  * Convenience function to add title, value and image to size
 483  * groups. %NULL size groups will be ignored.
 484  *
 485  * Since: 2.2
 486  **/
 487 void
 488 hildon_button_add_size_groups                   (HildonButton *button,
 489                                                  GtkSizeGroup *title_size_group,
 490                                                  GtkSizeGroup *value_size_group,
 491                                                  GtkSizeGroup *image_size_group)
 492 {
 493     if (title_size_group)
 494         hildon_button_add_title_size_group (button, title_size_group);
 495
 496     if (value_size_group)
 497         hildon_button_add_value_size_group (button, value_size_group);
 498
 499     if (image_size_group)
 500         hildon_button_add_image_size_group (button, image_size_group);
 501 }
 502
 503 /**
 504  * hildon_button_new:
 505  * @size: Flags to set the size of the button.
 506  * @arrangement: How the labels must be arranged.
 507  *
 508  * Creates a new #HildonButton. To set text in the labels, use
 509  * hildon_button_set_title() and
 510  * hildon_button_set_value(). Alternatively, you can add a custom
 511  * child widget using gtk_container_add().
 512  *
 513  * Returns: a new #HildonButton
 514  *
 515  * Since: 2.2
 516  **/
 517 GtkWidget *
 518 hildon_button_new                               (HildonSizeType          size,
 519                                                  HildonButtonArrangement arrangement)
 520 {
 521     return hildon_button_new_with_text (size, arrangement, NULL, NULL);
 522 }
 523
 524 /**
 525  * hildon_button_new_with_text:
 526  * @size: Flags to set the size of the button.
 527  * @arrangement: How the labels must be arranged.
 528  * @title: Title of the button (main label), or %NULL
 529  * @value: Value of the button (secondary label), or %NULL
 530  *
 531  * Creates a new #HildonButton with two labels, @title and @value.
 532  *
 533  * If you just don't want to use one of the labels, set it to
 534  * %NULL. You can set it to a non-%NULL value at any time later using
 535  * hildon_button_set_title() or hildon_button_set_value() .
 536  *
 537  * Returns: a new #HildonButton
 538  *
 539  * Since: 2.2
 540  **/
 541 GtkWidget *
 542 hildon_button_new_with_text                     (HildonSizeType           size,
 543                                                  HildonButtonArrangement  arrangement,
 544                                                  const gchar             *title,
 545                                                  const gchar             *value)
 546 {
 547     GtkWidget *button;
 548
 549     /* Create widget */
 550     button = g_object_new (HILDON_TYPE_BUTTON,
 551                            "size", size,
 552                            "title", title,
 553                            "value", value,
 554                            "arrangement", arrangement,
 555                            NULL);
 556
 557     return button;
 558 }
 559
 560 static void
 561 hildon_button_set_arrangement                   (HildonButton            *button,
 562                                                  HildonButtonArrangement  arrangement)
 563 {
 564     HildonButtonPrivate *priv;
 565
 566     priv = HILDON_BUTTON_GET_PRIVATE (button);
 567
 568     /* Pack everything */
 569     if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
 570         priv->label_box = gtk_vbox_new (FALSE, 0);
 571         set_logical_font (GTK_WIDGET (button));
 572     } else {
 573         priv->label_box = gtk_hbox_new (FALSE, 0);
 574     }
 575
 576     g_object_ref_sink (priv->label_box);
 577
 578     /* If we pack both labels with (TRUE, TRUE) or (FALSE, FALSE) they
 579      * can be painted outside of the button in some situations, see
 580      * NB#88126 and NB#110689 */
 581     gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->title), FALSE, FALSE, 0);
 582     gtk_box_pack_start (GTK_BOX (priv->label_box), GTK_WIDGET (priv->value), TRUE, TRUE, 0);
 583
 584     hildon_button_construct_child (button);
 585 }
 586
 587 /**
 588  * hildon_button_set_title:
 589  * @button: a #HildonButton
 590  * @title: a new title (main label) for the button, or %NULL
 591  *
 592  * Sets the title (main label) of @button to @title.
 593  *
 594  * This will clear any previously set title.
 595  *
 596  * If @title is set to %NULL or an empty string, the title label will
 597  * be hidden and the value label will be realigned.
 598  *
 599  * Since: 2.2
 600  **/
 601 void
 602 hildon_button_set_title                         (HildonButton *button,
 603                                                  const gchar  *title)
 604 {
 605     HildonButtonPrivate *priv;
 606
 607     g_return_if_fail (HILDON_IS_BUTTON (button));
 608
 609     priv = HILDON_BUTTON_GET_PRIVATE (button);
 610     gtk_label_set_text (priv->title, title);
 611
 612     /* If the button has no title, hide the label so the value is
 613      * properly aligned */
 614     if (title && title[0] != '\0') {
 615         hildon_button_construct_child (button);
 616         gtk_widget_show (GTK_WIDGET (priv->title));
 617     } else {
 618         gtk_widget_hide (GTK_WIDGET (priv->title));
 619     }
 620
 621     g_object_notify (G_OBJECT (button), "title");
 622 }
 623
 624 /**
 625  * hildon_button_set_value:
 626  * @button: a #HildonButton
 627  * @value: a new value (secondary label) for the button, or %NULL
 628  *
 629  * Sets the value (secondary label) of @button to @value.
 630  *
 631  * This will clear any previously set value.
 632  *
 633  * If @value is set to %NULL or an empty string, the value label will
 634  * be hidden and the title label will be realigned.
 635  *
 636  * Since: 2.2
 637  **/
 638 void
 639 hildon_button_set_value                         (HildonButton *button,
 640                                                  const gchar  *value)
 641 {
 642     HildonButtonPrivate *priv;
 643
 644     g_return_if_fail (HILDON_IS_BUTTON (button));
 645
 646     priv = HILDON_BUTTON_GET_PRIVATE (button);
 647     gtk_label_set_text (priv->value, value);
 648
 649     /* If the button has no value, hide the label so the title is
 650      * properly aligned */
 651     if (value && value[0] != '\0') {
 652         hildon_button_construct_child (button);
 653         gtk_widget_show (GTK_WIDGET (priv->value));
 654     } else {
 655         gtk_widget_hide (GTK_WIDGET (priv->value));
 656     }
 657
 658     g_object_notify (G_OBJECT (button), "value");
 659 }
 660
 661 /**
 662  * hildon_button_get_title:
 663  * @button: a #HildonButton
 664  *
 665  * Fetches the text from the main label (title) of @button,
 666  * as set by hildon_button_set_title() or hildon_button_set_text().
 667  * If the label text has not been set the return value will be %NULL.
 668  * This will be the case if you create an empty button with
 669  * hildon_button_new() to use as a container.
 670  *
 671  * Returns: The text of the title label. This string is owned by the
 672  * widget and must not be modified or freed.
 673  *
 674  * Since: 2.2
 675  **/
 676 const gchar *
 677 hildon_button_get_title                         (HildonButton *button)
 678 {
 679     HildonButtonPrivate *priv;
 680
 681     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
 682
 683     priv = HILDON_BUTTON_GET_PRIVATE (button);
 684
 685     return gtk_label_get_text (priv->title);
 686 }
 687
 688 /**
 689  * hildon_button_get_value:
 690  * @button: a #HildonButton
 691  *
 692  * Fetches the text from the secondary label (value) of @button,
 693  * as set by hildon_button_set_value() or hildon_button_set_text().
 694  * If the label text has not been set the return value will be %NULL.
 695  * This will be the case if you create an empty button with hildon_button_new()
 696  * to use as a container.
 697  *
 698  * Returns: The text of the value label. This string is owned by the
 699  * widget and must not be modified or freed.
 700  *
 701  * Since: 2.2
 702  **/
 703 const gchar *
 704 hildon_button_get_value                         (HildonButton *button)
 705 {
 706     HildonButtonPrivate *priv;
 707
 708     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
 709
 710     priv = HILDON_BUTTON_GET_PRIVATE (button);
 711
 712     return gtk_label_get_text (priv->value);
 713 }
 714
 715 /**
 716  * hildon_button_set_text:
 717  * @button: a #HildonButton
 718  * @title: new text for the button title (main label)
 719  * @value: new text for the button value (secondary label)
 720  *
 721  * Convenience function to change both labels of a #HildonButton
 722  *
 723  * Since: 2.2
 724  **/
 725 void
 726 hildon_button_set_text                          (HildonButton *button,
 727                                                  const gchar  *title,
 728                                                  const gchar  *value)
 729 {
 730     hildon_button_set_title (button, title);
 731     hildon_button_set_value (button, value);
 732 }
 733
 734 /**
 735  * hildon_button_set_image:
 736  * @button: a #HildonButton
 737  * @image: a widget to set as the button image
 738  *
 739  * Sets the image of @button to the given widget. The previous image
 740  * (if any) will be removed.
 741  *
 742  * Since: 2.2
 743  **/
 744 void
 745 hildon_button_set_image                         (HildonButton *button,
 746                                                  GtkWidget    *image)
 747 {
 748     HildonButtonPrivate *priv;
 749
 750     g_return_if_fail (HILDON_IS_BUTTON (button));
 751     g_return_if_fail (!image || GTK_IS_WIDGET (image));
 752
 753     priv = HILDON_BUTTON_GET_PRIVATE (button);
 754
 755     /* Return if there's nothing to do */
 756     if (image == priv->image)
 757         return;
 758
 759     if (priv->image && priv->image->parent)
 760         gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
 761
 762     priv->image = image;
 763
 764     hildon_button_construct_child (button);
 765 }
 766
 767 /**
 768  * hildon_button_get_image:
 769  * @button: a #HildonButton
 770  *
 771  * Gets the widget that is currenty set as the image of @button,
 772  * previously set with hildon_button_set_image()
 773  *
 774  * Returns: a #GtkWidget or %NULL in case there is no image
 775  *
 776  * Since: 2.2
 777  **/
 778 GtkWidget *
 779 hildon_button_get_image                         (HildonButton *button)
 780 {
 781     HildonButtonPrivate *priv;
 782
 783     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
 784
 785     priv = HILDON_BUTTON_GET_PRIVATE (button);
 786
 787     return priv->image;
 788 }
 789
 790 /**
 791  * hildon_button_set_image_position:
 792  * @button: a #HildonButton
 793  * @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
 794  *
 795  * Sets the position of the image inside @button. Only %GTK_POS_LEFT
 796  * and %GTK_POS_RIGHT are currently supported.
 797  *
 798  * Since: 2.2
 799  **/
 800 void
 801 hildon_button_set_image_position                (HildonButton    *button,
 802                                                  GtkPositionType  position)
 803 {
 804     HildonButtonPrivate *priv;
 805
 806     g_return_if_fail (HILDON_IS_BUTTON (button));
 807     g_return_if_fail (position == GTK_POS_LEFT || position == GTK_POS_RIGHT);
 808
 809     priv = HILDON_BUTTON_GET_PRIVATE (button);
 810
 811     /* Return if there's nothing to do */
 812     if (priv->image_position == position)
 813         return;
 814
 815     priv->image_position = position;
 816
 817     hildon_button_construct_child (button);
 818 }
 819
 820 /**
 821  * hildon_button_set_alignment:
 822  * @button: a #HildonButton
 823  * @xalign: the horizontal alignment of the contents, from 0 (left) to 1 (right).
 824  * @yalign: the vertical alignment of the contents, from 0 (top) to 1 (bottom).
 825  * @xscale: the amount that the child widget expands horizontally to fill up unused space, from 0 to 1
 826  * @yscale: the amount that the child widget expands vertically to fill up unused space, from 0 to 1
 827  *
 828  * Sets the alignment of the contents of the widget. If you don't need
 829  * to change @xscale or @yscale you can just use
 830  * gtk_button_set_alignment() instead.
 831  *
 832  * Note that for this method to work properly the, child widget of
 833  * @button must be a #GtkAlignment. That's what #HildonButton uses by
 834  * default, so this function will work unless you add a custom widget
 835  * to @button.
 836  *
 837  * Since: 2.2
 838  **/
 839 void
 840 hildon_button_set_alignment                     (HildonButton *button,
 841                                                  gfloat        xalign,
 842                                                  gfloat        yalign,
 843                                                  gfloat        xscale,
 844                                                  gfloat        yscale)
 845 {
 846     HildonButtonPrivate *priv;
 847     GtkWidget *child;
 848
 849     g_return_if_fail (HILDON_IS_BUTTON (button));
 850
 851     priv = HILDON_BUTTON_GET_PRIVATE (button);
 852
 853     child = gtk_bin_get_child (GTK_BIN (button));
 854
 855     /* If the button has no child, use priv->alignment, which is the default one */
 856     if (child == NULL)
 857         child = priv->alignment;
 858
 859     if (GTK_IS_ALIGNMENT (child)) {
 860         gtk_alignment_set (GTK_ALIGNMENT (priv->alignment), xalign, yalign, xscale, yscale);
 861     }
 862 }
 863
 864 /**
 865  * hildon_button_set_title_alignment:
 866  * @button: a #HildonButton
 867  * @xalign: the horizontal alignment of the title label, from 0 (left) to 1 (right).
 868  * @yalign: the vertical alignment of the title label, from 0 (top) to 1 (bottom).
 869  *
 870  * Sets the alignment of the title label. See also
 871  * hildon_button_set_alignment() to set the alignment of the whole
 872  * contents of the button.
 873  *
 874  * Since: 2.2
 875  **/
 876 void
 877 hildon_button_set_title_alignment               (HildonButton *button,
 878                                                  gfloat        xalign,
 879                                                  gfloat        yalign)
 880 {
 881     HildonButtonPrivate *priv;
 882
 883     g_return_if_fail (HILDON_IS_BUTTON (button));
 884
 885     priv = HILDON_BUTTON_GET_PRIVATE (button);
 886
 887     gtk_misc_set_alignment (GTK_MISC (priv->title), xalign, yalign);
 888 }
 889
 890 /**
 891  * hildon_button_set_value_alignment:
 892  * @button: a #HildonButton
 893  * @xalign: the horizontal alignment of the value label, from 0 (left) to 1 (right).
 894  * @yalign: the vertical alignment of the value label, from 0 (top) to 1 (bottom).
 895  *
 896  * Sets the alignment of the value label. See also
 897  * hildon_button_set_alignment() to set the alignment of the whole
 898  * contents of the button.
 899  *
 900  * Since: 2.2
 901  **/
 902 void
 903 hildon_button_set_value_alignment               (HildonButton *button,
 904                                                  gfloat        xalign,
 905                                                  gfloat        yalign)
 906 {
 907     HildonButtonPrivate *priv;
 908
 909     g_return_if_fail (HILDON_IS_BUTTON (button));
 910
 911     priv = HILDON_BUTTON_GET_PRIVATE (button);
 912
 913     gtk_misc_set_alignment (GTK_MISC (priv->value), xalign, yalign);
 914 }
 915
 916 /**
 917  * hildon_button_set_image_alignment:
 918  * @button: a #HildonButton
 919  * @xalign: the horizontal alignment of the image, from 0 (left) to 1 (right).
 920  * @yalign: the vertical alignment of the image, from 0 (top) to 1 (bottom).
 921  *
 922  * Sets the alignment of the image. See also
 923  * hildon_button_set_alignment() to set the alignment of the whole
 924  * contents of the button.
 925  *
 926  * Since: 2.2
 927  **/
 928 void
 929 hildon_button_set_image_alignment               (HildonButton *button,
 930                                                  gfloat        xalign,
 931                                                  gfloat        yalign)
 932 {
 933     HildonButtonPrivate *priv;
 934
 935     g_return_if_fail (HILDON_IS_BUTTON (button));
 936
 937     priv = HILDON_BUTTON_GET_PRIVATE (button);
 938
 939     /* Return if there's nothing to do */
 940     if (priv->image_xalign == xalign && priv->image_yalign == yalign)
 941         return;
 942
 943     priv->image_xalign = xalign;
 944     priv->image_yalign = yalign;
 945
 946     hildon_button_construct_child (button);
 947 }
 948
 949 /**
 950  * hildon_button_set_style:
 951  * @button: A #HildonButton
 952  * @style: A #HildonButtonStyle for @button
 953  *
 954  * Sets the style of @button to @style. This changes the visual
 955  * appearance of the button (colors, font sizes) according to the
 956  * particular style chosen, but the general layout is not altered.
 957  *
 958  * Use %HILDON_BUTTON_STYLE_NORMAL to make it look like a normal
 959  * #HildonButton, or %HILDON_BUTTON_STYLE_PICKER to make it look like
 960  * a #HildonPickerButton.
 961  *
 962  * Since: 2.2
 963  */
 964 void
 965 hildon_button_set_style                         (HildonButton      *button,
 966                                                  HildonButtonStyle  style)
 967 {
 968     HildonButtonPrivate *priv;
 969
 970     g_return_if_fail (HILDON_IS_BUTTON (button));
 971     priv = HILDON_BUTTON_GET_PRIVATE (button);
 972
 973     priv->style = style;
 974     set_logical_color (GTK_WIDGET (button));
 975
 976     g_object_notify (G_OBJECT (button), "style");
 977 }
 978
 979 /**
 980  * hildon_button_get_style:
 981  * @button: A #HildonButton
 982  *
 983  * Gets the visual style of the button.
 984  *
 985  * Returns: a #HildonButtonStyle
 986  *
 987  * Since: 2.2
 988  */
 989 HildonButtonStyle
 990 hildon_button_get_style                         (HildonButton *button)
 991 {
 992     HildonButtonPrivate *priv;
 993
 994     g_return_val_if_fail (HILDON_IS_BUTTON (button), HILDON_BUTTON_STYLE_NORMAL);
 995
 996     priv = HILDON_BUTTON_GET_PRIVATE (button);
 997
 998     return priv->style;
 999 }
1000
1001 static void
1002 hildon_button_construct_child                   (HildonButton *button)
1003 {
1004     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
1005     GtkWidget *child;
1006     gint image_spacing;
1007     const gchar *title, *value;
1008
1009     /* Don't do anything if the button is not constructed yet */
1010     if (G_UNLIKELY (priv->label_box == NULL))
1011         return;
1012
1013     /* Don't do anything if the button has no contents */
1014     title = gtk_label_get_text (priv->title);
1015     value = gtk_label_get_text (priv->value);
1016     if (!priv->image && !title[0] && !value[0])
1017         return;
1018
1019     /* Save a ref to the image, and remove it from its container if necessary */
1020     if (priv->image) {
1021         g_object_ref (priv->image);
1022         if (priv->image->parent != NULL)
1023             gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
1024     }
1025
1026     if (priv->label_box->parent != NULL) {
1027         gtk_container_remove (GTK_CONTAINER (priv->label_box->parent), priv->label_box);
1028     }
1029
1030     /* Remove the child from the container and add priv->alignment */
1031     child = gtk_bin_get_child (GTK_BIN (button));
1032     if (child != NULL && child != priv->alignment) {
1033         gtk_container_remove (GTK_CONTAINER (button), child);
1034         child = NULL;
1035     }
1036
1037     if (child == NULL) {
1038         gtk_container_add (GTK_CONTAINER (button), GTK_WIDGET (priv->alignment));
1039     }
1040
1041     /* Create a new hbox */
1042     if (priv->hbox) {
1043         gtk_container_remove (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
1044     }
1045     gtk_widget_style_get (GTK_WIDGET (button), "image-spacing", &image_spacing, NULL);
1046     priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, image_spacing));
1047     gtk_container_add (GTK_CONTAINER (priv->alignment), GTK_WIDGET (priv->hbox));
1048
1049     /* Pack the image and the alignment in the new hbox */
1050     if (priv->image && priv->image_position == GTK_POS_LEFT)
1051         gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
1052
1053     gtk_box_pack_start (priv->hbox, priv->label_box, TRUE, TRUE, 0);
1054
1055     if (priv->image && priv->image_position == GTK_POS_RIGHT)
1056         gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
1057
1058     /* Set image alignment and remove previously set ref */
1059     if (priv->image) {
1060         gtk_misc_set_alignment (GTK_MISC (priv->image), priv->image_xalign, priv->image_yalign);
1061         g_object_unref (priv->image);
1062     }
1063
1064     /* Show everything */
1065     gtk_widget_show_all (GTK_WIDGET (priv->alignment));
1066 }