GtkCellRenderer: GTK+ 2 Reference Manual

GtkCellRenderer

Functions

void	gtk_cell_renderer_get_size ()
void	gtk_cell_renderer_render ()
gboolean	gtk_cell_renderer_activate ()
GtkCellEditable *	gtk_cell_renderer_start_editing ()
void	gtk_cell_renderer_editing_canceled ()
void	gtk_cell_renderer_stop_editing ()
void	gtk_cell_renderer_get_fixed_size ()
void	gtk_cell_renderer_set_fixed_size ()
gboolean	gtk_cell_renderer_get_visible ()
void	gtk_cell_renderer_set_visible ()
gboolean	gtk_cell_renderer_get_sensitive ()
void	gtk_cell_renderer_set_sensitive ()
void	gtk_cell_renderer_get_alignment ()
void	gtk_cell_renderer_set_alignment ()
void	gtk_cell_renderer_get_padding ()
void	gtk_cell_renderer_set_padding ()

Properties

char *	cell-background	Write
GdkColor *	cell-background-gdk	Read / Write
gboolean	cell-background-set	Read / Write
gboolean	editing	Read
int	height	Read / Write
gboolean	is-expanded	Read / Write
gboolean	is-expander	Read / Write
GtkCellRendererMode	mode	Read / Write
gboolean	sensitive	Read / Write
gboolean	visible	Read / Write
int	width	Read / Write
float	xalign	Read / Write
guint	xpad	Read / Write
float	yalign	Read / Write
guint	ypad	Read / Write

Signals

void	editing-canceled	Run First
void	editing-started	Run First

Types and Values

enum	GtkCellRendererState
enum	GtkCellRendererMode
struct	GtkCellRenderer
struct	GtkCellRendererClass

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkCellRenderer
                ├── GtkCellRendererText
                ├── GtkCellRendererPixbuf
                ├── GtkCellRendererProgress
                ├── GtkCellRendererSpinner
                ╰── GtkCellRendererToggle

Includes

#include <gtk/gtk.h>

Description

Functions

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.

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

