From 4c165de31fec151c0f4dc020bd489d12e5a2e57b Mon Sep 17 00:00:00 2001 From: Tristan Van Berkom Date: Fri, 3 Dec 2010 16:29:11 +0900 Subject: [PATCH] Added gtk-doc to GtkCellArea & GtkCellAreaContext. --- gtk/gtkcellarea.c | 257 ++++++++++++++++++++++++++++++--------- gtk/gtkcellareacontext.c | 196 +++++++++++++++++++++++++++++ gtk/gtkcellareacontext.h | 12 ++ 3 files changed, 405 insertions(+), 60 deletions(-) diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c index dcf0007f43..a5e8ab9428 100644 --- a/gtk/gtkcellarea.c +++ b/gtk/gtkcellarea.c @@ -26,16 +26,15 @@ * @Short_Description: An abstract class for laying out #GtkCellRenderers * @Title: GtkCellArea * - * The #GtkCellArea is an abstract class for laying out #GtkCellRenderers - * onto a given area of a #GtkWidget. + * The #GtkCellArea is an abstract class for #GtkCellLayout widgets (also referred + * to as "layouting widgets") to interface with an arbitrary number of #GtkCellRenderers + * and interact with the user for a given #GtkTreeModel row. * - * The work of rendering #GtkCellRenderers can be very complicated; it involves - * requesting size for cells, driving keyboard focus from cell to cell, rendering - * the actual cells, painting the focus onto the currently focused cell and finally - * activating cells which are %GTK_CELL_RENDERER_MODE_ACTIVATABLE and editing cells - * which are %GTK_CELL_RENDERER_MODE_EDITABLE. The work is even more complex since - * a cell renderer as opposed to a widget, is used to interact with an arbitrary - * number of #GtkTreeModel rows instead of always displaying the same data. + * The cell area handles events, focus navigation, drawing and wraps geometrical + * size requests and allocations for a given row of data. + * + * Usually users dont have to interact with the #GtkCellArea directly unless they + * are implementing a cell layouting widget themselves. * * * Requesting area sizes @@ -46,22 +45,31 @@ * interfaces. #GtkCellArea uses the same semantics to calculate the * size of an area for an arbitrary number of #GtkTreeModel rows. * - * When requesting the size of a #GtkCellArea one needs to calculate - * the size of a handful of rows, this will be done differently by - * different #GtkCellLayout widgets. For instance a #GtkTreeViewColumn + * When requesting the size of a cell area one needs to calculate + * the size for a handful of rows, this will be done differently by + * different layouting widgets. For instance a #GtkTreeViewColumn * always lines up the areas from top to bottom while a #GtkIconView - * on the other hand might enforce that areas maintain a fixed width - * and then wrap the area around, thus requesting height for more + * on the other hand might enforce that all areas received the same + * width and wrap the areas around, requesting height for more cell * areas when allocated less width. * - * It's also important for #GtkCellAreas to maintain some cell - * alignments with areas rendered for different rows so that - * a handful of rendered rows can allocate the same size for - * a said cell across rows (and also to make sure to request - * an appropriate size for the largest row after requesting - * a hand full of rows). For this reason the #GtkCellArea + * It's also important for areas to maintain some cell + * alignments with areas rendered for adjacent rows (cells can + * appear "columnized" inside an area even when the size of + * cells are different in each row). For this reason the #GtkCellArea * uses a #GtkCellAreaContext object to store the alignments - * and sizes along the way. + * and sizes along the way (as well as the overall largest minimum + * and natural size for all the rows which have been calculated + * with the said context). + * + * The #GtkCellAreaContext is an opaque object specific to the + * #GtkCellArea which created it (see gtk_cell_area_create_context()). + * The owning cell layouting widget can create as many contexts as + * it wishes to calculate sizes of rows which should receive the + * same size in at least one orientation (horizontally or vertically), + * however it's important that the same #GtkCellAreaContext which + * was used to request the sizes for a given #GtkTreeModel row be + * used when rendering or processing events for that row. * * In order to request the width of all the rows at the root level * of a #GtkTreeModel one would do the following: @@ -98,7 +106,7 @@ * A simple example where rows are rendered from top to bottom and take up the full * width of the layouting widget would look like: * - * Requesting the width of a hand full of GtkTreeModel rows. + * A typical #GtkWidgetClass.get_preferred_width() for a layouting widget. * * static void * foo_get_preferred_width (GtkWidget *widget, @@ -242,7 +250,7 @@ * * Implementing keyboard focus navigation when displaying rows from top to bottom. * - * static void + * static gboolean * foo_focus (GtkWidget *widget, * GtkDirectionType direction) * { @@ -269,13 +277,13 @@ * } * else * { - * if (direction == GTK_DIR_RIGHT || - * direction == GTK_DIR_LEFT) - * break; - * else if (direction == GTK_DIR_UP || - * direction == GTK_DIR_TAB_BACKWARD) - * { - * if (focus_row == 0) + * if (direction == GTK_DIR_RIGHT || + * direction == GTK_DIR_LEFT) + * break; + * else if (direction == GTK_DIR_UP || + * direction == GTK_DIR_TAB_BACKWARD) + * { + * if (focus_row == 0) * break; * else * { @@ -567,6 +575,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * @is_expanded: whether the view is currently showing the children of this row * * This signal is emitted whenever applying attributes to @area from @model + * + * Since: 3.0 */ cell_area_signals[SIGNAL_APPLY_ATTRIBUTES] = g_signal_new (I_("apply-attributes"), @@ -588,10 +598,12 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * @editable: the #GtkCellEditable widget to add * @cell_area: the #GtkWidget relative #GdkRectangle coordinates * where @editable should be added - * @path: the #GtkTreePath string this edit was initiated for + * @path: the #GtkTreePath string this edit was initiated for * * Indicates that editing has started on @renderer and that @editable * should be added to the owning cell layouting widget at @cell_area. + * + * Since: 3.0 */ cell_area_signals[SIGNAL_ADD_EDITABLE] = g_signal_new (I_("add-editable"), @@ -615,6 +627,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * * Indicates that editing finished on @renderer and that @editable * should be removed from the owning cell layouting widget. + * + * Since: 3.0 */ cell_area_signals[SIGNAL_REMOVE_EDITABLE] = g_signal_new (I_("remove-editable"), @@ -641,6 +655,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * currently focused renderer did not change, this is * because focus may change to the same renderer in the * same cell area for a different row of data. + * + * Since: 3.0 */ cell_area_signals[SIGNAL_FOCUS_CHANGED] = g_signal_new (I_("focus-changed"), @@ -658,6 +674,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * GtkCellArea:focus-cell: * * The cell in the area that currently has focus + * + * Since: 3.0 */ g_object_class_install_property (object_class, PROP_FOCUS_CELL, @@ -675,6 +693,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * * This property is read-only and only changes as * a result of a call gtk_cell_area_activate_cell(). + * + * Since: 3.0 */ g_object_class_install_property (object_class, PROP_EDITED_CELL, @@ -692,6 +712,8 @@ gtk_cell_area_class_init (GtkCellAreaClass *class) * * This property is read-only and only changes as * a result of a call gtk_cell_area_activate_cell(). + * + * Since: 3.0 */ g_object_class_install_property (object_class, PROP_EDIT_WIDGET, @@ -1213,6 +1235,8 @@ gtk_cell_area_get_cells (GtkCellLayout *cell_layout) * @renderer: the #GtkCellRenderer to add to @area * * Adds @renderer to @area with the default child cell properties. + * + * Since: 3.0 */ void gtk_cell_area_add (GtkCellArea *area, @@ -1238,6 +1262,8 @@ gtk_cell_area_add (GtkCellArea *area, * @renderer: the #GtkCellRenderer to add to @area * * Removes @renderer from @area. + * + * Since: 3.0 */ void gtk_cell_area_remove (GtkCellArea *area, @@ -1297,7 +1323,9 @@ get_has_renderer (GtkCellRenderer *renderer, * * Checks if @area contains @renderer. * - * Returns: %TRUE if @renderer is in the @area. + * Return value: %TRUE if @renderer is in the @area. + * + * Since: 3.0 */ gboolean gtk_cell_area_has_renderer (GtkCellArea *area, @@ -1320,6 +1348,8 @@ gtk_cell_area_has_renderer (GtkCellArea *area, * @callback_data: user provided data pointer * * Calls @callback for every #GtkCellRenderer in @area. + * + * Since: 3.0 */ void gtk_cell_area_forall (GtkCellArea *area, @@ -1348,10 +1378,12 @@ gtk_cell_area_forall (GtkCellArea *area, * @renderer: the #GtkCellRenderer to get the allocation for * @cell_area: the whole allocated area for @area in @widget * for this row - * @allocation: where to store the allocation for @renderer + * @allocation: (out): where to store the allocation for @renderer * * Derives the allocation of @renderer inside @area if @area * were to be renderered in @cell_area. + * + * Since: 3.0 */ void gtk_cell_area_get_cell_allocation (GtkCellArea *area, @@ -1390,7 +1422,9 @@ gtk_cell_area_get_cell_allocation (GtkCellArea *area, * * Delegates event handling to a #GtkCellArea. * - * Returns: %TRUE if the event was handled by @area. + * Return value: %TRUE if the event was handled by @area. + * + * Since: 3.0 */ gint gtk_cell_area_event (GtkCellArea *area, @@ -1431,6 +1465,8 @@ gtk_cell_area_event (GtkCellArea *area, * * Renders @area's cells according to @area's layout onto @widget at * the given coordinates. + * + * Since: 3.0 */ void gtk_cell_area_render (GtkCellArea *area, @@ -1467,6 +1503,8 @@ gtk_cell_area_render (GtkCellArea *area, * * Sets the detail string used in any gtk_paint_*() functions * used by @area. + * + * Since: 3.0 */ void gtk_cell_area_set_style_detail (GtkCellArea *area, @@ -1492,7 +1530,9 @@ gtk_cell_area_set_style_detail (GtkCellArea *area, * Gets the detail string used in any gtk_paint_*() functions * used by @area. * - * Returns: the detail string. + * Return value: the detail string, the string belongs to the area and should not be freed. + * + * Since: 3.0 */ G_CONST_RETURN gchar * gtk_cell_area_get_style_detail (GtkCellArea *area) @@ -1520,7 +1560,9 @@ gtk_cell_area_get_style_detail (GtkCellArea *area) * one should render and handle events with the same #GtkCellAreaContext * which was used to request the size of those rows of data). * - * Returns: a newly created #GtkCellAreaContext which can be used with @area. + * Return value: (transfer full): a newly created #GtkCellAreaContext which can be used with @area. + * + * Since: 3.0 */ GtkCellAreaContext * gtk_cell_area_create_context (GtkCellArea *area) @@ -1548,7 +1590,7 @@ gtk_cell_area_create_context (GtkCellArea *area) * Gets whether the area prefers a height-for-width layout * or a width-for-height layout. * - * Returns: The #GtkSizeRequestMode preferred by @area. + * Return value: The #GtkSizeRequestMode preferred by @area. * * Since: 3.0 */ @@ -1587,7 +1629,6 @@ gtk_cell_area_get_request_mode (GtkCellArea *area) * consult gtk_cell_area_context_get_preferred_width() after a series of * requests. * - * * Since: 3.0 */ void @@ -1750,6 +1791,8 @@ gtk_cell_area_get_preferred_width_for_height (GtkCellArea *area, * * Connects an @attribute to apply values from @column for the * #GtkTreeModel in use. + * + * Since: 3.0 */ void gtk_cell_area_attribute_connect (GtkCellArea *area, @@ -1817,6 +1860,8 @@ gtk_cell_area_attribute_connect (GtkCellArea *area, * Disconnects @attribute for the @renderer in @area so that * attribute will no longer be updated with values from the * model. + * + * Since: 3.0 */ void gtk_cell_area_attribute_disconnect (GtkCellArea *area, @@ -1854,7 +1899,7 @@ gtk_cell_area_attribute_disconnect (GtkCellArea *area, /** * gtk_cell_area_apply_attributes * @area: a #GtkCellArea - * @tree_model: a #GtkTreeModel to pull values from + * @tree_model: the #GtkTreeModel to pull values from * @iter: the #GtkTreeIter in @tree_model to apply values for * @is_expander: whether @iter has children * @is_expanded: whether @iter is expanded in the view and @@ -1862,6 +1907,8 @@ gtk_cell_area_attribute_disconnect (GtkCellArea *area, * * Applies any connected attributes to the renderers in * @area by pulling the values from @tree_model. + * + * Since: 3.0 */ void gtk_cell_area_apply_attributes (GtkCellArea *area, @@ -1887,8 +1934,14 @@ gtk_cell_area_apply_attributes (GtkCellArea *area, * gtk_cell_area_apply_attributes() is called and can be * used to interact with renderers from #GtkCellArea * subclasses. + * + * Return value: The current #GtkTreePath string for the current + * attributes applied to @area. This string belongs to the area and + * should not be freed. + * + * Since: 3.0 */ -const gchar * +G_CONST_RETURN gchar * gtk_cell_area_get_current_path_string (GtkCellArea *area) { GtkCellAreaPrivate *priv; @@ -1911,6 +1964,8 @@ gtk_cell_area_get_current_path_string (GtkCellArea *area) * @pspec: the #GParamSpec for the property * * Installs a cell property on a cell area class. + * + * Since: 3.0 */ void gtk_cell_area_class_install_cell_property (GtkCellAreaClass *aclass, @@ -1943,10 +1998,13 @@ gtk_cell_area_class_install_cell_property (GtkCellAreaClass *aclass, * gtk_cell_area_class_find_cell_property: * @aclass: a #GtkCellAreaClass * @property_name: the name of the child property to find - * @returns: (allow-none): the #GParamSpec of the child property or %NULL if @aclass has no - * child property with that name. * * Finds a cell property of a cell area class by name. + * + * Return value: (allow-none): the #GParamSpec of the child property or %NULL if @aclass has no + * child property with that name. + * + * Since: 3.0 */ GParamSpec* gtk_cell_area_class_find_cell_property (GtkCellAreaClass *aclass, @@ -1965,10 +2023,13 @@ gtk_cell_area_class_find_cell_property (GtkCellAreaClass *aclass, * gtk_cell_area_class_list_cell_properties: * @aclass: a #GtkCellAreaClass * @n_properties: location to return the number of cell properties found - * @returns: a newly allocated %NULL-terminated array of #GParamSpec*. - * The array must be freed with g_free(). * * Returns all cell properties of a cell area class. + * + * Return value: a newly allocated %NULL-terminated array of #GParamSpec*. + * The array must be freed with g_free(). + * + * Since: 3.0 */ GParamSpec** gtk_cell_area_class_list_cell_properties (GtkCellAreaClass *aclass, @@ -1998,7 +2059,9 @@ gtk_cell_area_class_list_cell_properties (GtkCellAreaClass *aclass, * * Adds @renderer to @area, setting cell properties at the same time. * See gtk_cell_area_add() and gtk_cell_area_child_set() for more details. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_add_with_properties (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2036,7 +2099,9 @@ gtk_cell_area_add_with_properties (GtkCellArea *area, * with @first_prop_name * * Sets one or more cell properties for @cell in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_set (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2062,7 +2127,9 @@ gtk_cell_area_cell_set (GtkCellArea *area, * optionally by more name/return location pairs, followed by %NULL * * Gets the values of one or more cell properties for @renderer in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_get (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2133,7 +2200,9 @@ area_set_cell_property (GtkCellArea *area, * with @first_prop_name * * Sets one or more cell properties for @renderer in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_set_valist (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2193,7 +2262,9 @@ gtk_cell_area_cell_set_valist (GtkCellArea *area, * optionally by more name/return location pairs, followed by %NULL * * Gets the values of one or more cell properties for @renderer in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_get_valist (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2250,7 +2321,9 @@ gtk_cell_area_cell_get_valist (GtkCellArea *area, * @value: the value to set the cell property to * * Sets a cell property for @renderer in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_set_property (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2286,7 +2359,9 @@ gtk_cell_area_cell_set_property (GtkCellArea *area, * @value: a location to return the value * * Gets the value of a cell property for @renderer in @area. - **/ + * + * Since: 3.0 + */ void gtk_cell_area_cell_get_property (GtkCellArea *area, GtkCellRenderer *renderer, @@ -2354,7 +2429,9 @@ gtk_cell_area_cell_get_property (GtkCellArea *area, * Returns whether the area can do anything when activated, * after applying new attributes to @area. * - * Returns: whether @area can do anything when activated. + * Return value: whether @area can do anything when activated. + * + * Since: 3.0 */ gboolean gtk_cell_area_is_activatable (GtkCellArea *area) @@ -2377,7 +2454,9 @@ gtk_cell_area_is_activatable (GtkCellArea *area) * method to receive and navigate focus in it's own way particular * to how it lays out cells. * - * Returns: %TRUE if focus remains inside @area as a result of this call. + * Return value: %TRUE if focus remains inside @area as a result of this call. + * + * Since: 3.0 */ gboolean gtk_cell_area_focus (GtkCellArea *area, @@ -2410,7 +2489,9 @@ gtk_cell_area_focus (GtkCellArea *area, * cell, however some subclasses which embed widgets in the area * can also activate a widget if it currently has the focus. * - * Returns: Whether @area was successfully activated. + * Return value: Whether @area was successfully activated. + * + * Since: 3.0 */ gboolean gtk_cell_area_activate (GtkCellArea *area, @@ -2435,6 +2516,8 @@ gtk_cell_area_activate (GtkCellArea *area, * is called. It's also up to the #GtkCellArea implementation * to update the focused cell when receiving events from * gtk_cell_area_event() appropriately. + * + * Since: 3.0 */ void gtk_cell_area_set_focus_cell (GtkCellArea *area, @@ -2474,7 +2557,9 @@ gtk_cell_area_set_focus_cell (GtkCellArea *area, * * Retrieves the currently focused cell for @area * - * Returns: the currently focused cell in @area. + * Return value: the currently focused cell in @area. + * + * Since: 3.0 */ GtkCellRenderer * gtk_cell_area_get_focus_cell (GtkCellArea *area) @@ -2505,6 +2590,8 @@ gtk_cell_area_get_focus_cell (GtkCellArea *area) * * Events handled by focus siblings can also activate the given * focusable @renderer. + * + * Since: 3.0 */ void gtk_cell_area_add_focus_sibling (GtkCellArea *area, @@ -2548,6 +2635,8 @@ gtk_cell_area_add_focus_sibling (GtkCellArea *area, * * Removes @sibling from @renderer's focus sibling list * (see gtk_cell_area_add_focus_sibling()). + * + * Since: 3.0 */ void gtk_cell_area_remove_focus_sibling (GtkCellArea *area, @@ -2583,6 +2672,8 @@ gtk_cell_area_remove_focus_sibling (GtkCellArea *area, * * Returns %TRUE if @sibling is one of @renderer's focus siblings * (see gtk_cell_area_add_focus_sibling()). + * + * Since: 3.0 */ gboolean gtk_cell_area_is_focus_sibling (GtkCellArea *area, @@ -2618,7 +2709,10 @@ gtk_cell_area_is_focus_sibling (GtkCellArea *area, * * Gets the focus sibling cell renderers for @renderer. * - * Returns: A #GList of #GtkCellRenderers. The returned list is internal and should not be freed. + * Return value: (element-type GtkCellRenderer) (transfer none): A #GList of #GtkCellRenderers. + * The returned list is internal and should not be freed. + * + * Since: 3.0 */ const GList * gtk_cell_area_get_focus_siblings (GtkCellArea *area, @@ -2647,7 +2741,9 @@ gtk_cell_area_get_focus_siblings (GtkCellArea *area, * then chose to activate the focus cell for which the event * cell may have been a sibling. * - * Returns: the #GtkCellRenderer for which @renderer is a sibling, or %NULL. + * Return value: the #GtkCellRenderer for which @renderer is a sibling, or %NULL. + * + * Since: 3.0 */ GtkCellRenderer * gtk_cell_area_get_focus_from_sibling (GtkCellArea *area, @@ -2788,7 +2884,9 @@ gtk_cell_area_set_edit_widget (GtkCellArea *area, * Gets the #GtkCellRenderer in @area that is currently * being edited. * - * Returns: The currently edited #GtkCellRenderer + * Return value: The currently edited #GtkCellRenderer + * + * Since: 3.0 */ GtkCellRenderer * gtk_cell_area_get_edited_cell (GtkCellArea *area) @@ -2809,7 +2907,9 @@ gtk_cell_area_get_edited_cell (GtkCellArea *area) * Gets the #GtkCellEditable widget currently used * to edit the currently edited cell. * - * Returns: The currently active #GtkCellEditable widget + * Return value: The currently active #GtkCellEditable widget + * + * Since: 3.0 */ GtkCellEditable * gtk_cell_area_get_edit_widget (GtkCellArea *area) @@ -2838,7 +2938,9 @@ gtk_cell_area_get_edit_widget (GtkCellArea *area) * for keyboard events for free in it's own GtkCellArea->activate() * implementation. * - * Returns: whether cell activation was successful + * Return value: whether cell activation was successful + * + * Since: 3.0 */ gboolean gtk_cell_area_activate_cell (GtkCellArea *area, @@ -2932,6 +3034,8 @@ gtk_cell_area_activate_cell (GtkCellArea *area, * * If @canceled is %TRUE, the cell renderer will emit * the ::editing-canceled signal. + * + * Since: 3.0 */ void gtk_cell_area_stop_editing (GtkCellArea *area, @@ -2968,6 +3072,20 @@ gtk_cell_area_stop_editing (GtkCellArea *area, * API: Convenience for area implementations * *************************************************************/ +/** + * gtk_cell_area_inner_cell_area: + * @area: a #GtkCellArea + * @widget: the #GtkWidget that @area is rendering onto + * @cell_area: the @widget relative coordinates where one of @area's cells + * is to be placed + * @inner_area: (out): the return location for the inner cell area + * + * This is a convenience function for #GtkCellArea implementations + * to get the inner area where a given #GtkCellRenderer will be + * rendered. It removes any padding previously added by gtk_cell_area_request_renderer(). + * + * Since: 3.0 + */ void gtk_cell_area_inner_cell_area (GtkCellArea *area, GtkWidget *widget, @@ -2991,6 +3109,25 @@ gtk_cell_area_inner_cell_area (GtkCellArea *area, inner_area->height -= focus_line_width * 2; } +/** + * gtk_cell_area_request_renderer: + * @area: a #GtkCellArea + * @renderer: the #GtkCellRenderer to request size for + * @orientation: the #GtkOrientation in which to request size + * @widget: the #GtkWidget that @area is rendering onto + * @for_size: the allocation contextual size to request for, or -1 if + * the base request for the orientation is to be returned. + * @minimum_size: (out) (allow-none): location to store the minimum size, or %NULL + * @natural_size: (out) (allow-none): location to store the natural size, or %NULL + * + * This is a convenience function for #GtkCellArea implementations + * to request size for cell renderers. It's important to use this + * function to request size and then use gtk_cell_area_inner_cell_area() + * at render and event time since this function will add padding + * around the cell for focus painting. + * + * Since: 3.0 + */ void gtk_cell_area_request_renderer (GtkCellArea *area, GtkCellRenderer *renderer, diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c index 6b78d20829..164af47467 100644 --- a/gtk/gtkcellareacontext.c +++ b/gtk/gtkcellareacontext.c @@ -21,6 +21,20 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtkcellareacontext + * @Short_Description: An object for a #GtkCellArea to store geometrical information for a series of rows. + * @Title: GtkCellAreaContext + * + * The #GtkCellAreaContext object is created by a given #GtkCellArea implementation via it's + * #GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments + * for a series of #GtkTreeModel rows that are requested and rendered in the same context. + * + * #GtkCellLayout widgets can create any number of contexts in which to request and render + * groups of data rows. However its important that the same context which was used to + * request sizes for a given #GtkTreeModel row also be used for the same row when calling + * other #GtkCellArea apis such as gtk_cell_area_render() and gtk_cell_area_event(). + */ #include "config.h" #include "gtkintl.h" #include "gtkmarshalers.h" @@ -97,6 +111,13 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) class->reset = gtk_cell_area_context_real_reset; class->allocate = gtk_cell_area_context_real_allocate; + /** + * GtkCellAreaContext:area: + * + * The #GtkCellArea this context was created by + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_CELL_AREA, g_param_spec_object ("area", @@ -105,6 +126,15 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) GTK_TYPE_CELL_AREA, GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + /** + * GtkCellAreaContext:minimum-width: + * + * The minimum width for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_width(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_MIN_WIDTH, g_param_spec_int ("minimum-width", @@ -115,6 +145,15 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) -1, G_PARAM_READABLE)); + /** + * GtkCellAreaContext:natural-width: + * + * The natural width for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_width(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_NAT_WIDTH, g_param_spec_int ("natural-width", @@ -125,6 +164,15 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) -1, G_PARAM_READABLE)); + /** + * GtkCellAreaContext:minimum-height: + * + * The minimum height for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_height(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_MIN_HEIGHT, g_param_spec_int ("minimum-height", @@ -135,6 +183,15 @@ gtk_cell_area_context_class_init (GtkCellAreaContextClass *class) -1, G_PARAM_READABLE)); + /** + * GtkCellAreaContext:natural-height: + * + * The natural height for the #GtkCellArea in this context + * for all #GtkTreeModel rows that this context was requested + * for using gtk_cell_area_get_preferred_height(). + * + * Since: 3.0 + */ g_object_class_install_property (object_class, PROP_NAT_HEIGHT, g_param_spec_int ("natural-height", @@ -256,6 +313,25 @@ gtk_cell_area_context_real_allocate (GtkCellAreaContext *context, /************************************************************* * API * *************************************************************/ +/** + * gtk_cell_area_context_get_area: + * @context: a #GtkCellAreaContext + * + * Fetches the #GtkCellArea this @context was created by. + * + * This is generally unneeded by layouting widgets however + * its important for the context implementation itself to + * fetch information about the area it is being used for. + * + * For instance at #GtkCellAreaContextClass.allocate() time + * it's important to know details about any cell spacing + * that the #GtkCellArea is configured with in order to + * compute a proper allocation. + * + * Return value: the #GtkCellArea this context was created by. + * + * Since: 3.0 + */ GtkCellArea * gtk_cell_area_context_get_area (GtkCellAreaContext *context) { @@ -268,6 +344,35 @@ gtk_cell_area_context_get_area (GtkCellAreaContext *context) return priv->cell_area; } +/** + * gtk_cell_area_context_reset: + * @context: a #GtkCellAreaContext + * + * Resets any previously cached request and allocation + * data. + * + * When underlying #GtkTreeModel data changes it's + * important to reset the context if the content + * size is allowed to shrink. If the content size + * is only allowed to grow (this is usually an option + * for views rendering large data stores as a measure + * of optimization), then only the row that changed + * or was inserted needs to be (re)requested with + * gtk_cell_area_get_preferred_width(). + * + * When the new overall size of the context requires + * that the allocated size changes (or whenever this + * allocation changes at all), the variable row + * sizes need to be re-requested for every row. + * + * For instance, if the rows are displayed all with + * the same width from top to bottom then a change + * in the allocated width necessitates a recalculation + * of all the displayed row heights using + * gtk_cell_area_get_preferred_height_for_width(). + * + * Since 3.0 + */ void gtk_cell_area_context_reset (GtkCellAreaContext *context) { @@ -276,6 +381,23 @@ gtk_cell_area_context_reset (GtkCellAreaContext *context) GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->reset (context); } +/** + * gtk_cell_area_context_allocate: + * @context: a #GtkCellAreaContext + * @width: the allocated width for all #GtkTreeModel rows rendered with @context, or -1. + * @height: the allocated height for all #GtkTreeModel rows rendered with @context, or -1. + * + * Allocates a width and/or a height for all rows which are to be rendered with @context. + * + * Usually allocation is performed only horizontally or sometimes vertically since + * a group of rows are usually rendered side by side vertically or horizontally and + * share either the same width or the same hieght. Sometimes they are allocated in + * both horizontal and vertical orientations producing a homogenious effect of the + * rows. This is generally the case for #GtkTreeView when #GtkTreeView:fixed-height-mode + * is enabled. + * + * Since 3.0 + */ void gtk_cell_area_context_allocate (GtkCellAreaContext *context, gint width, @@ -286,6 +408,20 @@ gtk_cell_area_context_allocate (GtkCellAreaContext *context, GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->allocate (context, width, height); } +/** + * gtk_cell_area_context_get_preferred_width: + * @context: a #GtkCellAreaContext + * @minimum_width: (out) (allow-none): location to store the minimum width, or %NULL + * @natural_width: (out) (allow-none): location to store the natural width, or %NULL + * + * Gets the accumulative preferred width for all rows which have been requested + * with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever requesting + * the size of a #GtkCellArea, the returned values are -1. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context, gint *minimum_width, @@ -304,6 +440,20 @@ gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context, *natural_width = priv->nat_width; } +/** + * gtk_cell_area_context_get_preferred_height: + * @context: a #GtkCellAreaContext + * @minimum_height: (out) (allow-none): location to store the minimum height, or %NULL + * @natural_height: (out) (allow-none): location to store the natural height, or %NULL + * + * Gets the accumulative preferred height for all rows which have been requested + * with this context. + * + * After gtk_cell_area_context_reset() is called and/or before ever requesting + * the size of a #GtkCellArea, the returned values are -1. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context, gint *minimum_height, @@ -322,6 +472,20 @@ gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context, *natural_height = priv->nat_height; } +/** + * gtk_cell_area_context_get_allocation: + * @context: a #GtkCellAreaContext + * @width: (out) (allow-none): location to store the allocated width, or %NULL. + * @height: (out) (allow-none): location to store the allocated height, or %NULL. + * + * Fetches the current allocation size for @context. + * + * If the context was not allocated in width or height, or if the + * context was recently reset with gtk_cell_area_context_reset(), + * the returned value will be -1. + * + * Since: 3.0 + */ void gtk_cell_area_context_get_allocation (GtkCellAreaContext *context, gint *width, @@ -340,6 +504,22 @@ gtk_cell_area_context_get_allocation (GtkCellAreaContext *context, *height = priv->alloc_height; } +/** + * gtk_cell_area_context_push_preferred_width: + * @context: a #GtkCellAreaContext + * @minimum_width: the proposed new minimum width for @context. + * @natural_width: the proposed new natural width for @context. + * + * Causes the minimum and/or natural width to grow if the new + * proposed sizes exceed the current minimum and natural width. + * + * This is used by #GtkCellAreaContext implementations during + * the request process over a series of #GtkTreeModel rows to + * progressively push the requested width over a series of + * gtk_cell_area_get_preferred_width() requests. + * + * Since: 3.0 + */ void gtk_cell_area_context_push_preferred_width (GtkCellAreaContext *context, gint minimum_width, @@ -370,6 +550,22 @@ gtk_cell_area_context_push_preferred_width (GtkCellAreaContext *context, g_object_thaw_notify (G_OBJECT (context)); } +/** + * gtk_cell_area_context_push_preferred_height: + * @context: a #GtkCellAreaContext + * @minimum_height: the proposed new minimum height for @context. + * @natural_height: the proposed new natural height for @context. + * + * Causes the minimum and/or natural height to grow if the new + * proposed sizes exceed the current minimum and natural height. + * + * This is used by #GtkCellAreaContext implementations during + * the request process over a series of #GtkTreeModel rows to + * progressively push the requested height over a series of + * gtk_cell_area_get_preferred_height() requests. + * + * Since: 3.0 + */ void gtk_cell_area_context_push_preferred_height (GtkCellAreaContext *context, gint minimum_height, diff --git a/gtk/gtkcellareacontext.h b/gtk/gtkcellareacontext.h index 2338074a2d..549977f351 100644 --- a/gtk/gtkcellareacontext.h +++ b/gtk/gtkcellareacontext.h @@ -49,15 +49,27 @@ struct _GtkCellAreaContext GtkCellAreaContextPrivate *priv; }; +/** + * GtkCellAreaContextClass: + * @allocate: This tells the context that an allocation width or height (or both) + * have been decided for a group of rows. The context should store any allocations + * for internally aligned cells at this point so that they dont need to be + * recalculated at gtk_cell_area_render() time. + * @reset: Clear any previously stored information about requested and allocated + * sizes for the context. + */ struct _GtkCellAreaContextClass { + /*< private >*/ GObjectClass parent_class; + /*< public >*/ void (* allocate) (GtkCellAreaContext *context, gint width, gint height); void (* reset) (GtkCellAreaContext *context); + /*< private >*/ /* Padding for future expansion */ void (*_gtk_reserved1) (void); void (*_gtk_reserved2) (void);