CellEditable: Clarify doc on lifecycle of editable

* Note in the intro that we're really thinking about temporary widgets
* Mention a gotcha regarding GtkEntry and how ::focus-out stops editing
* Give some examples of what you'd want to do in ::editing-done
* Be a bit more precise about what ::remove-widget represents
* Summarise the lifecycle between Renderer/Editable in .start_editing()
* Emphasise again there that this should be viewed as a temporary widget

https://gitlab.gnome.org/GNOME/gtk/issues/154

diff --git a/gtk/gtkcelleditable.c b/gtk/gtkcelleditable.c
index adf7418224119513aa0a6c89669ec574fe32da2c..3d81b1bf000797cb06a4ea3dae09392af313bf19 100644 (file)
--- a/gtk/gtkcelleditable.c
+++ b/gtk/gtkcelleditable.c
@@ -22,7 +22,8 @@
  * @See_also: #GtkEntry, #GtkCellRenderer
  *
  * The #GtkCellEditable interface must be implemented for widgets to be usable
- * when editing the contents of a #GtkTreeView cell.
+ * to edit the contents of a #GtkTreeView cell. It provides a way to specify how
+ * temporary widgets should be configured for editing, get the new value, etc.
  */
 
 #include "config.h"
@@ -59,7 +60,9 @@ gtk_cell_editable_default_init (GtkCellEditableInterface *iface)
    *
    * Implementations of #GtkCellEditable are responsible for
    * emitting this signal when they are done editing, e.g.
-   * #GtkEntry is emitting it when the user presses Enter.
+   * #GtkEntry emits this signal when the user presses Enter. Typical things to
+   * do in a handler for ::editing-done are to capture the edited value,
+   * disconnect the @cell_editable from signals on the #GtkCellRenderer, etc.
    *
    * gtk_cell_editable_editing_done() is a convenience method
    * for emitting #GtkCellEditable::editing-done.
@@ -77,7 +80,8 @@ gtk_cell_editable_default_init (GtkCellEditableInterface *iface)
    * @cell_editable: the object on which the signal was emitted
    *
    * This signal is meant to indicate that the cell is finished
-   * editing, and the widget may now be destroyed.
+   * editing, and the @cell_editable widget is being removed and may
+   * subsequently be destroyed.
    *
    * Implementations of #GtkCellEditable are responsible for
    * emitting this signal when they are done editing. It must
@@ -104,6 +108,15 @@ gtk_cell_editable_default_init (GtkCellEditableInterface *iface)
  *   %NULL if editing was initiated programmatically
  * 
  * Begins editing on a @cell_editable.
+ *
+ * The #GtkCellRenderer for the cell creates and returns a #GtkCellEditable from
+ * gtk_cell_renderer_start_editing(), configured for the #GtkCellRenderer type.
+ *
+ * gtk_cell_editable_start_editing() can then set up @cell_editable suitably for
+ * editing a cell, e.g. making the Esc key emit #GtkCellEditable::editing-done.
+ *
+ * Note that the @cell_editable is created on-demand for the current edit; its
+ * lifetime is temporary and does not persist across other edits and/or cells.
  **/
 void
 gtk_cell_editable_start_editing (GtkCellEditable *cell_editable,