2008-09-08 Alberto Garcia <agarcia@igalia.com>

* src/hildon-entry.c: Updated HildonButton documentation.

diff --git a/ChangeLog b/ChangeLog
index eafe660..b785495 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2008-09-08  Alberto Garcia  <agarcia@igalia.com>
 
+       * src/hildon-entry.c: Updated HildonButton documentation.
+
+2008-09-08  Alberto Garcia  <agarcia@igalia.com>
+
        * src/hildon-button.c (hildon_button_set_arrangement): Pack the
        button value label with (FALSE, FALSE) to prevent NB#88126 from
        being triggered.

diff --git a/src/hildon-entry.c b/src/hildon-entry.c
index 2e3911f..f56a618 100644 (file)
--- a/src/hildon-entry.c
+++ b/src/hildon-entry.c
@@ -21,8 +21,19 @@
  * @short_description: Widget representing a text entry in the Hildon framework.
  *
  * The #HildonEntry is a GTK widget which represents a text entry. It
- * is derived from the GtkEntry widget and provides additional
+ * is derived from the #GtkEntry widget and provides additional
  * commodities specific to the Hildon framework.
+ *
+ * Besides all the features inherited from #GtkEntry, a #HildonEntry
+ * can also have a placeholder text. This text will be shown if the
+ * entry is empty and doesn't have the input focus, but it's otherwise
+ * ignored. Thus, calls to hildon_entry_get_text() will never return
+ * the placeholder text, not even when it's being displayed.
+ *
+ * Although #HildonEntry is derived from #GtkEntry,
+ * gtk_entry_get_text() and gtk_entry_set_text() must never be used to
+ * get/set the text in this widget. hildon_entry_get_text() and
+ * hildon_entry_set_text() must be used instead.
  */
 
 #include                                        "hildon-entry.h"
@@ -31,6 +42,16 @@ G_DEFINE_TYPE                                   (HildonEntry, hildon_entry, GTK_
 
 static const gchar *placeholder_widget_name     = "hildon-entry-placeholder";
 
+/**
+ * hildon_entry_set_text:
+ * @entry: a #HildonEntry
+ * @text: the new text
+ *
+ * Sets the text in @entry to @text, replacing its current contents.
+ *
+ * Note that you must never use gtk_entry_set_text() to set the text
+ * of a #HildonEntry.
+ */
 void
 hildon_entry_set_text                           (HildonEntry *entry,
                                                  const gchar *text)
@@ -42,6 +63,22 @@ hildon_entry_set_text                           (HildonEntry *entry,
     gtk_widget_set_name (GTK_WIDGET (entry), NULL);
 }
 
+/**
+ * hildon_entry_get_text:
+ * @entry: a #HildonEntry
+ *
+ * Gets the current text in @entry.
+ *
+ * Note that you must never use gtk_entry_get_text() to get the text
+ * from a #HildonEntry.
+ *
+ * Also note that placeholder text (set using
+ * hildon_entry_set_placeholder()) is never returned. Only text set by
+ * hildon_entry_set_text() or typed by the user is considered.
+ *
+ * Returns: the text in @entry. This text must not be modified or
+ * freed.
+ */
 const gchar *
 hildon_entry_get_text                           (HildonEntry *entry)
 {
@@ -54,6 +91,13 @@ hildon_entry_get_text                           (HildonEntry *entry)
     return gtk_entry_get_text (GTK_ENTRY (entry));
 }
 
+/**
+ * hildon_entry_set_placeholder:
+ * @entry: a #HildonEntry
+ * @text: the new text
+ *
+ * Sets the placeholder text in @entry to @text.
+ */
 void
 hildon_entry_set_placeholder                    (HildonEntry *entry,
                                                  const gchar *text)
@@ -65,6 +109,14 @@ hildon_entry_set_placeholder                    (HildonEntry *entry,
     gtk_entry_set_text (GTK_ENTRY (entry), text);
 }
 
+/**
+ * hildon_entry_new:
+ * @size: The size of the entry
+ *
+ * Creates a new entry.
+ *
+ * Returns: a new #HildonEntry
+ */
 GtkWidget *
 hildon_entry_new                                (HildonSizeType size)
 {