void
gtk_cell_renderer_render (GtkCellRenderer *cell,
                          GdkWindow *window,
                          GtkWidget *widget,
                          const GdkRectangle *background_area,
                          const GdkRectangle *cell_area,
                          const 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.

Parameters

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

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

[transfer none]

gtk_cell_renderer_editing_canceled ()

void
gtk_cell_renderer_editing_canceled (GtkCellRenderer *cell);

gtk_cell_renderer_editing_canceled has been deprecated since version 2.6 and should not be used in newly-written code.

Use gtk_cell_renderer_stop_editing() instead

Causes the cell renderer to emit the “editing-canceled” signal.

This function is for use only by implementations of cell renderers that need to notify the client program that an editing process was canceled and the changes were not committed.

Parameters

cell

A GtkCellRenderer

Since: 2.4

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

Types and Values

enum GtkCellRendererState

Members

GTK_CELL_RENDERER_SELECTED
GTK_CELL_RENDERER_PRELIT
GTK_CELL_RENDERER_INSENSITIVE
GTK_CELL_RENDERER_SORTED
GTK_CELL_RENDERER_FOCUSED

enum GtkCellRendererMode

Members

GTK_CELL_RENDERER_MODE_INERT
GTK_CELL_RENDERER_MODE_ACTIVATABLE
GTK_CELL_RENDERER_MODE_EDITABLE

struct GtkCellRenderer

struct GtkCellRenderer;

struct GtkCellRendererClass

struct GtkCellRendererClass {
  GtkObjectClass parent_class;

  /* vtable - not signals */
  void             (* get_size)      (GtkCellRenderer      *cell,
				      GtkWidget            *widget,
				      GdkRectangle         *cell_area,
				      gint                 *x_offset,
				      gint                 *y_offset,
				      gint                 *width,
				      gint                 *height);
  void             (* render)        (GtkCellRenderer      *cell,
				      GdkDrawable          *window,
				      GtkWidget            *widget,
				      GdkRectangle         *background_area,
				      GdkRectangle         *cell_area,
				      GdkRectangle         *expose_area,
				      GtkCellRendererState  flags);
  gboolean         (* activate)      (GtkCellRenderer      *cell,
				      GdkEvent             *event,
				      GtkWidget            *widget,
				      const gchar          *path,
				      GdkRectangle         *background_area,
				      GdkRectangle         *cell_area,
				      GtkCellRendererState  flags);
  GtkCellEditable *(* start_editing) (GtkCellRenderer      *cell,
				      GdkEvent             *event,
				      GtkWidget            *widget,
				      const gchar          *path,
				      GdkRectangle         *background_area,
				      GdkRectangle         *cell_area,
				      GtkCellRendererState  flags);

  /* Signals */
  void (* editing_canceled) (GtkCellRenderer *cell);
  void (* editing_started)  (GtkCellRenderer *cell,
			     GtkCellEditable *editable,
			     const gchar     *path);

  /* Padding for future expansion */
  void (*_gtk_reserved1) (void);
  void (*_gtk_reserved2) (void);
};

Property Details

The `“cell-background”` property

  “cell-background”          char *

Cell background color as a string.

Owner: GtkCellRenderer

Flags: Write

Default value: NULL

The `“cell-background-gdk”` property

  “cell-background-gdk”      GdkColor *

Cell background color as a GdkColor.

Owner: GtkCellRenderer

Flags: Read / Write

The `“cell-background-set”` property

  “cell-background-set”      gboolean

Whether this tag affects the cell background color.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: FALSE

The `“editing”` property

  “editing”                  gboolean

Whether the cell renderer is currently in editing mode.

Owner: GtkCellRenderer

Flags: Read

Default value: FALSE

The `“height”` property

  “height”                   int

The fixed height.

Owner: GtkCellRenderer

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“is-expanded”` property

  “is-expanded”              gboolean

Row is an expander row, and is expanded.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: FALSE

The `“is-expander”` property

  “is-expander”              gboolean

Row has children.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: FALSE

The `“mode”` property

  “mode”                     GtkCellRendererMode

Editable mode of the CellRenderer.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: GTK_CELL_RENDERER_MODE_INERT

The `“sensitive”` property

  “sensitive”                gboolean

Display the cell sensitive.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: TRUE

The `“visible”` property

  “visible”                  gboolean

Display the cell.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: TRUE

The `“width”` property

  “width”                    int

The fixed width.

Owner: GtkCellRenderer

Flags: Read / Write

Allowed values: >= -1

Default value: -1

The `“xalign”` property

  “xalign”                   float

The x-align.

Owner: GtkCellRenderer

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.5

The `“xpad”` property

  “xpad”                     guint

The xpad.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: 0

The `“yalign”` property

  “yalign”                   float

The y-align.

Owner: GtkCellRenderer

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.5

The `“ypad”` property

  “ypad”                     guint

The ypad.

Owner: GtkCellRenderer

Flags: Read / Write

Default value: 0

Signal Details

The `“editing-canceled”` signal

void
user_function (GtkCellRenderer *renderer,
               gpointer         user_data)

This signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses Escape.

Parameters

renderer	the object which received the signal
user_data	user data set when the signal handler was connected.

Flags: Run First

Since: 2.4

The `“editing-started”` signal

void
user_function (GtkCellRenderer *renderer,
               GtkCellEditable *editable,
               char            *path,
               gpointer         user_data)

This signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on editable , e.g. adding a GtkEntryCompletion or setting up additional columns in a GtkComboBox.

Note that GTK+ doesn't guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of editable before doing any specific setup, as in the following example:

static void
text_editing_started (GtkCellRenderer *cell,
                      GtkCellEditable *editable,
                      const gchar     *path,
                      gpointer         data)
{
  if (GTK_IS_ENTRY (editable))

    {
      GtkEntry *entry = GTK_ENTRY (editable);

      /* ... create a GtkEntryCompletion */

      gtk_entry_set_completion (entry, completion);
    }
}

Parameters

renderer	the object which received the signal
editable	the GtkCellEditable
path	the path identifying the edited cell
user_data	user data set when the signal handler was connected.

Flags: Run First

Since: 2.6