Commit 60b4a386 authored by Daniel Boles's avatar Daniel Boles

Merge branch...

Merge branch '154-documentation-lifecycle-of-editables-inside-gtkcellrenderers-is-not-clear' into 'gtk-3-22'

Resolve "Documentation: Lifecycle of Editables inside GtkCellRenderers is not clear"

See merge request !97
parents b19c524a 7f846ce7
Pipeline #9107 passed with stage
in 7 minutes and 19 seconds
......@@ -17,13 +17,13 @@
/**
* SECTION:gtkcelleditable
* @Short_description: Interface for widgets which can are used for editing
* cells
* @Short_description: Interface for widgets that can be used for editing cells
* @Title: GtkCellEditable
* @See_also: #GtkEntry, #GtkCellRenderer
* @See_also: #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"
......@@ -62,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.
......@@ -80,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
......@@ -103,11 +106,19 @@ gtk_cell_editable_default_init (GtkCellEditableInterface *iface)
/**
* gtk_cell_editable_start_editing:
* @cell_editable: A #GtkCellEditable
* @event: (allow-none): A #GdkEvent, or %NULL
* @event: (nullable): The #GdkEvent that began the editing process, or
* %NULL if editing was initiated programmatically
*
* Begins editing on a @cell_editable. @event is the #GdkEvent that began
* the editing process. It may be %NULL, in the instance that editing was
* initiated through programatic means.
* 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,
......
......@@ -29,7 +29,7 @@
* SECTION:gtkcellrenderer
* @Short_description: An object for rendering a single cell
* @Title: GtkCellRenderer
* @See_also: #GtkCellRendererText, #GtkCellRendererPixbuf, #GtkCellRendererToggle
* @See_also: #GtkCellEditable
*
* The #GtkCellRenderer is a base class of a set of objects used for
* rendering a cell to a #cairo_t. These objects are used primarily by
......@@ -56,7 +56,8 @@
* “activatable” like #GtkCellRendererToggle,
* which toggles when it gets activated by a mouse click, or it can be
* “editable” like #GtkCellRendererText, which
* allows the user to edit the text using a #GtkEntry.
* allows the user to edit the text using a widget implementing the
* #GtkCellEditable interface, e.g. #GtkEntry.
* To make a cell renderer activatable or editable, you have to
* implement the #GtkCellRendererClass.activate or
* #GtkCellRendererClass.start_editing virtual functions, respectively.
......@@ -244,6 +245,9 @@ gtk_cell_renderer_class_init (GtkCellRendererClass *class)
* on @editable, e.g. adding a #GtkEntryCompletion or setting
* up additional columns in a #GtkComboBox.
*
* See gtk_cell_editable_start_editing() for information on the lifecycle of
* the @editable and a way to do setup that doesn’t depend on the @renderer.
*
* Note that GTK+ doesn't guarantee that cell renderers will
* continue to use the same kind of widget for editing in future
* releases, therefore you should check the type of @editable
......@@ -891,9 +895,11 @@ gtk_cell_renderer_activate (GtkCellRenderer *cell,
* @cell_area: cell area as passed to gtk_cell_renderer_render()
* @flags: render flags
*
* Passes an activate event to the cell renderer for possible processing.
* Starts editing the contents of this @cell, through a new #GtkCellEditable
* widget created by the #GtkCellRendererClass.start_editing virtual function.
*
* Returns: (nullable) (transfer none): A new #GtkCellEditable, or %NULL
* Returns: (nullable) (transfer none): A new #GtkCellEditable for editing this
* @cell, or %NULL if editing is not possible
**/
GtkCellEditable *
gtk_cell_renderer_start_editing (GtkCellRenderer *cell,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment