vcs.maemo.org Git - hildon/blob - src/hildon-entry.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-entry
  21  * @short_description: Widget representing a text entry in the Hildon framework.
  22  *
  23  * The #HildonEntry is a GTK widget which represents a text entry. It
  24  * is derived from the #GtkEntry widget and provides additional
  25  * commodities specific to the Hildon framework.
  26  *
  27  * Besides all the features inherited from #GtkEntry, a #HildonEntry
  28  * can also have a placeholder text. This text will be shown if the
  29  * entry is empty and doesn't have the input focus, but it's otherwise
  30  * ignored. Thus, calls to hildon_entry_get_text() will never return
  31  * the placeholder text, not even when it's being displayed.
  32  *
  33  * Although #HildonEntry is derived from #GtkEntry,
  34  * gtk_entry_get_text() and gtk_entry_set_text() must never be used to
  35  * get/set the text in this widget. hildon_entry_get_text() and
  36  * hildon_entry_set_text() must be used instead.
  37  */
  38
  39 #include                                        "hildon-entry.h"
  40
  41 G_DEFINE_TYPE                                   (HildonEntry, hildon_entry, GTK_TYPE_ENTRY);
  42
  43 static const gchar *placeholder_widget_name     = "hildon-entry-placeholder";
  44
  45 /**
  46  * hildon_entry_set_text:
  47  * @entry: a #HildonEntry
  48  * @text: the new text
  49  *
  50  * Sets the text in @entry to @text, replacing its current contents.
  51  *
  52  * Note that you must never use gtk_entry_set_text() to set the text
  53  * of a #HildonEntry.
  54  */
  55 void
  56 hildon_entry_set_text                           (HildonEntry *entry,
  57                                                  const gchar *text)
  58 {
  59     g_return_if_fail (HILDON_IS_ENTRY (entry));
  60
  61     gtk_entry_set_text (GTK_ENTRY (entry), text);
  62
  63     gtk_widget_set_name (GTK_WIDGET (entry), NULL);
  64 }
  65
  66 /**
  67  * hildon_entry_get_text:
  68  * @entry: a #HildonEntry
  69  *
  70  * Gets the current text in @entry.
  71  *
  72  * Note that you must never use gtk_entry_get_text() to get the text
  73  * from a #HildonEntry.
  74  *
  75  * Also note that placeholder text (set using
  76  * hildon_entry_set_placeholder()) is never returned. Only text set by
  77  * hildon_entry_set_text() or typed by the user is considered.
  78  *
  79  * Returns: the text in @entry. This text must not be modified or
  80  * freed.
  81  */
  82 const gchar *
  83 hildon_entry_get_text                           (HildonEntry *entry)
  84 {
  85     g_return_val_if_fail (HILDON_IS_ENTRY (entry), NULL);
  86
  87     if (g_str_equal (gtk_widget_get_name (GTK_WIDGET (entry)), placeholder_widget_name)) {
  88         return "";
  89     }
  90
  91     return gtk_entry_get_text (GTK_ENTRY (entry));
  92 }
  93
  94 /**
  95  * hildon_entry_set_placeholder:
  96  * @entry: a #HildonEntry
  97  * @text: the new text
  98  *
  99  * Sets the placeholder text in @entry to @text.
 100  */
 101 void
 102 hildon_entry_set_placeholder                    (HildonEntry *entry,
 103                                                  const gchar *text)
 104 {
 105     g_return_if_fail (HILDON_IS_ENTRY (entry));
 106
 107     gtk_widget_set_name (GTK_WIDGET (entry), placeholder_widget_name);
 108
 109     gtk_entry_set_text (GTK_ENTRY (entry), text);
 110 }
 111
 112 /**
 113  * hildon_entry_new:
 114  * @size: The size of the entry
 115  *
 116  * Creates a new entry.
 117  *
 118  * Returns: a new #HildonEntry
 119  */
 120 GtkWidget *
 121 hildon_entry_new                                (HildonSizeType size)
 122 {
 123     GtkWidget *entry = g_object_new (HILDON_TYPE_ENTRY, NULL);
 124
 125     hildon_gtk_widget_set_theme_size (entry, size);
 126
 127     return entry;
 128 }
 129
 130 static gboolean
 131 hildon_entry_focus_in_event                     (GtkWidget     *widget,
 132                                                  GdkEventFocus *event)
 133 {
 134     if (g_str_equal (gtk_widget_get_name (widget), placeholder_widget_name)) {
 135         hildon_entry_set_text (HILDON_ENTRY (widget), "");
 136     }
 137     if (GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_in_event) {
 138         return GTK_WIDGET_CLASS (hildon_entry_parent_class)->focus_in_event (widget, event);
 139     } else {
 140         return FALSE;
 141     }
 142 }
 143
 144 static void
 145 hildon_entry_class_init                         (HildonEntryClass *klass)
 146 {
 147     GtkWidgetClass *widget_class = (GtkWidgetClass *)klass;
 148
 149     widget_class->focus_in_event = hildon_entry_focus_in_event;
 150 }
 151
 152 static void
 153 hildon_entry_init                               (HildonEntry *self)
 154 {
 155 }