gtk.CellRenderer
Prev | The gtk Class Reference | Next

## gtk.CellRenderer

gtk.CellRenderer — a base class for objects that render on a `gtk.gdk.Drawable`

## Synopsis

    class gtk.CellRenderer(gtk.Object):
        def get_size(widget, cell_area=None)
        def render(window, widget, background_area, cell_area, expose_area, flags)
        def activate(event, widget, path, background_area, cell_area, flags)
        def start_editing(event, widget, path, background_area, cell_area, flags)
        def editing_canceled()
        def stop_editing(canceled)
        def set_fixed_size(width, height)
        def get_fixed_size()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.CellRenderer

## gtk.CellRenderer Properties

gtk.Object Properties

"cell-background" | Write | The background color of the cell as a string. Default: None.
"cell-background-gdk" | Read/Write | The background color of the cell as a `gtk.gdk.Color`.
"cell-background-set" | Read/Write | If TRUE the cell background color is set by this cellrenderer. Default: FALSE.
"height" | Read/Write | The fixed height of the cell. Allowed values >= -1. Default: -1.
"is-expanded" | Read/Write | If TRUE the row has children and it is expanded to show the children. Default: FALSE.
"is-expander" | Read/Write | If TRUE the row has children. Default: FALSE.
"mode" | Read/Write | The editable mode of the cellrenderer. One of the GTK CellRenderer Mode Constants. Default: `gtk.CELL_RENDERER_MODE_INERT`,
"sensitive" | Read/Write | If TRUE the cell is displayed as sensitive. Available in GTK+ 2.6 and above. Default: TRUE.
"visible" | Read/Write | If TRUE the cell is displayed. Default: TRUE.
"width" | Read/Write | The fixed width of the cell. Allowed values >= -1. Default: -1.
"xalign" | Read/Write | The fraction of free space to the left of the cell in the range 0.0 to 1.0. Allowed values between 0 and 1. Default: 0.5.
"xpad" | Read/Write | The amount of padding to the left and right of the cell. Default: 0.
"yalign" | Read/Write | The fraction of free space above the cell in the range 0.0 to 1.0. Allowed values between 0 and 1. Default: 0.5.
"ypad" | Read/Write | The amount of padding above and below cell. Default: 0.

## gtk.CellRenderer Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

"editing-canceled" | `def callback(`cellrenderer`, `user_param1`, `...`)`
"editing-started" | `def callback(`cellrenderer`, `editable`, `path`, `user_param1`, `...`)`

## Description

The `gtk.CellRenderer` is a base class for a set of objects used for rendering a cell to a `gtk.gdk.Drawable`. The `gtk.CellRenderer` provides the common attributes and methods for its subclasses (`gtk.CellRendererPixbuf`, `gtk.CellRendererText` and `gtk.CellRendererToggle`).

The primary use of a `gtk.CellRenderer` is for drawing a certain graphical elements on a `gtk.gdk.Drawable`. 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 the GObjects property system. Then, the cell is measured using the `get_size`() method. Finally, the cell is rendered in the correct location using the `render`() method.

## Methods

### gtk.CellRenderer.get_size

        def get_size(widget, cell_area)

`widget` : | the widget the renderer is rendering to
`cell_area` : | The area a cell will be allocated, or `None`
Returns : | a tuple containing the xoffset, yoffset, width and height

The `get_size`() method obtains the width and height needed to render the cell. These values are returned as part of a tuple containing the x_offset, y_offset, width and height. `get_size`() is used by view widgets to determine the appropriate size for the `cell_area` to be passed to the `gtk.CellRenderer.render()` method. If `cell_area` is not `None`, the x and y offsets of the cell relative to this location are returned. Please note that the values set in the returned width and height, as well as those in x_offset and y_offset are inclusive of the xpad and ypad properties.

### gtk.CellRenderer.render

        def render(window, widget, background_area, cell_area, expose_area, flags)

`window` : | a `gtk.gdk.Drawable` 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

The `render`() method invokes the virtual render function of the `gtk.CellRenderer`. The three passed-in rectangles are areas of `window`. Most renderers will draw within `cell_area`; the xalign, yalign, xpad, and ypad properties of the `gtk.CellRenderer` 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.

