vcs.maemo.org Git - hildon/blob - hildon/hildon-entry.c

   1 /*
   2  * This file is a part of hildon
   3  *
   4  * Copyright (C) 2008 Nokia Corporation, all rights reserved.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU Lesser Public License as published by
   8  * the Free Software Foundation; version 2 of the license.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU Lesser Public License for more details.
  14  *
  15  */
  16
  17 /**
  18  * SECTION:hildon-entry
  19  * @short_description: Text entry in the Hildon framework.
  20  *
  21  * The #HildonEntry is text entry derived from the #GtkEntry widget providing
  22  * additional commodities specific to the Hildon framework.
  23  *
  24  * Besides all the features inherited from #GtkEntry, a #HildonEntry
  25  * can also have a placeholder text. This text will be shown if the
  26  * entry is empty and doesn't have the input focus, but it's otherwise
  27  * ignored. Thus, calls to hildon_entry_get_text() will never return
  28  * the placeholder text, not even when it's being displayed.
  29  *
  30  * Although #HildonEntry is derived from #GtkEntry,
  31  * gtk_entry_get_text() and gtk_entry_set_text() must never be used to
  32  * get/set the text in this widget. hildon_entry_get_text() and
  33  * hildon_entry_set_text() must be used instead.
  34  *
  35  * <example>
  36  * <title>Creating a HildonEntry with a placeholder</title>
  37  * <programlisting>
  38  * GtkWidget *
  39  * create_entry (void)
  40  * {
  41  *     GtkWidget *entry;
  42  * <!-- -->
  43  *     entry = hildon_entry_new (HILDON_SIZE_AUTO);
  44  *     hildon_entry_set_placeholder (HILDON_ENTRY (entry), "First name");
  45  * <!-- -->
  46  *     return entry;
  47  * }
  48  * </programlisting>
  49  * </example>
  50  */
  51
  52 #include                                        "hildon-entry.h"
  53 #include                                        "hildon-helper.h"
  54
  55 G_DEFINE_TYPE                                   (HildonEntry, hildon_entry, GTK_TYPE_ENTRY);
  56
  57 enum {
  58     PROP_SIZE = 1
  59 };
  60
  61 #define                                         HILDON_ENTRY_GET_PRIVATE(obj) \
  62                                                 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
  63                                                 HILDON_TYPE_ENTRY, HildonEntryPrivate));
  64
  65 struct                                          _HildonEntryPrivate
  66 {
  67     gchar *placeholder;
  68     gboolean showing_placeholder;
  69 };
  70
  71 static void
  72 set_property                                    (GObject      *object,
  73                                                  guint         prop_id,
  74                                                  const GValue *value,
  75                                                  GParamSpec   *pspec)
  76 {
  77     HildonSizeType size;
  78
  79     switch (prop_id)
  80     {
  81     case PROP_SIZE:
  82         size = g_value_get_flags (value);
  83         /* If this is auto height, default to finger height. */
  84         if (!(size & (HILDON_SIZE_FINGER_HEIGHT | HILDON_SIZE_THUMB_HEIGHT)))
  85           size |= HILDON_SIZE_FINGER_HEIGHT;
  86         hildon_gtk_widget_set_theme_size (GTK_WIDGET (object), size);
  87         break;
  88     default:
  89         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  90         break;
  91     }
  92 }
  93
  94 static void
  95 hildon_entry_show_placeholder (HildonEntry *entry)
  96 {
  97     HildonEntryPrivate *priv = HILDON_ENTRY (entry)->priv;
  98
  99     priv->showing_placeholder = TRUE;
 100     gtk_entry_set_text (GTK_ENTRY (entry), priv->placeholder);
 101     hildon_helper_set_logical_color (GTK_WIDGET (entry),
 102                                      GTK_RC_TEXT, GTK_STATE_NORMAL, "ReversedSecondaryTextColor");
 103 }
 104
 105 static void
 106 hildon_entry_hide_placeholder (HildonEntry *entry, const gchar *text)
 107 {
 108     HildonEntryPrivate *priv = HILDON_ENTRY (entry)->priv;
 109
 110     priv->showing_placeholder = FALSE;
 111     gtk_entry_set_text (GTK_ENTRY (entry), text);
 112     hildon_helper_set_logical_color (GTK_WIDGET (entry),
 113                                      GTK_RC_TEXT, GTK_STATE_NORMAL, "ReversedTextColor");
 114 }
 115
 116 /**
 117  * hildon_entry_set_text:
 118  * @entry: a #HildonEntry
 119  * @text: the new text
 120  *
 121  * Sets the text in @entry to @text, replacing its current contents.
 122  *
 123  * Note that you must never use gtk_entry_set_text() to set the text
 124  * of a #HildonEntry.
 125  *
 126  * Since: 2.2
 127  */
 128 void
 129 hildon_entry_set_text                           (HildonEntry *entry,
 130                                                  const gchar *text)
 131 {
 132     g_return_if_fail (HILDON_IS_ENTRY (entry) && text != NULL);
 133
 134     if (text[0] == '\0' && !GTK_WIDGET_HAS_FOCUS (entry)) {
 135             hildon_entry_show_placeholder (entry);
 136     } else {
 137             hildon_entry_hide_placeholder (entry, text);
 138     }
 139 }
 140
 141 /**
 142  * hildon_entry_get_text:
 143  * @entry: a #HildonEntry
 144  *
 145  * Gets the current text in @entry.
 146  *
 147  * Note that you must never use gtk_entry_get_text() to get the text
 148  * from a #HildonEntry.
 149  *
 150  * Also note that placeholder text (set using
 151  * hildon_entry_set_placeholder()) is never returned. Only text set by
 152  * hildon_entry_set_text() or typed by the user is considered.
 153  *
 154  * Returns: the text in @entry. This text must not be modified or
 155  * freed.
 156  *
 157  * Since: 2.2
 158  */
 159 const gchar *
 160 hildon_entry_get_text                           (HildonEntry *entry)
 161 {
 162     g_return_val_if_fail (HILDON_IS_ENTRY (entry), NULL);
 163
 164     if (entry->priv->showing_placeholder) {
 165         return "";
 166     }
 167
 168     return gtk_entry_get_text (GTK_ENTRY (entry));
 169 }
 170
 171 /**
 172  * hildon_entry_set_placeholder:
 173  * @entry: a #HildonEntry
 174  * @text: the new text
 175  *
 176  * Sets the placeholder text in @entry to @text.
 177  *
 178  * Since: 2.2
 179  */
 180 void
 181 hildon_entry_set_placeholder                    (HildonEntry *entry,
 182                                                  const gchar *text)
 183 {
 184     g_return_if_fail (HILDON_IS_ENTRY (entry) && text != NULL);
 185
 186     g_free (entry->priv->placeholder);
 187     entry->priv->placeholder = g_strdup (text);
 188
 189     /* Show the placeholder if it needs to be updated or if should be shown now. */
 190     if (entry->priv->showing_placeholder ||
 191         (!GTK_WIDGET_HAS_FOCUS (entry) && gtk_entry_get_text (GTK_ENTRY (entry)) [0] == '\0')) {
 192         hildon_entry_show_placeholder (entry);
 193     }
 194 }
 195
 196 /**
 197  * hildon_entry_new:
 198  * @size: The size of the entry
 199  *
 200  * Creates a new entry.
 201  *
 202  * Returns: a new #HildonEntry
 203  *
 204  * Since: 2.2
 205  */
 206 GtkWidget *
 207 hildon_entry_new                                (HildonSizeType size)
 208 {
 209     return g_object_new (HILDON_TYPE_ENTRY, "size", size, NULL);
 210 }
 211
 212 static gboolean
 213 hildon_entry_focus_in_event                     (GtkWidget     *widget,
 214                                                  GdkEventFocus *event)
 215 {
 216     if (HILDON_ENTRY (widget)->priv->showing_placeholder) {
 217             hildon_entry_hide_placeholder (HILDON_ENTRY (widget), "");
 218     }
 219
 220     if (GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_in_event) {
 221         return GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_in_event (widget, event);
 222     } else {
 223         return FALSE;
 224     }
 225 }
 226
 227 static gboolean
 228 hildon_entry_focus_out_event                    (GtkWidget     *widget,
 229                                                  GdkEventFocus *event)
 230 {
 231     if (gtk_entry_get_text (GTK_ENTRY (widget)) [0] == '\0') {
 232         hildon_entry_show_placeholder (HILDON_ENTRY (widget));
 233     }
 234
 235     if (GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_out_event) {
 236         return GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_out_event (widget, event);
 237     } else {
 238         return FALSE;
 239     }
 240 }
 241
 242 static void
 243 hildon_entry_finalize                           (GObject *object)
 244 {
 245     HildonEntryPrivate *priv = HILDON_ENTRY (object)->priv;
 246
 247     g_free (priv->placeholder);
 248
 249     if (G_OBJECT_CLASS (hildon_entry_parent_class)->finalize)
 250         G_OBJECT_CLASS (hildon_entry_parent_class)->finalize (object);
 251 }
 252
 253 static void
 254 hildon_entry_class_init                         (HildonEntryClass *klass)
 255 {
 256     GObjectClass *gobject_class = (GObjectClass *)klass;
 257     GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
 258
 259     gobject_class->set_property = set_property;
 260     gobject_class->finalize = hildon_entry_finalize;
 261     widget_class->focus_in_event = hildon_entry_focus_in_event;
 262     widget_class->focus_out_event = hildon_entry_focus_out_event;
 263
 264     g_object_class_install_property (
 265         gobject_class,
 266         PROP_SIZE,
 267         g_param_spec_flags (
 268             "size",
 269             "Size",
 270             "Size request for the entry",
 271             HILDON_TYPE_SIZE_TYPE,
 272             HILDON_SIZE_AUTO_WIDTH | HILDON_SIZE_FINGER_HEIGHT,
 273             G_PARAM_CONSTRUCT | G_PARAM_WRITABLE));
 274
 275     g_type_class_add_private (klass, sizeof (HildonEntryPrivate));
 276 }
 277
 278 static void
 279 hildon_entry_init                               (HildonEntry *self)
 280 {
 281     self->priv = HILDON_ENTRY_GET_PRIVATE (self);
 282     self->priv->placeholder = g_strdup ("");
 283     self->priv->showing_placeholder = FALSE;
 284 }