vcs.maemo.org Git - hildon/blob - src/hildon-helper.c

   1 /*
   2  * This file is a part of hildon
   3  *
   4  * Copyright (C) 2005, 2006 Nokia Corporation, all rights reserved.
   5  *
   6  * Contact: Michael Dominic Kostrzewa <michael.kostrzewa@nokia.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public License
  10  * as published by the Free Software Foundation; version 2.1 of
  11  * the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  21  * 02110-1301 USA
  22  *
  23  */
  24
  25 /**
  26  * SECTION:hildon-helper
  27  * @short_description: A collection of usefull utilities and functions.
  28  *
  29  * Hildon provides some helper functions that can be used for commonly
  30  * performed tasks and functionality blocks. This includes operations
  31  * on widget styles and probing functions for touch events.
  32  *
  33  */
  34
  35 #ifdef                                          HAVE_CONFIG_H
  36 #include                                        <config.h>
  37 #endif
  38
  39 #include                                        <gtk/gtk.h>
  40 #include                                        "hildon-helper.h"
  41 #include                                        "hildon-banner.h"
  42
  43 #define                                         HILDON_FINGER_PRESSURE_THRESHOLD 0.4
  44
  45 #define                                         HILDON_FINGER_BUTTON 8
  46
  47 #define                                         HILDON_FINGER_ALT_BUTTON 1
  48
  49 #define                                         HILDON_FINGER_ALT_MASK GDK_MOD4_MASK
  50
  51 #define                                         HILDON_FINGER_SIMULATE_BUTTON 2
  52
  53 struct                                          _HildonLogicalElement
  54 {
  55     gboolean is_color;                          /* If FALSE, it's a logical font def */
  56     GtkRcFlags rc_flags;
  57     GtkStateType state;
  58     gchar *logical_color_name;
  59     gchar *logical_font_name;
  60 } typedef                                       HildonLogicalElement;
  61
  62 static void
  63 hildon_logical_element_list_free                (GSList *list)
  64 {
  65     GSList *iterator = list;
  66
  67     while (iterator) {
  68         HildonLogicalElement *element = (HildonLogicalElement *) iterator->data;
  69
  70         g_free (element->logical_color_name);
  71         g_free (element->logical_font_name);
  72         g_slice_free (HildonLogicalElement, element);
  73
  74         iterator = iterator->next;
  75     }
  76
  77     /* Free the list itself */
  78     g_slist_free (list);
  79 }
  80
  81 static GQuark
  82 hildon_helper_logical_data_quark                (void)
  83 {
  84     static GQuark quark = 0;
  85
  86     if (G_UNLIKELY (quark == 0))
  87         quark = g_quark_from_static_string ("hildon-logical-data");
  88
  89     return quark;
  90 }
  91
  92 static HildonLogicalElement*
  93 attach_blank_element                            (GtkWidget *widget,
  94                                                  GSList **style_list)
  95 {
  96     gboolean first = (*style_list == NULL) ? TRUE : FALSE;
  97
  98     HildonLogicalElement *element = g_slice_new (HildonLogicalElement);
  99
 100     element->is_color = FALSE;
 101     element->rc_flags = 0;
 102     element->state = 0;
 103     element->logical_color_name = NULL;
 104     element->logical_font_name = NULL;
 105
 106     *style_list = g_slist_append (*style_list, element);
 107
 108     if (first)
 109         g_object_set_qdata_full (G_OBJECT (widget), hildon_helper_logical_data_quark (), *style_list, (GDestroyNotify) hildon_logical_element_list_free);
 110
 111     return element;
 112 }
 113
 114 static GSList*
 115 attach_new_font_element                         (GtkWidget *widget,
 116                                                  const gchar *font_name)
 117 {
 118     GSList *style_list = g_object_get_qdata (G_OBJECT (widget), hildon_helper_logical_data_quark ());
 119     HildonLogicalElement *element = NULL;
 120
 121     /* Try to find an element that already sets a font */
 122     GSList *iterator = style_list;
 123     while (iterator) {
 124         element = (HildonLogicalElement *) iterator->data;
 125
 126         if (element->is_color == FALSE) {
 127             /* Reusing ... */
 128             g_free (element->logical_font_name);
 129             element->logical_font_name = g_strdup (font_name);
 130             return style_list;
 131         }
 132
 133         iterator = iterator->next;
 134     }
 135
 136     /* It was not found so we need to create a new one and attach it */
 137     element = attach_blank_element (widget, &style_list);
 138     element->is_color = FALSE;
 139     element->logical_font_name = g_strdup (font_name);
 140     return style_list;
 141 }
 142
 143 static GSList*
 144 attach_new_color_element                        (GtkWidget *widget,
 145                                                  GtkRcFlags flags,
 146                                                  GtkStateType state,
 147                                                  const gchar *color_name)
 148 {
 149     GSList *style_list = g_object_get_qdata (G_OBJECT (widget), hildon_helper_logical_data_quark ());
 150     HildonLogicalElement *element = NULL;
 151
 152     /* Try to find an element that has same flags and state */
 153     GSList *iterator = style_list;
 154     while (iterator) {
 155         element = (HildonLogicalElement *) iterator->data;
 156
 157         if (element->rc_flags == flags &&
 158             element->state == state &&
 159             element->is_color == TRUE) {
 160             /* Reusing ... */
 161             element->logical_color_name = g_strdup (color_name);
 162             return style_list;
 163         }
 164
 165         iterator = iterator->next;
 166     }
 167
 168     /* It was not found so we need to create a new one and attach it */
 169     element = attach_blank_element (widget, &style_list);
 170     element->is_color = TRUE;
 171     element->state = state;
 172     element->rc_flags = flags;
 173     element->logical_color_name = g_strdup (color_name);
 174     return style_list;
 175 }
 176
 177 static void
 178 hildon_change_style_recursive_from_list         (GtkWidget *widget,
 179                                                  GtkStyle *prev_style,
 180                                                  GSList *list)
 181 {
 182     g_assert (GTK_IS_WIDGET (widget));
 183
 184     /* Change the style for child widgets */
 185     if (GTK_IS_CONTAINER (widget)) {
 186         GList *iterator, *children;
 187         children = gtk_container_get_children (GTK_CONTAINER (widget));
 188         for (iterator = children; iterator != NULL; iterator = g_list_next (iterator))
 189             hildon_change_style_recursive_from_list (GTK_WIDGET (iterator->data), prev_style, list);
 190         g_list_free (children);
 191     }
 192
 193     /* gtk_widget_modify_*() emit "style_set" signals, so if we got here from
 194        "style_set" signal, we need to block this function from being called
 195        again or we get into inifinite loop.
 196
 197     FIXME: Compiling with gcc > 3.3 and -pedantic won't allow
 198     conversion between function and object pointers. GLib API however
 199     requires an object pointer for a function, so we have to work
 200     around this.
 201     See http://bugzilla.gnome.org/show_bug.cgi?id=310175
 202     */
 203
 204     G_GNUC_EXTENSION
 205         g_signal_handlers_block_matched (G_OBJECT (widget), G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_FUNC,
 206                 g_signal_lookup ("style_set", G_TYPE_FROM_INSTANCE (widget)),
 207                 0, NULL,
 208                 (gpointer) hildon_change_style_recursive_from_list,
 209                 NULL);
 210
 211     /* We iterate over all list elements and apply each style
 212      * specification. */
 213
 214     GSList *iterator = list;
 215     while (iterator) {
 216
 217         HildonLogicalElement *element = (HildonLogicalElement *) iterator->data;
 218
 219         if (element->is_color == TRUE) {
 220
 221             /* Changing logical color */
 222             GdkColor color;
 223             gtk_widget_ensure_style (widget);
 224             if (gtk_style_lookup_color (widget->style, element->logical_color_name, &color) == TRUE) {
 225
 226                 switch (element->rc_flags)
 227                 {
 228                     case GTK_RC_FG:
 229                         gtk_widget_modify_fg (widget, element->state, &color);
 230                         break;
 231
 232                     case GTK_RC_BG:
 233                         gtk_widget_modify_bg (widget, element->state, &color);
 234                         break;
 235
 236                     case GTK_RC_TEXT:
 237                         gtk_widget_modify_text (widget, element->state, &color);
 238                         break;
 239
 240                     case GTK_RC_BASE:
 241                         gtk_widget_modify_base (widget, element->state, &color);
 242                         break;
 243                 }
 244             }
 245         } else {
 246
 247             /* Changing logical font */
 248             GtkStyle *font_style = gtk_rc_get_style_by_paths (gtk_settings_get_default (), element->logical_font_name, NULL, G_TYPE_NONE);
 249             if (font_style != NULL) {
 250                 PangoFontDescription *font_desc = font_style->font_desc;
 251
 252                 if (font_desc != NULL)
 253                     gtk_widget_modify_font (widget, font_desc);
 254             }
 255         }
 256
 257         iterator = iterator->next;
 258     }
 259
 260     /* FIXME: Compilation workaround for gcc > 3.3 + -pedantic again */
 261
 262     G_GNUC_EXTENSION
 263         g_signal_handlers_unblock_matched (G_OBJECT (widget), G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_FUNC,
 264                 g_signal_lookup ("style_set", G_TYPE_FROM_INSTANCE (widget)),
 265                 0, NULL,
 266                 (gpointer) hildon_change_style_recursive_from_list,
 267                 NULL);
 268 }
 269
 270 /**
 271  * hildon_helper_event_button_is_finger:
 272  * @event: A @gtkeventbutton to check
 273  *
 274  * Checks if the given button event is a finger event.
 275  *
 276  * return value : TRUE if the event is a finger event.
 277  **/
 278 gboolean
 279 hildon_helper_event_button_is_finger            (GdkEventButton *event)
 280 {
 281     gdouble pressure;
 282
 283     if (gdk_event_get_axis ((GdkEvent*) event, GDK_AXIS_PRESSURE, &pressure) &&
 284         pressure > HILDON_FINGER_PRESSURE_THRESHOLD)
 285         return TRUE;
 286
 287     if (event->button == HILDON_FINGER_BUTTON)
 288         return TRUE;
 289
 290     if (event->button == HILDON_FINGER_ALT_BUTTON &&
 291         event->state & HILDON_FINGER_ALT_MASK)
 292         return TRUE;
 293
 294     if (event->button == HILDON_FINGER_SIMULATE_BUTTON)
 295         return TRUE;
 296
 297     return FALSE;
 298 }
 299
 300 /**
 301  * hildon_helper_set_logical_font:
 302  * @widget : a @gtkwidget to assign this logical font for.
 303  * @logicalfontname : a gchar* with the logical font name to assign to the widget.
 304  *
 305  * This function assigns a defined logical font to the @widget and all its child widgets.
 306  * it also connects to the "style_set" signal which will retrieve & assign the new font
 307  * for the given logical name each time the theme is changed.
 308  * The returned signal id can be used to disconnect the signal.
 309  * When calling multiple times the previous signal (obtained by calling this function) is disconnected
 310  * automatically and should not be used.
 311  *
 312  * return value : the signal id that is triggered every time theme is changed. 0 if font set failed.
 313  **/
 314 gulong
 315 hildon_helper_set_logical_font                  (GtkWidget *widget,
 316                                                  const gchar *logicalfontname)
 317 {
 318     gulong signum = 0;
 319     GSList *list;
 320
 321     g_return_val_if_fail (GTK_IS_WIDGET (widget), 0);
 322     g_return_val_if_fail (logicalfontname != NULL, 0);
 323
 324     list = attach_new_font_element (widget, logicalfontname);
 325
 326     /* Disconnects the previously connected signals. That calls the closure notify
 327      * and effectively disposes the allocated data (hildon_logical_data_free) */
 328     g_signal_handlers_disconnect_matched (G_OBJECT (widget), G_SIGNAL_MATCH_FUNC,
 329                                           0, 0, NULL,
 330                                           G_CALLBACK (hildon_change_style_recursive_from_list), NULL);
 331
 332     /* Change the font now */
 333     hildon_change_style_recursive_from_list (widget, NULL, list);
 334
 335     /* Connect to "style_set" so that the font gets changed whenever theme changes. */
 336     signum = g_signal_connect_data (G_OBJECT (widget), "style_set",
 337                                     G_CALLBACK (hildon_change_style_recursive_from_list),
 338                                     list, NULL, 0);
 339
 340     return signum;
 341 }
 342
 343 static GQuark
 344 hildon_helper_insensitive_message_quark         (void)
 345 {
 346     static GQuark quark = 0;
 347
 348     if (G_UNLIKELY (quark == 0))
 349         quark = g_quark_from_static_string ("hildon-insensitive-message");
 350
 351     return quark;
 352 }
 353
 354 static void
 355 show_insensitive_message                        (GtkWidget *widget,
 356                                                  gpointer user_data)
 357 {
 358     gchar *message = NULL;
 359
 360     g_assert (GTK_IS_WIDGET (widget));
 361
 362     message = (gchar*) g_object_get_qdata (G_OBJECT (widget),
 363             hildon_helper_insensitive_message_quark ());
 364
 365     if (message)
 366         hildon_banner_show_information (widget, NULL, message);
 367 }
 368
 369
 370 /**
 371  * hildon_helper_set_insensitive_message
 372  * @widget : A @GtkWidget to assign a banner to
 373  * @message: A message to display to the user
 374  *
 375  * This function assigns an insensitive message to a @widget. When the @widget is
 376  * in an insensitive state and the user activates it, the @message will be displayed
 377  * using a standard @HildonBanner.
 378  *
 379  **/
 380 void
 381 hildon_helper_set_insensitive_message           (GtkWidget *widget,
 382                                                  const gchar *message)
 383 {
 384     g_return_if_fail (GTK_IS_WIDGET (widget));
 385
 386     /* Clean up any previous instance of the insensitive message */
 387     g_signal_handlers_disconnect_matched (G_OBJECT (widget), G_SIGNAL_MATCH_FUNC,
 388                                           0, 0, NULL,
 389                                           G_CALLBACK (show_insensitive_message), NULL);
 390
 391     /* We need to dup the string because the pointer might not be valid when the
 392      insensitive-press signal callback is executed */
 393     g_object_set_qdata_full (G_OBJECT (widget), hildon_helper_insensitive_message_quark (),
 394                              (gpointer)g_strdup (message),
 395                              g_free);
 396
 397     if (message != NULL) {
 398       g_signal_connect (G_OBJECT (widget), "insensitive-press",
 399                         G_CALLBACK (show_insensitive_message), NULL);
 400     }
 401 }
 402
 403 /**
 404  * hildon_helper_set_insensitive_messagef
 405  * @widget : A @GtkWidget to assign a banner to
 406  * @format : a printf-like format string
 407  * @varargs : arguments for the format string
 408  *
 409  * A version of hildon_helper_set_insensitive_message with string formatting.
 410  *
 411  **/
 412 void
 413 hildon_helper_set_insensitive_messagef          (GtkWidget *widget,
 414                                                  const gchar *format,
 415                                                  ...)
 416 {
 417     g_return_if_fail (GTK_IS_WIDGET (widget));
 418
 419     gchar *message;
 420     va_list args;
 421
 422     va_start (args, format);
 423     message = g_strdup_vprintf (format, args);
 424     va_end (args);
 425
 426     hildon_helper_set_insensitive_message (widget, message);
 427
 428     g_free (message);
 429 }
 430
 431 /**
 432  * hildon_helper_set_logical_color:
 433  * @widget : A @GtkWidget to assign this logical font for.
 434  * @rcflags : @GtkRcFlags enumeration defining whether to assign to FG, BG, TEXT or BASE style.
 435  * @state : @GtkStateType indicating to which state to assign the logical color
 436  * @logicalcolorname : A gchar* with the logical font name to assign to the widget.
 437  *
 438  * This function assigns a defined logical color to the @widget and all it's child widgets.
 439  * It also connects to the "style_set" signal which will retrieve & assign the new color
 440  * for the given logical name each time the theme is changed.
 441  * The returned signal id can be used to disconnect the signal.
 442  * When calling multiple times the previous signal (obtained by calling this function) is disconnected
 443  * automatically and should not be used.
 444  *
 445  * Example : If the style you want to modify is bg[NORMAL] then set rcflags to GTK_RC_BG and state to GTK_STATE_NORMAL.
 446  *
 447  * Return value : The signal id that is triggered every time theme is changed. 0 if color set failed.
 448  **/
 449 gulong
 450 hildon_helper_set_logical_color                 (GtkWidget *widget,
 451                                                  GtkRcFlags rcflags,
 452                                                  GtkStateType state,
 453                                                  const gchar *logicalcolorname)
 454 {
 455     gulong signum = 0;
 456     GSList *list = NULL;
 457
 458     g_return_val_if_fail (GTK_IS_WIDGET (widget), 0);
 459     g_return_val_if_fail (logicalcolorname != NULL, 0);
 460
 461     list = attach_new_color_element (widget, rcflags, state, logicalcolorname);
 462
 463     /* Disconnects the previously connected signals. */
 464     g_signal_handlers_disconnect_matched (G_OBJECT (widget), G_SIGNAL_MATCH_FUNC,
 465                                           0, 0, NULL,
 466                                           G_CALLBACK (hildon_change_style_recursive_from_list), NULL);
 467
 468     /* Change the colors now */
 469     hildon_change_style_recursive_from_list (widget, NULL, list);
 470
 471     /* Connect to "style_set" so that the colors gets changed whenever theme */
 472     signum = g_signal_connect_data (G_OBJECT (widget), "style_set",
 473                                     G_CALLBACK (hildon_change_style_recursive_from_list),
 474                                     list, NULL, 0);
 475
 476     return signum;
 477 }
 478
 479
 480 /**
 481  *
 482  * hildon_helper_set_thumb_scrollbar
 483  * @win: A @GtkScrolledWindow to use as target
 484  * @thumb: TRUE to enable the thumb scrollbar, FALSE to disable
 485  *
 486  * This function enables a thumb scrollbar on a given scrolled window. It'll convert the
 487  * existing normal scrollbar into a larger, finger-usable scrollbar that works without a stylus.
 488  * As fingerable list rows are fairly high, consider using the whole available vertical space
 489  * of your application for the content in order to have as many rows as possible
 490  * visible on the screen at once.
 491  *
 492  * Finger-Sized scrollbar should always be used together with finger-sized content.
 493  **/
 494 void
 495 hildon_helper_set_thumb_scrollbar               (GtkScrolledWindow *win,
 496                                                  gboolean thumb)
 497 {
 498     g_return_if_fail (GTK_IS_SCROLLED_WINDOW (win));
 499
 500     if (win->vscrollbar)
 501         gtk_widget_set_name (win->vscrollbar, (thumb) ? "hildon-thumb-scrollbar" : NULL);
 502 }
 503
 504
 505
 506