:right-sidebar: True CellRenderer =================================================================== .. currentmodule:: gi.repository.Gtk .. deprecated:: 4.10 List views use widgets for displaying their contents .. class:: CellRenderer(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gtk.CellRendererPixbuf`, :class:`~gi.repository.Gtk.CellRendererProgress`, :class:`~gi.repository.Gtk.CellRendererSpinner`, :class:`~gi.repository.Gtk.CellRendererText`, :class:`~gi.repository.Gtk.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 :func:`~gi.repository.Gtk.CellRenderer.get_preferred_size`. Finally, the cell is rendered in the correct location using :func:`~gi.repository.Gtk.CellRenderer.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 ------- .. rst-class:: interim-class .. class:: CellRenderer :no-index: .. method:: activate(event: ~gi.repository.Gdk.Event, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.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:: 4.10 Please do not use it in newly written code :param event: a ``GdkEvent`` :param widget: widget that received the event :param path: widget-dependent string representation of the event location; e.g. for ``GtkTreeView``\, a string representation of ``GtkTreePath`` :param background_area: background area as passed to gtk_cell_renderer_render() :param cell_area: cell area as passed to gtk_cell_renderer_render() :param flags: render flags .. method:: do_activate(self, event: ~gi.repository.Gdk.Event, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> bool :param event: :param widget: :param path: :param background_area: :param cell_area: :param flags: .. method:: do_editing_canceled(self) -> None .. method:: do_editing_started(self, editable: ~gi.repository.Gtk.CellEditable, path: str) -> None :param editable: :param path: .. method:: do_get_aligned_area(self, widget: ~gi.repository.Gtk.Widget, flags: ~gi.repository.Gtk.CellRendererState, cell_area: ~gi.repository.Gdk.Rectangle) -> ~gi.repository.Gdk.Rectangle :param widget: :param flags: :param cell_area: .. method:: do_get_preferred_height(self, widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] :param widget: .. method:: do_get_preferred_height_for_width(self, widget: ~gi.repository.Gtk.Widget, width: int) -> ~typing.Tuple[int, int] :param widget: :param width: .. method:: do_get_preferred_width(self, widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] :param widget: .. method:: do_get_preferred_width_for_height(self, widget: ~gi.repository.Gtk.Widget, height: int) -> ~typing.Tuple[int, int] :param widget: :param height: .. method:: do_get_request_mode(self) -> ~gi.repository.Gtk.SizeRequestMode .. method:: do_snapshot(self, snapshot: ~gi.repository.Gtk.Snapshot, widget: ~gi.repository.Gtk.Widget, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> None :param snapshot: :param widget: :param background_area: :param cell_area: :param flags: .. method:: do_start_editing(self, event: ~gi.repository.Gdk.Event | None, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> ~gi.repository.Gtk.CellEditable | None :param event: :param widget: :param path: :param background_area: :param cell_area: :param flags: .. method:: get_aligned_area(widget: ~gi.repository.Gtk.Widget, flags: ~gi.repository.Gtk.CellRendererState, cell_area: ~gi.repository.Gdk.Rectangle) -> ~gi.repository.Gdk.Rectangle Gets the aligned area used by ``cell`` inside ``cell_area``\. Used for finding the appropriate edit and focus rectangle. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param flags: render flags :param cell_area: cell area which would be passed to gtk_cell_renderer_render() .. method:: get_alignment() -> ~typing.Tuple[float, float] Fills in ``xalign`` and ``yalign`` with the appropriate values of ``cell``\. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_fixed_size() -> ~typing.Tuple[int, int] Fills in ``width`` and ``height`` with the appropriate size of ``cell``\. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_is_expanded() -> bool Checks whether the given ``GtkCellRenderer`` is expanded. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_is_expander() -> bool Checks whether the given ``GtkCellRenderer`` is an expander. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_padding() -> ~typing.Tuple[int, int] Fills in ``xpad`` and ``ypad`` with the appropriate values of ``cell``\. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_preferred_height(widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] Retrieves a renderer’s natural size when rendered to ``widget``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to .. method:: get_preferred_height_for_width(widget: ~gi.repository.Gtk.Widget, width: int) -> ~typing.Tuple[int, int] Retrieves a cell renderers’s minimum and natural height if it were rendered to ``widget`` with the specified ``width``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param width: the size which is available for allocation .. method:: get_preferred_size(widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[~gi.repository.Gtk.Requisition, ~gi.repository.Gtk.Requisition] Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to .. method:: get_preferred_width(widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] Retrieves a renderer’s natural size when rendered to ``widget``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to .. method:: get_preferred_width_for_height(widget: ~gi.repository.Gtk.Widget, height: int) -> ~typing.Tuple[int, int] Retrieves a cell renderers’s minimum and natural width if it were rendered to ``widget`` with the specified ``height``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param height: the size which is available for allocation .. method:: get_request_mode() -> ~gi.repository.Gtk.SizeRequestMode Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_sensitive() -> bool Returns the cell renderer’s sensitivity. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: get_state(widget: ~gi.repository.Gtk.Widget | None, cell_state: ~gi.repository.Gtk.CellRendererState) -> ~gi.repository.Gtk.StateFlags Translates the cell renderer state to ``GtkStateFlags``\, based on the cell renderer and widget sensitivity, and the given ``GtkCellRenderer``\State. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: a ``GtkWidget`` :param cell_state: cell renderer state .. method:: get_visible() -> bool Returns the cell renderer’s visibility. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: is_activatable() -> bool Checks whether the cell renderer can do something when activated. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: set_alignment(xalign: float, yalign: float) -> None Sets the renderer’s alignment within its available space. .. deprecated:: 4.10 Please do not use it in newly written code :param xalign: the x alignment of the cell renderer :param yalign: the y alignment of the cell renderer .. method:: set_fixed_size(width: int, height: int) -> None Sets the renderer size to be explicit, independent of the properties set. .. deprecated:: 4.10 Please do not use it in newly written code :param width: the width of the cell renderer, or -1 :param height: the height of the cell renderer, or -1 .. method:: set_is_expanded(is_expanded: bool) -> None Sets whether the given ``GtkCellRenderer`` is expanded. .. deprecated:: 4.10 Please do not use it in newly written code :param is_expanded: whether ``cell`` should be expanded .. method:: set_is_expander(is_expander: bool) -> None Sets whether the given ``GtkCellRenderer`` is an expander. .. deprecated:: 4.10 Please do not use it in newly written code :param is_expander: whether ``cell`` is an expander .. method:: set_padding(xpad: int, ypad: int) -> None Sets the renderer’s padding. .. deprecated:: 4.10 Please do not use it in newly written code :param xpad: the x padding of the cell renderer :param ypad: the y padding of the cell renderer .. method:: set_sensitive(sensitive: bool) -> None Sets the cell renderer’s sensitivity. .. deprecated:: 4.10 Please do not use it in newly written code :param sensitive: the sensitivity of the cell .. method:: set_visible(visible: bool) -> None Sets the cell renderer’s visibility. .. deprecated:: 4.10 Please do not use it in newly written code :param visible: the visibility of the cell .. method:: snapshot(snapshot: ~gi.repository.Gtk.Snapshot, widget: ~gi.repository.Gtk.Widget, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> None 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``\. .. deprecated:: 4.10 Please do not use it in newly written code :param snapshot: a ``GtkSnapshot`` to draw to :param widget: the widget owning ``window`` :param background_area: entire cell area (including tree expanders and maybe padding on the sides) :param cell_area: area normally rendered by a cell renderer :param flags: flags that affect rendering .. method:: start_editing(event: ~gi.repository.Gdk.Event | None, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> ~gi.repository.Gtk.CellEditable | None Starts editing the contents of this ``cell``\, through a new ``GtkCellEditable`` widget created by the ``GtkCellRenderer``\Class.start_editing virtual function. .. deprecated:: 4.10 Please do not use it in newly written code :param event: a ``GdkEvent`` :param widget: widget that received the event :param path: widget-dependent string representation of the event location; e.g. for ``GtkTreeView``\, a string representation of ``GtkTreePath`` :param background_area: background area as passed to gtk_cell_renderer_render() :param cell_area: cell area as passed to gtk_cell_renderer_render() :param flags: render flags .. method:: stop_editing(canceled: bool) -> None Informs the cell renderer that the editing is stopped. If ``canceled`` is :const:`True`, the cell renderer will emit the ``GtkCellRenderer``\::editing-canceled signal. This function should be called by cell renderer implementations in response to the ``GtkCellEditable::editing-done`` signal of ``GtkCellEditable``\. .. deprecated:: 4.10 Please do not use it in newly written code :param canceled: :const:`True` if the editing has been canceled Properties ---------- .. rst-class:: interim-class .. class:: CellRenderer :no-index: .. attribute:: props.cell_background :type: str The type of the None singleton. .. attribute:: props.cell_background_rgba :type: ~gi.repository.Gdk.RGBA The type of the None singleton. .. attribute:: props.cell_background_set :type: bool The type of the None singleton. .. attribute:: props.editing :type: bool The type of the None singleton. .. attribute:: props.height :type: int The type of the None singleton. .. attribute:: props.is_expanded :type: bool The type of the None singleton. .. attribute:: props.is_expander :type: bool The type of the None singleton. .. attribute:: props.mode :type: ~gi.repository.Gtk.CellRendererMode The type of the None singleton. .. attribute:: props.sensitive :type: bool The type of the None singleton. .. attribute:: props.visible :type: bool The type of the None singleton. .. attribute:: props.width :type: int The type of the None singleton. .. attribute:: props.xalign :type: float The type of the None singleton. .. attribute:: props.xpad :type: int The type of the None singleton. .. attribute:: props.yalign :type: float The type of the None singleton. .. attribute:: props.ypad :type: int The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: CellRenderer.signals :no-index: .. method:: editing_canceled() -> None The type of the None singleton. .. method:: editing_started(editable: ~gi.repository.Gtk.CellEditable, path: str) -> None The type of the None singleton. :param editable: the ``GtkCellEditable`` :param path: the path identifying the edited cell Virtual Methods --------------- .. rst-class:: interim-class .. class:: CellRenderer :no-index: .. method:: do_activate(event: ~gi.repository.Gdk.Event, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.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:: 4.10 Please do not use it in newly written code :param event: a ``GdkEvent`` :param widget: widget that received the event :param path: widget-dependent string representation of the event location; e.g. for ``GtkTreeView``\, a string representation of ``GtkTreePath`` :param background_area: background area as passed to gtk_cell_renderer_render() :param cell_area: cell area as passed to gtk_cell_renderer_render() :param flags: render flags .. method:: do_editing_canceled() -> None The type of the None singleton. .. method:: do_editing_started(editable: ~gi.repository.Gtk.CellEditable, path: str) -> None The type of the None singleton. :param editable: :param path: .. method:: do_get_aligned_area(widget: ~gi.repository.Gtk.Widget, flags: ~gi.repository.Gtk.CellRendererState, cell_area: ~gi.repository.Gdk.Rectangle) -> ~gi.repository.Gdk.Rectangle Gets the aligned area used by ``cell`` inside ``cell_area``\. Used for finding the appropriate edit and focus rectangle. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param flags: render flags :param cell_area: cell area which would be passed to gtk_cell_renderer_render() .. method:: do_get_preferred_height(widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] Retrieves a renderer’s natural size when rendered to ``widget``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to .. method:: do_get_preferred_height_for_width(widget: ~gi.repository.Gtk.Widget, width: int) -> ~typing.Tuple[int, int] Retrieves a cell renderers’s minimum and natural height if it were rendered to ``widget`` with the specified ``width``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param width: the size which is available for allocation .. method:: do_get_preferred_width(widget: ~gi.repository.Gtk.Widget) -> ~typing.Tuple[int, int] Retrieves a renderer’s natural size when rendered to ``widget``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to .. method:: do_get_preferred_width_for_height(widget: ~gi.repository.Gtk.Widget, height: int) -> ~typing.Tuple[int, int] Retrieves a cell renderers’s minimum and natural width if it were rendered to ``widget`` with the specified ``height``\. .. deprecated:: 4.10 Please do not use it in newly written code :param widget: the ``GtkWidget`` this cell will be rendering to :param height: the size which is available for allocation .. method:: do_get_request_mode() -> ~gi.repository.Gtk.SizeRequestMode Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. .. deprecated:: 4.10 Please do not use it in newly written code .. method:: do_snapshot(snapshot: ~gi.repository.Gtk.Snapshot, widget: ~gi.repository.Gtk.Widget, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> None 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``\. .. deprecated:: 4.10 Please do not use it in newly written code :param snapshot: a ``GtkSnapshot`` to draw to :param widget: the widget owning ``window`` :param background_area: entire cell area (including tree expanders and maybe padding on the sides) :param cell_area: area normally rendered by a cell renderer :param flags: flags that affect rendering .. method:: do_start_editing(event: ~gi.repository.Gdk.Event | None, widget: ~gi.repository.Gtk.Widget, path: str, background_area: ~gi.repository.Gdk.Rectangle, cell_area: ~gi.repository.Gdk.Rectangle, flags: ~gi.repository.Gtk.CellRendererState) -> ~gi.repository.Gtk.CellEditable | None Starts editing the contents of this ``cell``\, through a new ``GtkCellEditable`` widget created by the ``GtkCellRenderer``\Class.start_editing virtual function. .. deprecated:: 4.10 Please do not use it in newly written code :param event: a ``GdkEvent`` :param widget: widget that received the event :param path: widget-dependent string representation of the event location; e.g. for ``GtkTreeView``\, a string representation of ``GtkTreePath`` :param background_area: background area as passed to gtk_cell_renderer_render() :param cell_area: cell area as passed to gtk_cell_renderer_render() :param flags: render flags Fields ------ .. rst-class:: interim-class .. class:: CellRenderer :no-index: .. attribute:: parent_instance .. attribute:: priv