CellRenderer
Deprecated since version 4.10: List views use widgets for displaying their contents
Superclasses: InitiallyUnowned
, Object
Subclasses: CellRendererPixbuf
, CellRendererProgress
, CellRendererSpinner
, CellRendererText
, CellRendererToggle
An object for rendering a single cell
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 GObject
’s property system. Then, the
cell is measured using get_preferred_size()
. Finally, the cell
is rendered in the correct location using 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 style 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 GtkCellRenderer``Toggle,
which toggles when it gets activated by a mouse click, or it can be
“editable” like ``GtkCellRenderer``Text, 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 ``GtkCellRenderer``Class.activate or
``GtkCellRenderer``Class.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.
Methods
- class CellRenderer
- activate(event: Event, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) bool
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.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
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 ofGtkTreePath
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
- get_aligned_area(widget: Widget, flags: CellRendererState, cell_area: Rectangle) Rectangle
Gets the aligned area used by
cell
insidecell_area
. Used for finding the appropriate edit and focus rectangle.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering toflags – render flags
cell_area – cell area which would be passed to gtk_cell_renderer_render()
- get_alignment() tuple[float, float]
Fills in
xalign
andyalign
with the appropriate values ofcell
.Deprecated since version 4.10: Please do not use it in newly written code
- get_fixed_size() tuple[int, int]
Fills in
width
andheight
with the appropriate size ofcell
.Deprecated since version 4.10: Please do not use it in newly written code
- get_is_expanded() bool
Checks whether the given
GtkCellRenderer
is expanded.Deprecated since version 4.10: Please do not use it in newly written code
- get_is_expander() bool
Checks whether the given
GtkCellRenderer
is an expander.Deprecated since version 4.10: Please do not use it in newly written code
- get_padding() tuple[int, int]
Fills in
xpad
andypad
with the appropriate values ofcell
.Deprecated since version 4.10: Please do not use it in newly written code
- get_preferred_height(widget: Widget) tuple[int, int]
Retrieves a renderer’s natural size when rendered to
widget
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering to
- get_preferred_height_for_width(widget: Widget, width: int) tuple[int, int]
Retrieves a cell renderers’s minimum and natural height if it were rendered to
widget
with the specifiedwidth
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering towidth – the size which is available for allocation
- get_preferred_size(widget: Widget) tuple[Requisition, Requisition]
Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering to
- get_preferred_width(widget: Widget) tuple[int, int]
Retrieves a renderer’s natural size when rendered to
widget
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering to
- get_preferred_width_for_height(widget: Widget, height: int) tuple[int, int]
Retrieves a cell renderers’s minimum and natural width if it were rendered to
widget
with the specifiedheight
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering toheight – the size which is available for allocation
- get_request_mode() SizeRequestMode
Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.
Deprecated since version 4.10: Please do not use it in newly written code
- get_sensitive() bool
Returns the cell renderer’s sensitivity.
Deprecated since version 4.10: Please do not use it in newly written code
- get_state(widget: Widget | None, cell_state: CellRendererState) StateFlags
Translates the cell renderer state to
GtkStateFlags
, based on the cell renderer and widget sensitivity, and the given ``GtkCellRenderer``State.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – a
GtkWidget
cell_state – cell renderer state
- get_visible() bool
Returns the cell renderer’s visibility.
Deprecated since version 4.10: Please do not use it in newly written code
- is_activatable() bool
Checks whether the cell renderer can do something when activated.
Deprecated since version 4.10: Please do not use it in newly written code
- set_alignment(xalign: float, yalign: float) None
Sets the renderer’s alignment within its available space.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
xalign – the x alignment of the cell renderer
yalign – the y alignment of the cell renderer
- set_fixed_size(width: int, height: int) None
Sets the renderer size to be explicit, independent of the properties set.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
width – the width of the cell renderer, or -1
height – the height of the cell renderer, or -1
- set_is_expanded(is_expanded: bool) None
Sets whether the given
GtkCellRenderer
is expanded.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
is_expanded – whether
cell
should be expanded
- set_is_expander(is_expander: bool) None
Sets whether the given
GtkCellRenderer
is an expander.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
is_expander – whether
cell
is an expander
- set_padding(xpad: int, ypad: int) None
Sets the renderer’s padding.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
xpad – the x padding of the cell renderer
ypad – the y padding of the cell renderer
- set_sensitive(sensitive: bool) None
Sets the cell renderer’s sensitivity.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
sensitive – the sensitivity of the cell
- set_visible(visible: bool) None
Sets the cell renderer’s visibility.
Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
visible – the visibility of the cell
- snapshot(snapshot: Snapshot, widget: Widget, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) None
Invokes the virtual render function of the
GtkCellRenderer
. The three passed-in rectangles are areas incr
. Most renderers will draw withincell_area
; the xalign, yalign, xpad, and ypad fields of theGtkCellRenderer
should be honored with respect tocell_area
.background_area
includes the blank space around the cell, and also the area containing the tree expander; so thebackground_area
rectangles for all cells tile to cover the entirewindow
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
snapshot – a
GtkSnapshot
to draw towidget – 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
- start_editing(event: Event | None, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) CellEditable | None
Starts editing the contents of this
cell
, through a newGtkCellEditable
widget created by the ``GtkCellRenderer``Class.start_editing virtual function.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
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 ofGtkTreePath
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
- stop_editing(canceled: bool) None
Informs the cell renderer that the editing is stopped. If
canceled
isTrue
, the cell renderer will emit theGtkCellRenderer
::editing-canceled signal.This function should be called by cell renderer implementations in response to the
GtkCellEditable::editing-done
signal ofGtkCellEditable
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
canceled –
True
if the editing has been canceled
Properties
- class CellRenderer
-
- props.mode: CellRendererMode
Signals
- class CellRenderer.signals
- editing_canceled() None
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.
See also:
stop_editing()
.
- editing_started(editable: CellEditable, path: str) None
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 aGtkEntryCompletion
or setting up additional columns in aGtkComboBox
.See
start_editing()
for information on the lifecycle of theeditable
and a way to do setup that doesn’t depend on therenderer
.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 char *path, gpointer data) { if (GTK_IS_ENTRY (editable)) { GtkEntry *entry = GTK_ENTRY (editable); // ... create a GtkEntryCompletion gtk_entry_set_completion (entry, completion); } }
- Parameters:
editable – the
GtkCellEditable
path – the path identifying the edited cell
Virtual Methods
- class CellRenderer
- do_activate(event: Event, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) bool
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.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
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 ofGtkTreePath
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
- do_editing_canceled() None
Signal gets emitted when the user cancels the process of editing a cell.
- do_editing_started(editable: CellEditable, path: str) None
Signal gets emitted when a cell starts to be edited.
- Parameters:
editable
path
- do_get_aligned_area(widget: Widget, flags: CellRendererState, cell_area: Rectangle) Rectangle
Gets the aligned area used by
cell
insidecell_area
. Used for finding the appropriate edit and focus rectangle.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering toflags – render flags
cell_area – cell area which would be passed to gtk_cell_renderer_render()
- do_get_preferred_height(widget: Widget) tuple[int, int]
Retrieves a renderer’s natural size when rendered to
widget
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering to
- do_get_preferred_height_for_width(widget: Widget, width: int) tuple[int, int]
Retrieves a cell renderers’s minimum and natural height if it were rendered to
widget
with the specifiedwidth
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering towidth – the size which is available for allocation
- do_get_preferred_width(widget: Widget) tuple[int, int]
Retrieves a renderer’s natural size when rendered to
widget
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering to
- do_get_preferred_width_for_height(widget: Widget, height: int) tuple[int, int]
Retrieves a cell renderers’s minimum and natural width if it were rendered to
widget
with the specifiedheight
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
widget – the
GtkWidget
this cell will be rendering toheight – the size which is available for allocation
- do_get_request_mode() SizeRequestMode
Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout.
Deprecated since version 4.10: Please do not use it in newly written code
- do_snapshot(snapshot: Snapshot, widget: Widget, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) None
Invokes the virtual render function of the
GtkCellRenderer
. The three passed-in rectangles are areas incr
. Most renderers will draw withincell_area
; the xalign, yalign, xpad, and ypad fields of theGtkCellRenderer
should be honored with respect tocell_area
.background_area
includes the blank space around the cell, and also the area containing the tree expander; so thebackground_area
rectangles for all cells tile to cover the entirewindow
.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
snapshot – a
GtkSnapshot
to draw towidget – 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
- do_start_editing(event: Event | None, widget: Widget, path: str, background_area: Rectangle, cell_area: Rectangle, flags: CellRendererState) CellEditable | None
Starts editing the contents of this
cell
, through a newGtkCellEditable
widget created by the ``GtkCellRenderer``Class.start_editing virtual function.Deprecated since version 4.10: Please do not use it in newly written code
- Parameters:
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 ofGtkTreePath
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