| | | GTK+ Reference Manual | |
|---|
GtkCellRenderer — An object for rendering a single cell on a GdkDrawable
#include <gtk/gtk.h> enum GtkCellRendererState; enum GtkCellRendererMode; struct GtkCellRenderer; void gtk_cell_renderer_get_size (GtkCellRenderer *cell, GtkWidget *widget, GdkRectangle *cell_area, gint *x_offset, gint *y_offset, gint *width, gint *height); void gtk_cell_renderer_render (GtkCellRenderer *cell, GdkWindow *window, GtkWidget *widget, GdkRectangle *background_area, GdkRectangle *cell_area, GdkRectangle *expose_area, GtkCellRendererState flags); gboolean gtk_cell_renderer_activate (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, GdkRectangle *background_area, GdkRectangle *cell_area, GtkCellRendererState flags); GtkCellEditable* gtk_cell_renderer_start_editing (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, GdkRectangle *background_area, GdkRectangle *cell_area, GtkCellRendererState flags); void gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell, gint *width, gint *height); void gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell, gint width, gint height);
"cell-background" gchararray : Write "cell-background-gdk" GdkColor : Read / Write "cell-background-set" gboolean : Read / Write "height" gint : Read / Write "is-expanded" gboolean : Read / Write "is-expander" gboolean : Read / Write "mode" GtkCellRendererMode : Read / Write "visible" gboolean : Read / Write "width" gint : Read / Write "xalign" gfloat : Read / Write "xpad" guint : Read / Write "yalign" gfloat : Read / Write "ypad" guint : Read / Write
The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a GdkDrawable. These objects are used primarily by the GtkTreeView widget, though they aren't tied to them in any specific way. It is worth noting that GtkCellRenderer is not a GtkWidget and cannot be treated as such.
The primary use of a GtkCellRenderer is for drawing a certain graphical elements on a GdkDrawable. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn't expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using GObjects property system. Then, the cell is measured using gtk_cell_renderer_get_size. Finally, the cell is rendered in the correct location using gtk_cell_renderer_render.
There are a number of rules that must be followed when writing a new GtkCellRenderer. First and formost, it's important that a certain set of properties will always yield a cell renderer of the same size, barring a GtkStyle change. The GtkCellRenderer also has a number of generic properties that are expected to be honored by all children.
typedef enum
{
GTK_CELL_RENDERER_SELECTED = 1 << 0,
GTK_CELL_RENDERER_PRELIT = 1 << 1,
GTK_CELL_RENDERER_INSENSITIVE = 1 << 2,
/* this flag means the cell is in the sort column/row */
GTK_CELL_RENDERER_SORTED = 1 << 3,
GTK_CELL_RENDERER_FOCUSED = 1 << 4
} GtkCellRendererState;
Tells how a cell is to be rendererd.
| GTK_CELL_RENDERER_SELECTED | The cell is currently selected, and probably has a selection colored background to render to. |
| GTK_CELL_RENDERER_PRELIT | The mouse is hovering over the cell. |
| GTK_CELL_RENDERER_INSENSITIVE | The cell is drawn in an insensitive manner |
| GTK_CELL_RENDERER_SORTED | The cell is in a sorted row |
| GTK_CELL_RENDERER_FOCUSED |
typedef enum
{
GTK_CELL_RENDERER_MODE_INERT,
GTK_CELL_RENDERER_MODE_ACTIVATABLE,
GTK_CELL_RENDERER_MODE_EDITABLE
} GtkCellRendererMode;
Identifies how the user can interact with a particular cell.
| GTK_CELL_RENDERER_MODE_INERT | The cell is just for display and cannot be interacted with. Note that this doesn't mean that eg. the row being drawn can't be selected -- just that a particular element of it cannot be individually modified. |
| GTK_CELL_RENDERER_MODE_ACTIVATABLE | The cell can be clicked. |
| GTK_CELL_RENDERER_MODE_EDITABLE | The cell can be edited or otherwise modified. |
void gtk_cell_renderer_get_size (GtkCellRenderer *cell, GtkWidget *widget, GdkRectangle *cell_area, gint *x_offset, gint *y_offset, gint *width, gint *height);
Obtains the width and height needed to render the cell. Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render(). If cell_area is not NULL, fills in the x and y offsets (if set) of the cell relative to this location. Please note that the values set in width and height, as well as those in x_offset and y_offset are inclusive of the xpad and ypad properties.
| cell : | a GtkCellRenderer |
| widget : | the widget the renderer is rendering to |
| cell_area : | The area a cell will be allocated, or NULL |
| x_offset : | location to return x offset of cell relative to cell_area, or NULL |
| y_offset : | location to return y offset of cell relative to cell_area, or NULL |
| width : | location to return width needed to render a cell, or NULL |
| height : | location to return height needed to render a cell, or NULL |
void gtk_cell_renderer_render (GtkCellRenderer *cell, GdkWindow *window, GtkWidget *widget, GdkRectangle *background_area, GdkRectangle *cell_area, GdkRectangle *expose_area, GtkCellRendererState flags);
Invokes the virtual render function of the GtkCellRenderer. The three passed-in rectangles are areas of window. Most renderers will draw within cell_area; the xalign, yalign, xpad, and ypad fields of the GtkCellRenderer should be honored with respect to cell_area. background_area includes the blank space around the cell, and also the area containing the tree expander; so the background_area rectangles for all cells tile to cover the entire window. expose_area is a clip rectangle.
| cell : | a GtkCellRenderer |
| window : | a GdkDrawable to draw to |
| widget : | the widget owning window |
| background_area : | entire cell area (including tree expanders and maybe padding on the sides) |
| cell_area : | area normally rendered by a cell renderer |
| expose_area : | area that actually needs updating |
| flags : | flags that affect rendering |
gboolean gtk_cell_renderer_activate (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, GdkRectangle *background_area, GdkRectangle *cell_area, GtkCellRendererState flags);
Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse click.
| cell : | a GtkCellRenderer |
| event : | a GdkEvent |
| widget : | widget that received the event |
| path : | widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
| background_area : | background area as passed to gtk_cell_renderer_render |
| cell_area : | cell area as passed to gtk_cell_renderer_render |
| flags : | render flags |
| Returns : | TRUE if the event was consumed/handled |
GtkCellEditable* gtk_cell_renderer_start_editing (GtkCellRenderer *cell, GdkEvent *event, GtkWidget *widget, const gchar *path, GdkRectangle *background_area, GdkRectangle *cell_area, GtkCellRendererState flags);
Passes an activate event to the cell renderer for possible processing.
| cell : | a GtkCellRenderer |
| event : | a GdkEvent |
| widget : | widget that received the event |
| path : | widget-dependent string representation of the event location; e.g. for GtkTreeView, a string representation of GtkTreePath |
| background_area : | background area as passed to gtk_cell_renderer_render |
| cell_area : | cell area as passed to gtk_cell_renderer_render |
| flags : | render flags |
| Returns : | A new GtkCellEditable, or NULL |
void gtk_cell_renderer_get_fixed_size
(GtkCellRenderer *cell,
gint *width,
gint *height);Fills in width and height with the appropriate size of cell.
| cell : | A GtkCellRenderer |
| width : | location to fill in with the fixed width of the widget, or NULL |
| height : | location to fill in with the fixed height of the widget, or NULL |
void gtk_cell_renderer_set_fixed_size
(GtkCellRenderer *cell,
gint width,
gint height);Sets the renderer size to be explicit, independent of the properties set.
| cell : | A GtkCellRenderer |
| width : | the width of the cell renderer, or -1 |
| height : | the height of the cell renderer, or -1 |
| "cell-background" (gchararray : Write) |
|
| "cell-background-gdk" (GdkColor : Read / Write) |
|
| "cell-background-set" (gboolean : Read / Write) |
|
| "height" (gint : Read / Write) |
|
| "is-expanded" (gboolean : Read / Write) |
|
| "is-expander" (gboolean : Read / Write) |
|
| "mode" (GtkCellRendererMode : Read / Write) |
|
| "visible" (gboolean : Read / Write) |
|
| "width" (gint : Read / Write) |
|
| "xalign" (gfloat : Read / Write) |
|
| "xpad" (guint : Read / Write) |
|
| "yalign" (gfloat : Read / Write) |
|
| "ypad" (guint : Read / Write) |
|
| << GtkTreeModelSort | GtkCellEditable >> |