gtkentry: Document vfuncs in GtkEntryClass

Clarify that the signal handler vfuncs can be NULL, nothing else can,
and that they all have default implementations.

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

1 files changed, 44 insertions, 0 deletions

diff --git a/gtk/gtkentry.h b/gtk/gtkentry.h
index 57d65a5756..98c5a67e7f 100644
--- a/gtk/gtkentry.h
+++ b/gtk/gtkentry.h
@@ -79,6 +79,48 @@ struct _GtkEntry
   GtkEntryPrivate *priv;
 };
 
+/**
+ * GtkEntryClass:
+ * @parent_class: The parent class.
+ * @populate_popup: Class handler for the #GtkEntry::populate-popup signal. If
+ *   non-%NULL, this will be called to add additional entries to the context
+ *   menu when it is displayed.
+ * @activate: Class handler for the #GtkEntry::activate signal. The default
+ *   implementation calls gtk_window_activate_default() on the entry’s top-level
+ *   window.
+ * @move_cursor: Class handler for the #GtkEntry::move-cursor signal. The
+ *   default implementation specifies the standard #GtkEntry cursor movement
+ *   behavior.
+ * @insert_at_cursor: Class handler for the #GtkEntry::insert-at-cursor signal.
+ *   The default implementation inserts text at the cursor.
+ * @delete_from_cursor: Class handler for the #GtkEntry::delete-from-cursor
+ *   signal. The default implementation deletes the selection or the specified
+ *   number of characters or words.
+ * @backspace: Class handler for the #GtkEntry::backspace signal. The default
+ *   implementation deletes the selection or a single character or word.
+ * @cut_clipboard: Class handler for the #GtkEntry::cut-clipboard signal. The
+ *   default implementation cuts the selection, if one exists.
+ * @copy_clipboard: Class handler for the #GtkEntry::copy-clipboard signal. The
+ *   default implementation copies the selection, if one exists.
+ * @paste_clipboard: Class handler for the #GtkEntry::paste-clipboard signal.
+ *   The default implementation pastes at the current cursor position or over
+ *   the current selection if one exists.
+ * @toggle_overwrite: Class handler for the #GtkEntry::toggle-overwrite signal.
+ *   The default implementation toggles overwrite mode and blinks the cursor.
+ * @get_text_area_size: Calculate the size of the text area, which is its
+ *   allocated width and requested height, minus space for margins and borders.
+ *   This virtual function must be non-%NULL.
+ * @get_frame_size: Calculate the size of the text area frame, which is its
+ *   allocated width and requested height, minus space for margins and borders,
+ *   and taking baseline and text height into account. This virtual function
+ *   must be non-%NULL.
+ *
+ * Class structure for #GtkEntry. All virtual functions have a default
+ * implementation. Derived classes may set the virtual function pointers for the
+ * signal handlers to %NULL, but must keep @get_text_area_size and
+ * @get_frame_size non-%NULL; either use the default implementation, or provide
+ * a custom one.
+ */
 struct _GtkEntryClass
 {
   GtkWidgetClass parent_class;
@@ -117,6 +159,8 @@ struct _GtkEntryClass
 			       gint           *width,
 			       gint           *height);
 
+  /*< private >*/
+
   /* Padding for future expansion */
   void (*_gtk_reserved1)      (void);
   void (*_gtk_reserved2)      (void);