Description
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
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 cairo_t. 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 foremost, 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.
Beyond merely rendering a cell, cell renderers can optionally
provide active user interface elements. A cell renderer can be
“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 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.
Many properties of GtkCellRenderer and its subclasses have a
corresponding “set” property, e.g. “cell-background-set” corresponds
to “cell-background”. These “set” properties reflect whether a property
has been set or not. You should not set them independently.
Functions
gtk_cell_renderer_class_set_accessible_type ()
void
gtk_cell_renderer_class_set_accessible_type
(GtkCellRendererClass *renderer_class,
GType type);
Sets the type to be used for creating accessibles for cells rendered by
cell renderers of renderer_class
. Note that multiple accessibles will
be created.
This function should only be called from class init functions of cell
renderers.
gtk_cell_renderer_get_size ()
void
gtk_cell_renderer_get_size (GtkCellRenderer *cell,
GtkWidget *widget,
const 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.
gtk_cell_renderer_render ()
void
gtk_cell_renderer_render (GtkCellRenderer *cell,
cairo_t *cr,
GtkWidget *widget,
const GdkRectangle *background_area,
const GdkRectangle *cell_area,
GtkCellRendererState flags);
Invokes the virtual render function of the GtkCellRenderer. The three
passed-in rectangles are areas in cr
. 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
.
gtk_cell_renderer_stop_editing ()
void
gtk_cell_renderer_stop_editing (GtkCellRenderer *cell,
gboolean canceled);
Informs the cell renderer that the editing is stopped.
If canceled
is TRUE, the cell renderer will emit the
“editing-canceled” signal.
This function should be called by cell renderer implementations
in response to the “editing-done” signal of
GtkCellEditable.
Since: 2.6
gtk_cell_renderer_get_fixed_size ()
void
gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
gint *width,
gint *height);
Fills in width
and height
with the appropriate size of cell
.
gtk_cell_renderer_set_fixed_size ()
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.
gtk_cell_renderer_get_visible ()
gboolean
gtk_cell_renderer_get_visible (GtkCellRenderer *cell);
Returns the cell renderer’s visibility.
Returns
TRUE if the cell renderer is visible
Since: 2.18
gtk_cell_renderer_set_visible ()
void
gtk_cell_renderer_set_visible (GtkCellRenderer *cell,
gboolean visible);
Sets the cell renderer’s visibility.
Since: 2.18
gtk_cell_renderer_get_sensitive ()
gboolean
gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell);
Returns the cell renderer’s sensitivity.
Returns
TRUE if the cell renderer is sensitive
Since: 2.18
gtk_cell_renderer_set_sensitive ()
void
gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell,
gboolean sensitive);
Sets the cell renderer’s sensitivity.
Since: 2.18
gtk_cell_renderer_get_alignment ()
void
gtk_cell_renderer_get_alignment (GtkCellRenderer *cell,
gfloat *xalign,
gfloat *yalign);
Fills in xalign
and yalign
with the appropriate values of cell
.
Since: 2.18
gtk_cell_renderer_set_alignment ()
void
gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
gfloat xalign,
gfloat yalign);
Sets the renderer’s alignment within its available space.
Since: 2.18
gtk_cell_renderer_get_padding ()
void
gtk_cell_renderer_get_padding (GtkCellRenderer *cell,
gint *xpad,
gint *ypad);
Fills in xpad
and ypad
with the appropriate values of cell
.
Since: 2.18
gtk_cell_renderer_set_padding ()
void
gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
gint xpad,
gint ypad);
Sets the renderer’s padding.
Since: 2.18
gtk_cell_renderer_is_activatable ()
gboolean
gtk_cell_renderer_is_activatable (GtkCellRenderer *cell);
Checks whether the cell renderer can do something when activated.
Returns
TRUE if the cell renderer can do anything when activated
Since: 3.0
gtk_cell_renderer_get_preferred_height ()
void
gtk_cell_renderer_get_preferred_height
(GtkCellRenderer *cell,
GtkWidget *widget,
gint *minimum_size,
gint *natural_size);
Retreives a renderer’s natural size when rendered to widget
.
Since: 3.0
gtk_cell_renderer_get_preferred_height_for_width ()
void
gtk_cell_renderer_get_preferred_height_for_width
(GtkCellRenderer *cell,
GtkWidget *widget,
gint width,
gint *minimum_height,
gint *natural_height);
Retreives a cell renderers’s minimum and natural height if it were rendered to
widget
with the specified width
.
Since: 3.0
gtk_cell_renderer_get_preferred_size ()
void
gtk_cell_renderer_get_preferred_size (GtkCellRenderer *cell,
GtkWidget *widget,
GtkRequisition *minimum_size,
GtkRequisition *natural_size);
Retrieves the minimum and natural size of a cell taking
into account the widget’s preference for height-for-width management.
Since: 3.0
gtk_cell_renderer_get_preferred_width ()
void
gtk_cell_renderer_get_preferred_width (GtkCellRenderer *cell,
GtkWidget *widget,
gint *minimum_size,
gint *natural_size);
Retreives a renderer’s natural size when rendered to widget
.
Since: 3.0
gtk_cell_renderer_get_preferred_width_for_height ()
void
gtk_cell_renderer_get_preferred_width_for_height
(GtkCellRenderer *cell,
GtkWidget *widget,
gint height,
gint *minimum_width,
gint *natural_width);
Retreives a cell renderers’s minimum and natural width if it were rendered to
widget
with the specified height
.
Since: 3.0
gtk_cell_renderer_get_request_mode ()
GtkSizeRequestMode
gtk_cell_renderer_get_request_mode (GtkCellRenderer *cell);
Gets whether the cell renderer prefers a height-for-width layout
or a width-for-height layout.
Since: 3.0
Types and Values
enum GtkCellRendererState
Tells how a cell is to be rendered.
enum GtkCellRendererMode
Identifies how the user can interact with a particular cell.
struct GtkCellRenderer
struct GtkCellRenderer;
struct GtkCellRendererClass
struct GtkCellRendererClass {
/* vtable - not signals */
GtkSizeRequestMode (* get_request_mode) (GtkCellRenderer *cell);
void (* get_preferred_width) (GtkCellRenderer *cell,
GtkWidget *widget,
gint *minimum_size,
gint *natural_size);
void (* get_preferred_height_for_width) (GtkCellRenderer *cell,
GtkWidget *widget,
gint width,
gint *minimum_height,
gint *natural_height);
void (* get_preferred_height) (GtkCellRenderer *cell,
GtkWidget *widget,
gint *minimum_size,
gint *natural_size);
void (* get_preferred_width_for_height) (GtkCellRenderer *cell,
GtkWidget *widget,
gint height,
gint *minimum_width,
gint *natural_width);
void (* get_aligned_area) (GtkCellRenderer *cell,
GtkWidget *widget,
GtkCellRendererState flags,
const GdkRectangle *cell_area,
GdkRectangle *aligned_area);
void (* get_size) (GtkCellRenderer *cell,
GtkWidget *widget,
const GdkRectangle *cell_area,
gint *x_offset,
gint *y_offset,
gint *width,
gint *height);
void (* render) (GtkCellRenderer *cell,
cairo_t *cr,
GtkWidget *widget,
const GdkRectangle *background_area,
const GdkRectangle *cell_area,
GtkCellRendererState flags);
gboolean (* activate) (GtkCellRenderer *cell,
GdkEvent *event,
GtkWidget *widget,
const gchar *path,
const GdkRectangle *background_area,
const GdkRectangle *cell_area,
GtkCellRendererState flags);
GtkCellEditable * (* start_editing) (GtkCellRenderer *cell,
GdkEvent *event,
GtkWidget *widget,
const gchar *path,
const GdkRectangle *background_area,
const GdkRectangle *cell_area,
GtkCellRendererState flags);
/* Signals */
void (* editing_canceled) (GtkCellRenderer *cell);
void (* editing_started) (GtkCellRenderer *cell,
GtkCellEditable *editable,
const gchar *path);
};