The `flags` value is one of: `gtk.CELL_RENDERER_SELECTED`, `gtk.CELL_RENDERER_PRELIT`, `gtk.CELL_RENDERER_INSENSITIVE` or `gtk.CELL_RENDERER_SORTED`

### gtk.CellRenderer.activate

        def activate(event, widget, path, background_area, cell_area, flags)

`event` : | a `gtk.gdk.Event`
`widget` : | widget that received the event
`path` : | widget-dependent string representation of the event location; e.g. for `gtk.TreeView`, a string representation of `gtk.TreePath`
`background_area` : | background area as passed to `render`()
`cell_area` : | cell area as passed to `render`()
`flags` : | render flags
Returns : | `TRUE` if the event was consumed/handled

The `activate`() method passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, `gtk.CellRendererToggle` toggles when it gets a mouse click.

The `flags` value is one of: `gtk.CELL_RENDERER_SELECTED`, `gtk.CELL_RENDERER_PRELIT`, `gtk.CELL_RENDERER_INSENSITIVE` or `gtk.CELL_RENDERER_SORTED`

### gtk.CellRenderer.start_editing

        def start_editing(event, widget, path, background_area, cell_area, flags)

`event` : | a `gtk.gdk.Event`
`widget` : | the widget that received the event
`path` : | a widget-dependent string representation of the event location; e.g. for `gtk.TreeView`, a string representation of `gtk.TreePath`
`background_area` : | background area as passed to `render`().
`cell_area` : | cell area as passed to `render`()
`flags` : | render flags
Returns : | A new `gtk.CellEditable`, or `None`

The `start_editing`() method initiates the editing of a cell.

### gtk.CellRenderer.editing_canceled

        def editing_canceled()

### Note

This method is available in PyGTK 2.4 and above.

### Warning

This method is deprecated in PyGTK 2.6 and above. Use the `stop_editing`() method instead.

The `editing_canceled`() method causes the cell renderer to emit the "editing-canceled" signal. This method 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.

### gtk.CellRenderer.stop_editing

        def stop_editing(canceled)

`canceled` : | if `TRUE` the editing has been canceled

### Note

This method is available in PyGTK 2.6 and above.

The `stop_editing`() method informs the cell renderer that the editing is stopped. If `canceled` is `TRUE`, the cell renderer will emit the "editing-canceled" signal. This method should be called by cell renderer implementations in response to the "editing-done" signal of `gtk.CellEditable`.

### gtk.CellRenderer.set_fixed_size

        def set_fixed_size(width, height)

`width` : | the width of the cell renderer, or -1
`height` : | the height of the cell renderer, or -1

The `set_fixed_size`() method sets the renderer size to the specified `width` and `height`, independent of the properties set.

### gtk.CellRenderer.get_fixed_size

        def get_fixed_size()

Returns : | a tuple containing the width and height of the cell

The `get_fixed_size`() method retrieves a tuple containing the fixed `width` and `height` of the cell.

## Signals

### The "editing-canceled" gtk.CellRenderer Signal

        def callback(cellrenderer, user_param1, ...)

`cellrenderer` : | the cellrenderer that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.4 and above.

The "editing-canceled" signal is 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. Also see the `editing_canceled`() method.

### The "editing-started" gtk.CellRenderer Signal

        def callback(cellrenderer, editable, path, user_param1, ...)

`cellrenderer` : | the cellrenderer that received the signal
`editable` : | the `gtk.CellEditable`
`path` : | he path identifying the edited cell
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.6 and above.

The "editing-started" signal is 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 `gtk.EntryCompletion` or setting up additional columns in a `gtk.ComboBox`.

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:

    def text_editing_started(cell, editable, path, data):
      if isinstance(editable, gtk.Entry):
          # ... create a GtkEntryCompletion
          completion = gtk.EntryCompletion()
          editable.set_completion(completion)
          ...
      ...

Prev | Up | Next
gtk.CellLayout | Home | gtk.CellRendererAccel