An object for rendering a single cell on a GdkDrawable
Class GtkCellRenderer
The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a GdkDrawable. 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 GdkDrawable. 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_render().
There are a number of rules that must be followed when writing a new GtkCellRenderer. First and formost, 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 activate or start_editing virtual functions, respectively.
| Methods | |
| activate | Passes an activate event to the cell renderer for possible processing. |
| get_alignment | Returns xalign and yalign of the cell. |
| get_fixed_size | Fills in width and height with the appropriate size of cell. |
| get_padding | Returns xpad and ypad of the cell. |
| get_sensitive | Returns the cell renderer's sensitivity. |
| get_size | Obtains the width and height needed to render the cell. |
| get_visible | Returns the cell renderer's visibility. |
| render | Invokes the virtual render function of the GtkCellRenderer. |
| set_alignment | Sets the renderer's alignment within its available space. |
| set_fixed_size | Sets the renderer size to be explicit, independent of the properties set. |
| set_padding | Sets the renderer's padding. |
| set_sensitive | Sets the cell renderer's sensitivity. |
| set_visible | Sets the cell renderer's visibility. |
| signal_editing_canceled | This signal gets emitted when the user cancels the process of editing a cell. |
| signal_editing_started | This signal gets emitted when a cell starts to be edited. |
| start_editing | Passes an activate event to the cell renderer for possible processing. |
| stop_editing | Informs the cell renderer that the editing is stopped. |
Passes an activate event to the cell renderer for possible processing.
GtkCellRenderer.activate( event, widget, path, background_area, cell_area, flags )
| event | a GdkEvent |
| widget | widget that received the event (GtkWidget). |
| 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() (GdkRectangle). |
| cell_area | cell area as passed to gtk_cell_renderer_render() (GdkRectangle) |
| flags | render flags (GtkCellRendererState) |
| Return | TRUE if the event was consumed/handled |
Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse click.
Returns xalign and yalign of the cell.
GtkCellRenderer.get_alignment()
| Return | an array [ x alignment, y alignment ] |
Fills in width and height with the appropriate size of cell.
GtkCellRenderer.get_fixed_size()
| Return | an array [ fixed width of the cell, fixed height of the cell ]. |
Returns xpad and ypad of the cell.
GtkCellRenderer.get_padding()
| Return | an array ( x padding, y padding ) |
Returns the cell renderer's sensitivity.
GtkCellRenderer.get_sensitive()
| Return | TRUE if the cell renderer is sensitive |
Obtains the width and height needed to render the cell.
GtkCellRenderer.get_size( widget, cell_area )
| widget | the widget the renderer is rendering to |
| cell_area | The area a cell will be allocated (GdkRectangle), or nil. |
| Return | an array ( xoffset, yoffset, width, height ). |
Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_render().
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.
Returns the cell renderer's visibility.
GtkCellRenderer.get_visible()
| Return | TRUE if the cell renderer is visible |
Invokes the virtual render function of the GtkCellRenderer.
GtkCellRenderer.render( window, widget, background_area, cell_area, expose_area, flags )
| window | a GdkDrawable to draw to |
| widget | the widget owning window |
| background_area | entire cell area (GdkRectangle) (including tree expanders and maybe padding on the sides) |
| cell_area | area normally rendered by a cell renderer (GdkRectangle) |
| expose_area | area that actually needs updating (GdkRectangle) |
| flags | flags that affect rendering (GtkCellRendererState) |
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.
Sets the renderer's alignment within its available space.
GtkCellRenderer.set_alignment( x, y )
| x | the x alignment of the cell renderer |
| y | the y alignment of the cell renderer |
Sets the renderer size to be explicit, independent of the properties set.
GtkCellRenderer.set_fixed_size( width, height )
| width | the width of the cell renderer, or -1 |
| height | the height of the cell renderer, or -1 |
Sets the renderer's padding.
GtkCellRenderer.set_padding( xpad, ypad )
| xpad | the x padding of the cell renderer |
| ypad | the y padding of the cell renderer |
Sets the cell renderer's sensitivity.
GtkCellRenderer.set_sensitive( sensitive )
| sensitive | the sensitivity of the cell |
Sets the cell renderer's visibility.
GtkCellRenderer.set_visible( visible )
| visible | the visibility of the cell |
This signal gets emitted when the user cancels the process of editing a cell.
GtkCellRenderer.signal_editing_canceled()
For example, an editable cell renderer could be written to cancel editing when the user presses Escape.
See also: gtk_cell_renderer_stop_editing().
This signal gets emitted when a cell starts to be edited.
GtkCellRenderer.signal_editing_started()
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.
[...]
Passes an activate event to the cell renderer for possible processing.
GtkCellRenderer.start_editing( event, widget, path, background_area, cell_area, flags )
| event | a GdkEvent |
| widget | widget that received the event (GtkWidget). |
| 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() (GdkRectangle). |
| cell_area | cell area as passed to gtk_cell_renderer_render() (GdkRectangle) |
| flags | render flags (GtkCellRendererState) |
| Return | A new GtkCellEditable, or NULL |
Informs the cell renderer that the editing is stopped.
GtkCellRenderer.stop_editing( canceled )
| canceled | TRUE if the editing has been canceled |
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.