docs: move documentation to inline comments: GtkEntry

docs/reference/gtk/tmpl/.gitignore

@@ -12,6 +12,7 @@ gtkcombobox.sgml
 gtkcomboboxentry.sgml
 gtkcontainer.sgml
 gtkeditable.sgml
+gtkentry.sgml
 gtkentrybuffer.sgml
 gtkhbox.sgml
 gtkiconview.sgml

gtk/gtkentry.c

@@ -66,6 +66,51 @@
 #include "gtkiconfactory.h"
 #include "gtkicontheme.h"
 
+
+/**
+ * SECTION:gtkentry
+ * @Short_description: A single line text entry field
+ * @Title: GtkEntry
+ * @See_also: #GtkTextView, #GtkEntryCompletion
+ *
+ * The #GtkEntry widget is a single line text entry
+ * widget. A fairly large set of key bindings are supported
+ * by default. If the entered text is longer than the allocation
+ * of the widget, the widget will scroll so that the cursor
+ * position is visible.
+ *
+ * When using an entry for passwords and other sensitive information,
+ * it can be put into "password mode" using gtk_entry_set_visibility().
+ * In this mode, entered text is displayed using a 'invisible' character.
+ * By default, GTK+ picks the best invisible character that is available
+ * in the current font, but it can be changed with
+ * gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning
+ * when Caps Lock or input methods might interfere with entering text in
+ * a password entry. The warning can be turned off with the
+ * #GtkEntry:caps-lock-warning property.
+ *
+ * Since 2.16, GtkEntry has the ability to display progress or activity
+ * information behind the text. To make an entry display such information,
+ * use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step().
+ *
+ * Additionally, GtkEntry can show icons at either side of the entry. These
+ * icons can be activatable by clicking, can be set up as drag source and
+ * can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
+ * one of the various other functions that set an icon from a stock id, an
+ * icon name or a pixbuf. To trigger an action when the user clicks an icon,
+ * connect to the #GtkEntry::icon-press signal. To allow DND operations
+ * from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on
+ * an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
+ * for markup.
+ *
+ * Note that functionality or information that is only available by clicking
+ * on an icon in an entry may not be accessible at all to users which are not
+ * able to use a mouse or other pointing device. It is therefore recommended
+ * that any such functionality should also be available by other means, e.g.
+ * via the context menu of the entry.
+ */
+
+
 #define GTK_ENTRY_COMPLETION_KEY "gtk-entry-completion-key"
 
 #define MIN_ENTRY_WIDTH  150

gtk/gtkentry.h

@@ -54,6 +54,15 @@ G_BEGIN_DECLS
 #define GTK_IS_ENTRY_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_ENTRY))
 #define GTK_ENTRY_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_ENTRY, GtkEntryClass))
 
+/**
+ * GtkEntryIconPosition:
+ * @GTK_ENTRY_ICON_PRIMARY: At the beginning of the entry (depending on the text direction).
+ * @GTK_ENTRY_ICON_SECONDARY: At the end of the entry (depending on the text direction).
+ *
+ * Specifies the side of the entry at which an icon is placed.
+ *
+ * Since: 2.16
+ */
 typedef enum
 {
   GTK_ENTRY_ICON_PRIMARY,