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