GtkCellRenderer

GtkCellRenderer — An object for rendering a single cell

Functions

Types and Values

Includes

#include <gtk/gtk.h>

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_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.

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.

Parameters

renderer_class

class to set the accessible type for

 

type

The object type that implements the accessible for widget_class . The type must be a subtype of GtkRendererCellAccessible

 

gtk_cell_renderer_get_aligned_area ()

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.

Parameters

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 gtk_cell_renderer_render()

 

aligned_area

the return location for the space inside cell_area that would acually be used to render.

[out]

Since: 3.0


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);

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.

Parameters

cell

a GtkCellRenderer

 

widget

the widget the renderer is rendering to

 

cell_area

The area a cell will be allocated, or NULL.

[allow-none]

x_offset

location to return x offset of cell relative to cell_area , or NULL.

[out][allow-none]

y_offset

location to return y offset of cell relative to cell_area , or NULL.

[out][allow-none]

width

location to return width needed to render a cell, or NULL.

[out][allow-none]

height

location to return height needed to render a cell, or NULL.

[out][allow-none]

gtk_cell_renderer_snapshot ()

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 .

Parameters

cell

a GtkCellRenderer

 

snapshot

a GtkSnapshot 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

 

flags

flags that affect rendering

 

Since: 3.90


gtk_cell_renderer_activate ()

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.

Parameters

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


gtk_cell_renderer_start_editing ()

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.

Parameters

cell

a GtkCellRenderer

 

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 gtk_cell_renderer_render()

 

cell_area

cell area as passed to gtk_cell_renderer_render()

 

flags

render flags

 

Returns

A new GtkCellEditable, or NULL.

[nullable][transfer none]


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.

Parameters

cell

A GtkCellRenderer

 

canceled

TRUE if the editing has been canceled

 

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 .

Parameters

cell

A GtkCellRenderer

 

width

location to fill in with the fixed width of the cell, or NULL.

[out][allow-none]

height

location to fill in with the fixed height of the cell, or NULL.

[out][allow-none]

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.

Parameters

cell

A GtkCellRenderer

 

width

the width of the cell renderer, or -1

 

height

the height of the cell renderer, or -1

 

gtk_cell_renderer_get_visible ()

gboolean
gtk_cell_renderer_get_visible (GtkCellRenderer *cell);

Returns the cell renderer’s visibility.

Parameters

cell

A GtkCellRenderer

 

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.

Parameters

cell

A GtkCellRenderer

 

visible

the visibility of the cell

 

Since: 2.18


gtk_cell_renderer_get_sensitive ()

gboolean
gtk_cell_renderer_get_sensitive (GtkCellRenderer *cell);

Returns the cell renderer’s sensitivity.

Parameters

cell

A GtkCellRenderer

 

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.

Parameters

cell

A GtkCellRenderer

 

sensitive

the sensitivity of the cell

 

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 .

Parameters

cell

A GtkCellRenderer

 

xalign

location to fill in with the x alignment of the cell, or NULL.

[out][allow-none]

yalign

location to fill in with the y alignment of the cell, or NULL.

[out][allow-none]

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.

Parameters

cell

A GtkCellRenderer

 

xalign

the x alignment of the cell renderer

 

yalign

the y alignment of the cell renderer

 

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 .

Parameters

cell

A GtkCellRenderer

 

xpad

location to fill in with the x padding of the cell, or NULL.

[out][allow-none]

ypad

location to fill in with the y padding of the cell, or NULL.

[out][allow-none]

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.

Parameters

cell

A GtkCellRenderer

 

xpad

the x padding of the cell renderer

 

ypad

the y padding of the cell renderer

 

Since: 2.18


gtk_cell_renderer_get_state ()

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.

Parameters

cell

a GtkCellRenderer, or NULL.

[nullable]

widget

a GtkWidget, or NULL.

[nullable]

cell_state

cell renderer state

 

Returns

the widget state flags applying to cell

Since: 3.0


gtk_cell_renderer_is_activatable ()

gboolean
gtk_cell_renderer_is_activatable (GtkCellRenderer *cell);

Checks whether the cell renderer can do something when activated.

Parameters

cell

A GtkCellRenderer

 

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 .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location to store the minimum size, or NULL.

[out][allow-none]

natural_size

location to store the natural size, or NULL.

[out][allow-none]

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 .

Parameters

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 NULL.

[out][allow-none]

natural_height

location for storing the preferred size, or NULL.

[out][allow-none]

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.

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location for storing the minimum size, or NULL.

[out][allow-none]

natural_size

location for storing the natural size, or NULL.

[out][allow-none]

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 .

Parameters

cell

a GtkCellRenderer instance

 

widget

the GtkWidget this cell will be rendering to

 

minimum_size

location to store the minimum size, or NULL.

[out][allow-none]

natural_size

location to store the natural size, or NULL.

[out][allow-none]

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 .

Parameters

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 NULL.

[out][allow-none]

natural_width

location for storing the preferred size, or NULL.

[out][allow-none]

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.

Parameters

cell

a GtkCellRenderer instance

 

Returns

The GtkSizeRequestMode preferred by this renderer.

Since: 3.0

Types and Values

enum GtkCellRendererState

Tells how a cell is to be rendered.

Members

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

The cell is in the focus row.

 

GTK_CELL_RENDERER_EXPANDABLE

The cell is in a row that can be expanded. Since 3.4

 

GTK_CELL_RENDERER_EXPANDED

The cell is in a row that is expanded. Since 3.4

 

enum GtkCellRendererMode

Identifies how the user can interact with a particular cell.

Members

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.

 

struct GtkCellRenderer

struct GtkCellRenderer {
  GInitiallyUnowned parent_instance;
};

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               (* 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);
};

Members

get_request_mode ()

Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.

 

get_preferred_width ()

Called to get a renderer’s natural width.

 

get_preferred_height_for_width ()

Called to get a renderer’s natural height for width.

 

get_preferred_height ()

Called to get a renderer’s natural height.

 

get_preferred_width_for_height ()

Called to get a renderer’s natural width for height.

 

get_aligned_area ()

Called to get the aligned area used by cell inside cell_area .

 

get_size ()

Called to get the width and height needed to render the cell. Deprecated: 3.0.

 

snapshot ()

Called to snapshot the content of the GtkCellRenderer.

 

activate ()

Called to activate the content of the GtkCellRenderer.

 

start_editing ()

Called to initiate editing the content of the GtkCellRenderer.

 

editing_canceled ()

Signal gets emitted when the user cancels the process of editing a cell.

 

editing_started ()

Signal gets emitted when a cell starts to be edited.

 

See Also

GtkCellRendererText, GtkCellRendererPixbuf, GtkCellRendererToggle