Top | ![]() |
![]() |
![]() |
![]() |
enum | GtkCellRendererState |
enum | GtkCellRendererMode |
struct | GtkCellRenderer |
struct | GtkCellRendererClass |
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_snapshot()
.
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 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.
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.
void gtk_cell_renderer_get_aligned_area (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState flags
,const GdkRectangle *cell_area
,GdkRectangle *aligned_area
);
Gets the aligned area used by cell
inside cell_area
. Used for finding
the appropriate edit and focus rectangle.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
flags |
render flags |
|
cell_area |
cell area which would be passed to |
|
aligned_area |
the return location for the space inside |
[out] |
Since: 3.0
void gtk_cell_renderer_get_size (GtkCellRenderer *cell
,GtkWidget *widget
,const GdkRectangle *cell_area
,gint *x_offset
,gint *y_offset
,gint *width
,gint *height
);
gtk_cell_renderer_get_size
has been deprecated since version 3.0 and should not be used in newly-written code.
Use gtk_cell_renderer_get_preferred_size()
instead.
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_snapshot()
. 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 |
||
widget |
the widget the renderer is rendering to |
|
cell_area |
The area a cell will be allocated, or |
[allow-none] |
x_offset |
location to return x offset of cell relative to |
[out][allow-none] |
y_offset |
location to return y offset of cell relative to |
[out][allow-none] |
width |
location to return width needed to render a cell, or |
[out][allow-none] |
height |
location to return height needed to render a cell, or |
[out][allow-none] |
void gtk_cell_renderer_snapshot (GtkCellRenderer *cell
,GtkSnapshot *snapshot
,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
.
cell |
||
snapshot |
a GtkSnapshot to draw to |
|
widget |
the widget owning |
|
background_area |
entire cell area (including tree expanders and maybe padding on the sides) |
|
cell_area |
area normally rendered by a cell renderer |
|
flags |
flags that affect rendering |
Since: 3.90
gboolean gtk_cell_renderer_activate (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const 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 |
||
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 |
|
cell_area |
cell area as passed to |
|
flags |
render flags |
GtkCellEditable * gtk_cell_renderer_start_editing (GtkCellRenderer *cell
,GdkEvent *event
,GtkWidget *widget
,const gchar *path
,const GdkRectangle *background_area
,const GdkRectangle *cell_area
,GtkCellRendererState flags
);
Passes an activate event to the cell renderer for possible processing.
cell |
||
event |
a GdkEvent. |
[nullable] |
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 |
|
cell_area |
cell area as passed to |
|
flags |
render flags |
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
void gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell
,gint *width
,gint *height
);
Fills in width
and height
with the appropriate size of cell
.
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.
gboolean
gtk_cell_renderer_get_visible (GtkCellRenderer *cell
);
Returns the cell renderer’s visibility.
Since: 2.18
void gtk_cell_renderer_set_visible (GtkCellRenderer *cell
,gboolean visible
);
Sets the cell renderer’s visibility.
Since: 2.18
gboolean
gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell
);
Returns the cell renderer’s sensitivity.
Since: 2.18
void gtk_cell_renderer_set_sensitive (GtkCellRenderer *cell
,gboolean sensitive
);
Sets the cell renderer’s sensitivity.
Since: 2.18
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
void gtk_cell_renderer_set_alignment (GtkCellRenderer *cell
,gfloat xalign
,gfloat yalign
);
Sets the renderer’s alignment within its available space.
cell |
||
xalign |
the x alignment of the cell renderer |
|
yalign |
the y alignment of the cell renderer |
Since: 2.18
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
void gtk_cell_renderer_set_padding (GtkCellRenderer *cell
,gint xpad
,gint ypad
);
Sets the renderer’s padding.
Since: 2.18
GtkStateFlags gtk_cell_renderer_get_state (GtkCellRenderer *cell
,GtkWidget *widget
,GtkCellRendererState cell_state
);
Translates the cell renderer state to GtkStateFlags, based on the cell renderer and widget sensitivity, and the given GtkCellRendererState.
cell |
a GtkCellRenderer, or |
[nullable] |
widget |
[nullable] | |
cell_state |
cell renderer state |
Since: 3.0
gboolean
gtk_cell_renderer_is_activatable (GtkCellRenderer *cell
);
Checks whether the cell renderer can do something when activated.
Since: 3.0
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
.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
minimum_size |
location to store the minimum size, or |
[out][allow-none] |
natural_size |
location to store the natural size, or |
[out][allow-none] |
Since: 3.0
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
.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
width |
the size which is available for allocation |
|
minimum_height |
location for storing the minimum size, or |
[out][allow-none] |
natural_height |
location for storing the preferred size, or |
[out][allow-none] |
Since: 3.0
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.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
minimum_size |
location for storing the minimum size, or |
[out][allow-none] |
natural_size |
location for storing the natural size, or |
[out][allow-none] |
Since: 3.0
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
.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
minimum_size |
location to store the minimum size, or |
[out][allow-none] |
natural_size |
location to store the natural size, or |
[out][allow-none] |
Since: 3.0
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
.
cell |
a GtkCellRenderer instance |
|
widget |
the GtkWidget this cell will be rendering to |
|
height |
the size which is available for allocation |
|
minimum_width |
location for storing the minimum size, or |
[out][allow-none] |
natural_width |
location for storing the preferred size, or |
[out][allow-none] |
Since: 3.0
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
Tells how a cell is to be rendered.
The cell is currently selected, and probably has a selection colored background to render to. |
||
The mouse is hovering over the cell. |
||
The cell is drawn in an insensitive manner |
||
The cell is in a sorted row |
||
The cell is in the focus row. |
||
The cell is in a row that can be expanded. Since 3.4 |
||
The cell is in a row that is expanded. Since 3.4 |
Identifies how the user can interact with a particular cell.
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 (* snapshot) (GtkCellRenderer *cell, GtkSnapshot *snapshot, 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); };
Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. |
||
Called to get a renderer’s natural width. |
||
Called to get a renderer’s natural height for width. |
||
Called to get a renderer’s natural height. |
||
Called to get a renderer’s natural width for height. |
||
Called to get the aligned area used by |
||
Called to get the width and height needed to render the cell. Deprecated: 3.0. |
||
Called to snapshot the content of the GtkCellRenderer. |
||
Called to activate the content of the GtkCellRenderer. |
||
Called to initiate editing the content of the GtkCellRenderer. |
||
Signal gets emitted when the user cancels the process of editing a cell. |
||
Signal gets emitted when a cell starts to be edited. |