From a7ad110fe9beb0a3458b38574b2e74ac7b76d109 Mon Sep 17 00:00:00 2001 From: Tristan Van Berkom Date: Fri, 3 Dec 2010 00:29:22 +0900 Subject: [PATCH] Adding more documentation to GtkCellArea, documented GtkCellAreaClass structure. --- gtk/gtkcellarea.c | 2 +- gtk/gtkcellarea.h | 64 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c index 9f5616b2c..dcf0007f4 100644 --- a/gtk/gtkcellarea.c +++ b/gtk/gtkcellarea.c @@ -210,7 +210,7 @@ * Note that the cached height in this example really depends on how the layouting * widget works. The layouting widget might decide to give every row it's minimum * or natural height or if the model content is expected to fit inside the layouting - * widget with not scrolled window it would make sense to calculate the allocation + * widget with no scrolled window it would make sense to calculate the allocation * for each row at #GtkWidget.size_allocate() time using gtk_distribute_natural_allocation(). * * diff --git a/gtk/gtkcellarea.h b/gtk/gtkcellarea.h index abc73d047..f857e19ab 100644 --- a/gtk/gtkcellarea.h +++ b/gtk/gtkcellarea.h @@ -65,11 +65,70 @@ struct _GtkCellArea GtkCellAreaPrivate *priv; }; + +/** + * GtkCellAreaClass: + * @add: adds a #GtkCellRenderer to the area. + * @remove: removes a #GtkCellRenderer from the area. + * @forall: Calls the #GtkCellCallback function on every #GtkCellRenderer in the area + * with the provided user data. + * @get_cell_allocation: Gets the position (relative to the passed @cell_area rectangle) + * and size of a #GtkCellRenderer. + * @event: Handle an event in the area, this is generally used to activate a cell + * at the event location for button events but can also be used to generically pass + * events to #GtkWidgets drawn onto the area. + * @render: Actually render the area's cells to the specified rectangle, @background_area + * should be correctly distributed to the cells coresponding background areas. + * @apply_attributes: Apply the cell attributes to the cells. This is implemented as a signal and + * generally #GtkCellArea subclasses dont need to implement this since it's handled by the base + * class but can be overridden to apply some custom attributes. + * @create_context: Creates and returns a class specific #GtkCellAreaContext to store cell + * alignment and allocation details for a said #GtkCellArea class. + * @get_request_mode: This allows an area to tell its layouting widget whether it prefers to + * be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. + * @get_preferred_width: Calculates the minimum and natural width of the area's cells + * with the current attributes applied while considering the particular layouting details + * of the said #GtkCellArea. While requests are performed over a series of rows, alignments + * and overall minimum and natural sizes should be stored in the corresponding #GtkCellAreaContext. + * @get_preferred_height_for_width: Calculates the minimum and natural height for the area + * if the passed @context would be allocated the given width. When implementing this virtual + * method it is safe to assume that @context has already stored the aligned cell widths + * for every #GtkTreeModel row that @context will be allocated for since this information + * was stored at #GtkCellAreaClass.get_preferred_width() time. This virtual method should + * also store any necessary alignments of cell heights for the case that the context is + * allocated a height. + * @get_preferred_height: Calculates the minimum and natural height of the area's cells + * with the current attributes applied. Essentially this is the same as + * #GtkCellAreaClass.get_preferred_width() only for areas that are being requested as + * %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. + * @get_preferred_width_for_height: Calculates the minimum and natural width for the area + * if the passed @context would be allocated the given height. The same as + * #GtkCellAreaClass.get_preferred_height_for_width() only for handling requests in the + * %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. + * @set_cell_property: This should be implemented to handle changes in child cell properties + * for a given #GtkCellRenderer that were previously installed on the #GtkCellAreaClass with + * gtk_cell_area_class_install_cell_property(). + * @get_cell_property: This should be implemented to report the values of child cell properties + * for a given child #GtkCellRenderer. + * @focus: This virtual method should be implemented to navigate focus from cell to cell + * inside the #GtkCellArea. The #GtkCellArea should move focus from cell to cell inside + * the area and return %FALSE if focus logically leaves the area with the following exceptions: + * When the area contains no activatable cells, the entire area recieves focus. Focus should not + * be given to cells that are actually "focus siblings" of other sibling cells + * (see gtk_cell_area_get_focus_from_sibling()). Focus is set by calling gtk_cell_area_set_focus_cell(). + * @is_activatable: Returns whether the #GtkCellArea can respond to #GtkCellAreaClass.activate(), + * usually this does not need to be implemented since the base class takes care of this however + * it can be enhanced if the #GtkCellArea subclass can handle activation in other ways than + * activating its #GtkCellRenderers. + * @activate: This is called when the layouting widget rendering the #GtkCellArea activates + * the focus cell (see gtk_cell_area_get_focus_cell()). + */ struct _GtkCellAreaClass { + /*< private >*/ GInitiallyUnownedClass parent_class; - /* vtable - not signals */ + /*< public >*/ /* Basic methods */ void (* add) (GtkCellArea *area, @@ -144,15 +203,16 @@ struct _GtkCellAreaClass GParamSpec *pspec); /* Focus */ - gboolean (* is_activatable) (GtkCellArea *area); gboolean (* focus) (GtkCellArea *area, GtkDirectionType direction); + gboolean (* is_activatable) (GtkCellArea *area); gboolean (* activate) (GtkCellArea *area, GtkCellAreaContext *context, GtkWidget *widget, const GdkRectangle *cell_area, GtkCellRendererState flags); + /*< private >*/ /* Padding for future expansion */ void (*_gtk_reserved1) (void); -- 2.43.2