Add documentation

Document the new API and properties, and their interaction with
existing properties.

https://bugzilla.gnome.org/show_bug.cgi?id=651244

diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index cf09ed94b0e21cbc59305751eb38184935b6f435..97c8a89f9d6e17c8ff4bc45d71821c82bce565c9 100644 (file)
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -1081,6 +1081,12 @@ gtk_entry_get_icon_tooltip_markup
 gtk_entry_set_icon_drag_source
 gtk_entry_get_current_icon_drag_source
 gtk_entry_get_icon_area
+GtkInputPurpose
+gtk_entry_set_input_purpose
+gtk_entry_get_input_purpose
+GtkInputHints
+gtk_entry_set_input_hints
+gtk_entry_get_input_hints
 
 <SUBSECTION Standard>
 GTK_ENTRY
@@ -3672,6 +3678,10 @@ gtk_text_view_get_accepts_tab
 gtk_text_view_get_default_attributes
 gtk_text_view_im_context_filter_keypress
 gtk_text_view_reset_im_context
+gtk_text_view_set_input_purpose
+gtk_text_view_get_input_purpose
+gtk_text_view_set_input_hints
+gtk_text_view_get_input_hints
 GTK_TEXT_VIEW_PRIORITY_VALIDATE
 <SUBSECTION Standard>
 GTK_TEXT_VIEW

diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index de43d97b9a229db1e921cb97ba490f53dedabf17..f82512cd4c14dcb8b66b54ef215284895916dfc1 100644 (file)
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -1361,6 +1361,20 @@ gtk_entry_class_init (GtkEntryClass *class)
                                                         GTK_TYPE_ENTRY_COMPLETION,
                                                         GTK_PARAM_READWRITE));
 
+  /**
+   * GtkEntry:input-purpose:
+   *
+   * The purpose of this text field.
+   *
+   * This property can be used by on-screen keyboards and other input
+   * methods to adjust their behaviour.
+   *
+   * Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or
+   * %GTK_INPUT_PURPOSE_PIN is independent from setting
+   * #GtkEntry:visibility.
+   *
+   * Since: 3.6
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_INPUT_PURPOSE,
                                    g_param_spec_enum ("input-purpose",
@@ -1370,6 +1384,14 @@ gtk_entry_class_init (GtkEntryClass *class)
                                                       GTK_INPUT_PURPOSE_FREE_FORM,
                                                       G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+  /**
+   * GtkEntry:input-hints:
+   *
+   * Additional hints (beyond #GtkEntry:input-purpose) that
+   * allow input methods to fine-tune their behaviour.
+   *
+   * Since: 3.6
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_INPUT_HINTS,
                                    g_param_spec_flags ("input-hints",
@@ -6941,14 +6963,19 @@ gtk_entry_set_text (GtkEntry    *entry,
  * @visible: %TRUE if the contents of the entry are displayed
  *           as plaintext
  *
- * Sets whether the contents of the entry are visible or not. 
- * When visibility is set to %FALSE, characters are displayed 
- * as the invisible char, and will also appear that way when 
+ * Sets whether the contents of the entry are visible or not.
+ * When visibility is set to %FALSE, characters are displayed
+ * as the invisible char, and will also appear that way when
  * the text in the entry widget is copied elsewhere.
  *
  * By default, GTK+ picks the best invisible character available
  * in the current font, but it can be changed with
  * gtk_entry_set_invisible_char().
+ *
+ * Note that you probably want to set #GtkEntry:input-purpose
+ * to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to
+ * inform input methods about the purpose of this entry,
+ * in addition to setting visibility to %FALSE.
  */
 void
 gtk_entry_set_visibility (GtkEntry *entry,
@@ -10333,6 +10360,17 @@ _gtk_entry_set_is_cell_renderer (GtkEntry *entry,
   entry->priv->is_cell_renderer = is_cell_renderer;
 }
 
+/**
+ * gtk_entry_set_input_purpose:
+ * @entry: a #GtkEntry
+ * @purpose: the purpose
+ *
+ * Sets the #GtkEntry:input-purpose property which
+ * can be used by on-screen keyboards and other input
+ * methods to adjust their behaviour.
+ *
+ * Since: 3.6
+ */
 void
 gtk_entry_set_input_purpose (GtkEntry        *entry,
                              GtkInputPurpose  purpose)
@@ -10350,6 +10388,14 @@ gtk_entry_set_input_purpose (GtkEntry        *entry,
   }
 }
 
+/**
+ * gtk_entry_get_input_purpose:
+ * @entry: a #GtkEntry
+ *
+ * Gets the value of the #GtkEntry:input-purpose property.
+ *
+ * Since: 3.6
+ */
 GtkInputPurpose
 gtk_entry_get_input_purpose (GtkEntry *entry)
 {
@@ -10364,6 +10410,16 @@ gtk_entry_get_input_purpose (GtkEntry *entry)
   return purpose;
 }
 
+/**
+ * gtk_entry_set_input_hints:
+ * @entry: a #GtkEntry
+ * @hints: the hints
+ *
+ * Sets the #GtkEntry:input-hints property, which
+ * allows input methods to fine-tune their behaviour.
+ *
+ * Since: 3.6
+ */
 void
 gtk_entry_set_input_hints (GtkEntry      *entry,
                            GtkInputHints  hints)
@@ -10381,6 +10437,14 @@ gtk_entry_set_input_hints (GtkEntry      *entry,
   }
 }
 
+/**
+ * gtk_entry_get_input_hints:
+ * @entry: a #GtkEntry
+ *
+ * Gets the value of the #GtkEntry:input-hints property.
+ *
+ * Since: 3.6
+ */
 GtkInputHints
 gtk_entry_get_input_hints (GtkEntry *entry)
 {

diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 59379260a40eeccfd9933dbd891b87bc82ea1971..2f27ff840e4491fe47a199e2f3ced129ab2877aa 100644 (file)
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -796,6 +796,16 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
                                                          NULL,
                                                          GTK_PARAM_READWRITE));
 
+  /**
+   * GtkTextView:input-purpose:
+   *
+   * The purpose of this text field.
+   *
+   * This property can be used by on-screen keyboards and other input
+   * methods to adjust their behaviour.
+   *
+   * Since: 3.6
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_INPUT_PURPOSE,
                                    g_param_spec_enum ("input-purpose",
@@ -805,6 +815,14 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
                                                       GTK_INPUT_PURPOSE_FREE_FORM,
                                                       G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+  /**
+   * GtkTextView:input-hints:
+   *
+   * Additional hints (beyond #GtkTextView:input-purpose) that
+   * allow input methods to fine-tune their behaviour.
+   *
+   * Since: 3.6
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_INPUT_HINTS,
                                    g_param_spec_flags ("input-hints",
@@ -9668,6 +9686,18 @@ gtk_text_view_move_visually (GtkTextView *text_view,
   return gtk_text_layout_move_iter_visually (text_view->priv->layout, iter, count);
 }
 
+/**
+ * gtk_text_view_set_input_purpose:
+ * @text_vew: a #GtkTextView
+ * @purpose: the purpose
+ *
+ * Sets the #GtkTextView:input-purpose property which
+ * can be used by on-screen keyboards and other input
+ * methods to adjust their behaviour.
+ *
+ * Since: 3.6
+ */
+
 void
 gtk_text_view_set_input_purpose (GtkTextView     *text_view,
                                  GtkInputPurpose  purpose)
@@ -9685,6 +9715,15 @@ gtk_text_view_set_input_purpose (GtkTextView     *text_view,
   }
 }
 
+/**
+ * gtk_text_view_get_input_purpose:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the value of the #GtkTextView:input-purpose property.
+ *
+ * Since: 3.6
+ */
+
 GtkInputPurpose
 gtk_text_view_get_input_purpose (GtkTextView *text_view)
 {
@@ -9699,6 +9738,17 @@ gtk_text_view_get_input_purpose (GtkTextView *text_view)
   return purpose;
 }
 
+/**
+ * gtk_text_view_set_input_hints:
+ * @text_view: a #GtkTextView
+ * @hints: the hints
+ *
+ * Sets the #GtkTextView:input-hints property, which
+ * allows input methods to fine-tune their behaviour.
+ *
+ * Since: 3.6
+ */
+
 void
 gtk_text_view_set_input_hints (GtkTextView   *text_view,
                                GtkInputHints  hints)
@@ -9716,6 +9766,15 @@ gtk_text_view_set_input_hints (GtkTextView   *text_view,
   }
 }
 
+/**
+ * gtk_text_view_get_input_hints:
+ * @text_view: a #GtkTextView
+ *
+ * Gets the value of the #GtkTextView:input-hints property.
+ *
+ * Since: 3.6
+ */
+
 GtkInputHints
 gtk_text_view_get_input_hints (GtkTextView *text_view)
 {