11.36Class GtkCellRenderer

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
activatePasses an activate event to the cell renderer for possible processing.
get_alignmentReturns xalign and yalign of the cell.
get_fixed_sizeFills in width and height with the appropriate size of cell.
get_paddingReturns xpad and ypad of the cell.
get_sensitiveReturns the cell renderer's sensitivity.
get_sizeObtains the width and height needed to render the cell.
get_visibleReturns the cell renderer's visibility.
renderInvokes the virtual render function of the GtkCellRenderer.
set_alignmentSets the renderer's alignment within its available space.
set_fixed_sizeSets the renderer size to be explicit, independent of the properties set.
set_paddingSets the renderer's padding.
set_sensitiveSets the cell renderer's sensitivity.
set_visibleSets the cell renderer's visibility.
signal_editing_canceledThis signal gets emitted when the user cancels the process of editing a cell.
signal_editing_startedThis signal gets emitted when a cell starts to be edited.
start_editingPasses an activate event to the cell renderer for possible processing.
stop_editingInforms the cell renderer that the editing is stopped.

Methods

activate

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)
ReturnTRUE if the event was consumed/handled

Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse click.

get_alignment

Returns xalign and yalign of the cell.

GtkCellRenderer.get_alignment()
Returnan array [ x alignment, y alignment ]

get_fixed_size

Fills in width and height with the appropriate size of cell.

GtkCellRenderer.get_fixed_size()
Returnan array [ fixed width of the cell, fixed height of the cell ].

get_padding

Returns xpad and ypad of the cell.

GtkCellRenderer.get_padding()
Returnan array ( x padding, y padding )

get_sensitive

Returns the cell renderer's sensitivity.

GtkCellRenderer.get_sensitive()
ReturnTRUE if the cell renderer is sensitive

get_size

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

get_visible

Returns the cell renderer's visibility.

GtkCellRenderer.get_visible()
ReturnTRUE if the cell renderer is visible

render

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.

set_alignment

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

set_fixed_size

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

set_padding

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

set_sensitive

Sets the cell renderer's sensitivity.

GtkCellRenderer.set_sensitive( sensitive )
sensitive the sensitivity of the cell

set_visible

Sets the cell renderer's visibility.

GtkCellRenderer.set_visible( visible )
visible the visibility of the cell

signal_editing_canceled

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

signal_editing_started

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.

[...]

start_editing

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)
ReturnA new GtkCellEditable, or NULL

stop_editing

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.

Made with http://www.falconpl.org