vcs.maemo.org Git - hildon/blob - 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. To change the alignment
  34  * of the labels, use gtk_button_set_alignment()
  35  */
  36
  37 #include                                        "hildon-button.h"
  38 #include                                        "hildon-enum-types.h"
  39
  40 G_DEFINE_TYPE                                   (HildonButton, hildon_button, GTK_TYPE_BUTTON);
  41
  42 #define                                         HILDON_BUTTON_GET_PRIVATE(obj) \
  43                                                 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
  44                                                 HILDON_TYPE_BUTTON, HildonButtonPrivate));
  45
  46 typedef struct                                  _HildonButtonPrivate HildonButtonPrivate;
  47
  48 struct                                          _HildonButtonPrivate
  49 {
  50     GtkLabel *title;
  51     GtkLabel *value;
  52     GtkBox *hbox;
  53     GtkWidget *alignment;
  54     GtkWidget *image;
  55     GtkPositionType image_position;
  56 };
  57
  58 enum {
  59     PROP_TITLE = 1,
  60     PROP_VALUE,
  61     PROP_SIZE,
  62     PROP_ARRANGEMENT
  63 };
  64
  65 static void
  66 hildon_button_set_arrangement                   (HildonButton            *button,
  67                                                  HildonButtonArrangement  arrangement);
  68
  69 static void
  70 hildon_button_construct_child                   (HildonButton *button);
  71
  72 static void
  73 hildon_button_set_property                      (GObject      *object,
  74                                                  guint         prop_id,
  75                                                  const GValue *value,
  76                                                  GParamSpec   *pspec)
  77 {
  78     HildonButton *button = HILDON_BUTTON (object);
  79
  80     switch (prop_id)
  81     {
  82     case PROP_TITLE:
  83         hildon_button_set_title (button, g_value_get_string (value));
  84         break;
  85     case PROP_VALUE:
  86         hildon_button_set_value (button, g_value_get_string (value));
  87         break;
  88     case PROP_SIZE:
  89         hildon_helper_set_theme_size (GTK_WIDGET (button), g_value_get_flags (value));
  90         break;
  91     case PROP_ARRANGEMENT:
  92         hildon_button_set_arrangement (button, g_value_get_enum (value));
  93         break;
  94     default:
  95         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  96         break;
  97     }
  98 }
  99
 100 static void
 101 hildon_button_get_property                      (GObject    *object,
 102                                                  guint       prop_id,
 103                                                  GValue     *value,
 104                                                  GParamSpec *pspec)
 105 {
 106     HildonButton *button = HILDON_BUTTON (object);
 107     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
 108
 109     switch (prop_id)
 110     {
 111     case PROP_TITLE:
 112         g_value_set_string (value, gtk_label_get_text (priv->title));
 113         break;
 114     case PROP_VALUE:
 115         g_value_set_string (value, gtk_label_get_text (priv->value));
 116         break;
 117     default:
 118         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 119         break;
 120     }
 121 }
 122
 123 static void
 124 hildon_button_class_init                        (HildonButtonClass *klass)
 125 {
 126     GObjectClass *gobject_class = (GObjectClass *)klass;
 127     GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
 128
 129     gobject_class->set_property = hildon_button_set_property;
 130     gobject_class->get_property = hildon_button_get_property;
 131
 132     g_object_class_install_property (
 133         gobject_class,
 134         PROP_TITLE,
 135         g_param_spec_string (
 136             "title",
 137             "Title",
 138             "Text of the title label inside the button",
 139             NULL,
 140             G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 141
 142     g_object_class_install_property (
 143         gobject_class,
 144         PROP_VALUE,
 145         g_param_spec_string (
 146             "value",
 147             "Value",
 148             "Text of the value label inside the button",
 149             NULL,
 150             G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 151
 152     g_object_class_install_property (
 153         gobject_class,
 154         PROP_SIZE,
 155         g_param_spec_flags (
 156             "size",
 157             "Size",
 158             "Size request for the button",
 159             HILDON_TYPE_SIZE_TYPE,
 160             HILDON_SIZE_AUTO,
 161             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 162
 163     g_object_class_install_property (
 164         gobject_class,
 165         PROP_ARRANGEMENT,
 166         g_param_spec_enum (
 167             "arrangement",
 168             "Arrangement",
 169             "How the button contents must be arranged",
 170             HILDON_TYPE_BUTTON_ARRANGEMENT,
 171             HILDON_BUTTON_ARRANGEMENT_HORIZONTAL,
 172             G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 173
 174     gtk_widget_class_install_style_property (
 175         widget_class,
 176         g_param_spec_uint (
 177             "horizontal-spacing",
 178             "Horizontal spacing between labels",
 179             "Horizontal spacing between the title and value labels, when in horizontal mode",
 180             0, G_MAXUINT, 25,
 181             G_PARAM_READABLE));
 182
 183     gtk_widget_class_install_style_property (
 184         widget_class,
 185         g_param_spec_uint (
 186             "vertical-spacing",
 187             "Vertical spacing between labels",
 188             "Vertical spacing between the title and value labels, when in vertical mode",
 189             0, G_MAXUINT, 5,
 190             G_PARAM_READABLE));
 191
 192     g_type_class_add_private (klass, sizeof (HildonButtonPrivate));
 193 }
 194
 195 static void
 196 hildon_button_init                              (HildonButton *self)
 197 {
 198     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (self);
 199
 200     priv->title = GTK_LABEL (gtk_label_new (NULL));
 201     priv->value = GTK_LABEL (gtk_label_new (NULL));
 202     priv->alignment = gtk_alignment_new (0.5, 0.5, 0, 0);
 203     priv->image = NULL;
 204     priv->image_position = GTK_POS_LEFT;
 205     priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, 0));
 206
 207     gtk_widget_set_name (GTK_WIDGET (priv->title), "hildon-button-title");
 208     gtk_widget_set_name (GTK_WIDGET (priv->value), "hildon-button-value");
 209
 210     gtk_misc_set_alignment (GTK_MISC (priv->title), 0, 0.5);
 211     gtk_misc_set_alignment (GTK_MISC (priv->value), 0, 0.5);
 212
 213     gtk_box_pack_start (priv->hbox, priv->alignment, TRUE, TRUE, 0);
 214
 215     /* The labels are not shown automatically, see hildon_button_set_(title|value) */
 216     gtk_widget_set_no_show_all (GTK_WIDGET (priv->title), TRUE);
 217     gtk_widget_set_no_show_all (GTK_WIDGET (priv->value), TRUE);
 218 }
 219
 220 /**
 221  * hildon_button_set_size_groups:
 222  * @button: a #HildonButton
 223  * @title_size_group: A #GtkSizeGroup for the button title (main label), or %NULL
 224  * @value_size_group: A #GtkSizeGroup group for the button value (secondary label), or %NULL
 225  *
 226  * Adds the title and value labels of @button to @title_size_group and
 227  * @value_size_group respectively. %NULL size groups will be ignored.
 228  **/
 229 void
 230 hildon_button_set_size_groups                   (HildonButton *button,
 231                                                  GtkSizeGroup *title_size_group,
 232                                                  GtkSizeGroup *value_size_group)
 233 {
 234     HildonButtonPrivate *priv;
 235
 236     g_return_if_fail (HILDON_IS_BUTTON (button));
 237     g_return_if_fail (!title_size_group || GTK_IS_SIZE_GROUP (title_size_group));
 238     g_return_if_fail (!value_size_group || GTK_IS_SIZE_GROUP (value_size_group));
 239
 240     priv = HILDON_BUTTON_GET_PRIVATE (button);
 241
 242     if (title_size_group)
 243         gtk_size_group_add_widget (title_size_group, GTK_WIDGET (priv->title));
 244
 245     if (value_size_group)
 246         gtk_size_group_add_widget (value_size_group, GTK_WIDGET (priv->value));
 247 }
 248
 249 /**
 250  * hildon_button_new:
 251  * @size: Flags to set the size of the button.
 252  * @arrangement: How the labels must be arranged.
 253  *
 254  * Creates a new #HildonButton. To add a child widget use gtk_container_add().
 255  *
 256  * Returns: a new #HildonButton
 257  **/
 258 GtkWidget *
 259 hildon_button_new                               (HildonSizeType          size,
 260                                                  HildonButtonArrangement arrangement)
 261 {
 262     return hildon_button_new_full (size, arrangement, NULL, NULL, NULL, NULL);
 263 }
 264
 265 /**
 266  * hildon_button_new_with_text:
 267  * @size: Flags to set the size of the button.
 268  * @arrangement: How the labels must be arranged.
 269  * @title: Title of the button (main label), or %NULL
 270  * @value: Value of the button (secondary label), or %NULL
 271  *
 272  * Creates a new #HildonButton with two labels, @title and @value.
 273  *
 274  * If you just don't want to use one of the labels, set it to
 275  * %NULL. You can set it to a non-%NULL value at any time later.
 276  *
 277  * Returns: a new #HildonButton
 278  **/
 279 GtkWidget *
 280 hildon_button_new_with_text                     (HildonSizeType           size,
 281                                                  HildonButtonArrangement  arrangement,
 282                                                  const gchar             *title,
 283                                                  const gchar             *value)
 284 {
 285     return hildon_button_new_full (size, arrangement, title, value, NULL, NULL);
 286 }
 287
 288 /**
 289  * hildon_button_new_full:
 290  * @size: Flags to set the size of the button.
 291  * @arrangement: How the labels must be arranged.
 292  * @title: Title of the button (main label)
 293  * @value: Value of the button (secondary label), or %NULL
 294  * @title_size_group: a #GtkSizeGroup for the @title label, or %NULL
 295  * @value_size_group: a #GtkSizeGroup for the @value label, or %NULL
 296  *
 297  * Creates a new #HildonButton with two labels, @title and @value, and
 298  * their respective size groups.
 299  *
 300  * If you just don't want to use one of the labels, set it to
 301  * %NULL. You can set it to a non-%NULL value at any time later.
 302  *
 303  * @title and @value will be added to @title_size_group and
 304  * @value_size_group, respectively, if present.
 305  *
 306  * Returns: a new #HildonButton
 307  **/
 308 GtkWidget *
 309 hildon_button_new_full                          (HildonSizeType           size,
 310                                                  HildonButtonArrangement  arrangement,
 311                                                  const gchar             *title,
 312                                                  const gchar             *value,
 313                                                  GtkSizeGroup            *title_size_group,
 314                                                  GtkSizeGroup            *value_size_group)
 315 {
 316     GtkWidget *button;
 317
 318     /* Create widget */
 319     button = g_object_new (HILDON_TYPE_BUTTON,
 320                            "size", size,
 321                            "arrangement", arrangement,
 322                            "title", title,
 323                            "value", value,
 324                            "name", "hildon-button",
 325                            NULL);
 326     /* Set size groups */
 327     if (title_size_group || value_size_group)
 328         hildon_button_set_size_groups (HILDON_BUTTON (button), title_size_group, value_size_group);
 329
 330     return button;
 331 }
 332
 333 static void
 334 hildon_button_set_arrangement                   (HildonButton            *button,
 335                                                  HildonButtonArrangement  arrangement)
 336 {
 337     GtkWidget *box;
 338     HildonButtonPrivate *priv;
 339     guint horizontal_spacing;
 340     guint vertical_spacing;
 341
 342     priv = HILDON_BUTTON_GET_PRIVATE (button);
 343
 344     /* Pack everything */
 345     gtk_widget_style_get (GTK_WIDGET (button),
 346                           "horizontal-spacing", &horizontal_spacing,
 347                           "vertical-spacing", &vertical_spacing,
 348                           NULL);
 349
 350     if (arrangement == HILDON_BUTTON_ARRANGEMENT_VERTICAL) {
 351         box = gtk_vbox_new (FALSE, vertical_spacing);
 352     } else {
 353         box = gtk_hbox_new (FALSE, horizontal_spacing);
 354     }
 355
 356     gtk_box_pack_start (GTK_BOX (box), GTK_WIDGET (priv->title), TRUE, TRUE, 0);
 357     gtk_box_pack_start (GTK_BOX (box), GTK_WIDGET (priv->value), TRUE, TRUE, 0);
 358
 359     gtk_container_add (GTK_CONTAINER (priv->alignment), box);
 360 }
 361
 362 /**
 363  * hildon_button_set_title:
 364  * @button: a #HildonButton
 365  * @title: a new title (main label) for the button, or %NULL
 366  *
 367  * Sets the title (main label) of @button to @title.
 368  *
 369  * This will clear the previously set title.
 370  *
 371  * If @title is set to %NULL, the title label will be hidden and the
 372  * value label will be realigned.
 373  **/
 374 void
 375 hildon_button_set_title                         (HildonButton *button,
 376                                                  const gchar  *title)
 377 {
 378     HildonButtonPrivate *priv;
 379
 380     g_return_if_fail (HILDON_IS_BUTTON (button));
 381
 382     priv = HILDON_BUTTON_GET_PRIVATE (button);
 383     gtk_label_set_text (priv->title, title);
 384
 385     /* If the button has no title, hide the label so the value is
 386      * properly aligned */
 387     if (title) {
 388         hildon_button_construct_child (button);
 389         gtk_widget_show (GTK_WIDGET (priv->title));
 390     } else {
 391         gtk_widget_hide (GTK_WIDGET (priv->title));
 392     }
 393
 394     g_object_notify (G_OBJECT (button), "title");
 395 }
 396
 397 /**
 398  * hildon_button_set_value:
 399  * @button: a #HildonButton
 400  * @value: a new value (secondary label) for the button, or %NULL
 401  *
 402  * Sets the value (secondary label) of @button to @value.
 403  *
 404  * This will clear the previously set value.
 405  *
 406  * If @value is set to %NULL, the value label will be hidden and the
 407  * title label will be realigned.
 408  *
 409  **/
 410 void
 411 hildon_button_set_value                         (HildonButton *button,
 412                                                  const gchar  *value)
 413 {
 414     HildonButtonPrivate *priv;
 415
 416     g_return_if_fail (HILDON_IS_BUTTON (button));
 417
 418     priv = HILDON_BUTTON_GET_PRIVATE (button);
 419     gtk_label_set_text (priv->value, value);
 420
 421     /* If the button has no value, hide the label so the title is
 422      * properly aligned */
 423     if (value) {
 424         hildon_button_construct_child (button);
 425         gtk_widget_show (GTK_WIDGET (priv->value));
 426     } else {
 427         gtk_widget_hide (GTK_WIDGET (priv->value));
 428     }
 429
 430     g_object_notify (G_OBJECT (button), "value");
 431 }
 432
 433 /**
 434  * hildon_button_get_title:
 435  * @button: a #HildonButton
 436  *
 437  * Gets the text from the main label (title) of @button, or %NULL if
 438  * none has been set.
 439  *
 440  * Returns: The text of the title label. This string is owned by the
 441  * widget and must not be modified or freed.
 442  **/
 443 const gchar *
 444 hildon_button_get_title                         (HildonButton *button)
 445 {
 446     HildonButtonPrivate *priv;
 447
 448     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
 449
 450     priv = HILDON_BUTTON_GET_PRIVATE (button);
 451
 452     return gtk_label_get_text (priv->title);
 453 }
 454
 455 /**
 456  * hildon_button_get_value:
 457  * @button: a #HildonButton
 458  *
 459  * Gets the text from the secondary label (value) of @button, or %NULL
 460  * if none has been set.
 461  *
 462  * Returns: The text of the value label. This string is owned by the
 463  * widget and must not be modified or freed.
 464  **/
 465 const gchar *
 466 hildon_button_get_value                         (HildonButton *button)
 467 {
 468     HildonButtonPrivate *priv;
 469
 470     g_return_val_if_fail (HILDON_IS_BUTTON (button), NULL);
 471
 472     priv = HILDON_BUTTON_GET_PRIVATE (button);
 473
 474     return gtk_label_get_text (priv->value);
 475 }
 476
 477 /**
 478  * hildon_button_set_text:
 479  * @button: a #HildonButton
 480  * @title: new text for the button title (main label)
 481  * @value: new text for the button value (secondary label)
 482  *
 483  * Convenience function to change both labels of a #HildonButton
 484  **/
 485 void
 486 hildon_button_set_text                          (HildonButton *button,
 487                                                  const gchar  *title,
 488                                                  const gchar  *value)
 489 {
 490     hildon_button_set_title (button, title);
 491     hildon_button_set_value (button, value);
 492 }
 493
 494 /**
 495  * hildon_button_set_image:
 496  * @button: a #HildonButton
 497  * @image: a widget to set as the button image
 498  *
 499  * Sets the image of @button to the given widget. The previous image
 500  * (if any) will be removed.
 501  **/
 502 void
 503 hildon_button_set_image                         (HildonButton *button,
 504                                                  GtkWidget    *image)
 505 {
 506     HildonButtonPrivate *priv;
 507
 508     g_return_if_fail (HILDON_IS_BUTTON (button));
 509     g_return_if_fail (!image || GTK_IS_WIDGET (image));
 510
 511     priv = HILDON_BUTTON_GET_PRIVATE (button);
 512
 513     /* Return if there's nothing to do */
 514     if (image == priv->image)
 515         return;
 516
 517     if (priv->image && priv->image->parent)
 518         gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
 519
 520     priv->image = image;
 521
 522     hildon_button_construct_child (button);
 523 }
 524
 525 /**
 526  * hildon_button_set_image_position:
 527  * @button: a #HildonButton
 528  * @position: the position of the image (%GTK_POS_LEFT or %GTK_POS_RIGHT)
 529  *
 530  * Sets the position of the image inside @button. Only left and right
 531  * are supported.
 532  **/
 533 void
 534 hildon_button_set_image_position                (HildonButton    *button,
 535                                                  GtkPositionType  position)
 536 {
 537     HildonButtonPrivate *priv;
 538
 539     g_return_if_fail (HILDON_IS_BUTTON (button));
 540     g_return_if_fail (position == GTK_POS_LEFT || position == GTK_POS_RIGHT);
 541
 542     priv = HILDON_BUTTON_GET_PRIVATE (button);
 543
 544     /* Return if there's nothing to do */
 545     if (priv->image_position == position)
 546         return;
 547
 548     priv->image_position = position;
 549
 550     hildon_button_construct_child (button);
 551 }
 552
 553 static void
 554 hildon_button_construct_child                   (HildonButton *button)
 555 {
 556     HildonButtonPrivate *priv = HILDON_BUTTON_GET_PRIVATE (button);
 557     GtkWidget *child = gtk_bin_get_child (GTK_BIN (button));
 558
 559     /* Save a ref to the alignment if necessary */
 560     if (priv->alignment->parent != NULL) {
 561         g_object_ref (priv->alignment);
 562         gtk_container_remove (GTK_CONTAINER (priv->alignment->parent), priv->alignment);
 563     }
 564
 565     /* Save a ref to the image if necessary */
 566     if (priv->image && priv->image->parent != NULL) {
 567         g_object_ref (priv->image);
 568         gtk_container_remove (GTK_CONTAINER (priv->image->parent), priv->image);
 569     }
 570
 571     /* Remove the child from the container */
 572     if (child != NULL) {
 573         gtk_container_remove (GTK_CONTAINER (button), child);
 574     }
 575
 576     /* Pack the image and the alignment in a new hbox */
 577     priv->hbox = GTK_BOX (gtk_hbox_new (FALSE, 0));
 578
 579     if (priv->image && priv->image_position == GTK_POS_LEFT)
 580         gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
 581
 582     gtk_box_pack_start (priv->hbox, priv->alignment, TRUE, TRUE, 0);
 583
 584     if (priv->image && priv->image_position == GTK_POS_RIGHT)
 585         gtk_box_pack_start (priv->hbox, priv->image, FALSE, FALSE, 0);
 586
 587     /* Add the hbox to the button */
 588     gtk_container_add (GTK_CONTAINER (button), GTK_WIDGET (priv->hbox));
 589
 590     gtk_widget_show_all (GTK_WIDGET (priv->hbox));
 591 }