From b48fbcbb7c32484cdca2b7e6d67f959654889051 Mon Sep 17 00:00:00 2001 From: Daniel Boles Date: Tue, 17 Apr 2018 18:27:23 +0100 Subject: [PATCH] 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 --- gtk/gtkcelleditable.c | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/gtk/gtkcelleditable.c b/gtk/gtkcelleditable.c index f58f34ee7a..11a08b909b 100644 --- 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" @@ -61,7 +62,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. @@ -79,7 +82,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 @@ -106,6 +110,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,