1Gtk2::CellRenderer(3) User Contributed Perl DocumentationGtk2::CellRenderer(3)
2
6 Gtk2::CellRenderer - An object that renders a single cell onto a
7 Gtk2::Gdk::Drawable
8
10 The Gtk2::CellRenderer is the base class for objects which render cells
11 onto drawables. These objects are used primarily by the Gtk2::Tree‐
12 View, though they aren't tied to them in any specific way.
13 Typically, one cell renderer is used to draw many cells onto the
15 screen. Thus, the cell renderer doesn't keep state; instead, any state
16 is set immediately prior to use through the object property system.
17 The cell is measured with "get_size", and then renderered with "ren‐
18 der".
19
21 Glib::Object
22 +----Glib::InitiallyUnowned
23 +----Gtk2::Object
24 +----Gtk2::CellRenderer
25
27 boolean = $cell->activate ($event, $widget, $path, $background_area,
28 $cell_area, $flags)
29 * $event (Gtk2::Gdk::Event)
31 * $widget (Gtk2::Widget)
32 * $path (string)
33 * $background_area (Gtk2::Gdk::Rectangle)
34 * $cell_area (Gtk2::Gdk::Rectangle)
35 * $flags (Gtk2::CellRendererState)
36 $cell->editing_canceled
38 (width, height) = $cell->get_fixed_size
40 Fetch the fixed size if $cell. Values of -1 mean "this dimension
42 is not fixed."
43 $cell->set_fixed_size ($width, $height)
45 * $width (integer)
47 * $height (integer)
48 Set the renderer's size explicitly, independent of object proper‐
50 ties. A value of -1 means "don't use a fixed size for this dimen‐
51 sion."
52 $cell->render ($drawable, $widget, $background_area, $cell_area,
54 $expose_area, $flags)
55 * $drawable (Gtk2::Gdk::Drawable)
57 * $widget (Gtk2::Widget)
58 * $background_area (Gtk2::Gdk::Rectangle)
59 * $cell_area (Gtk2::Gdk::Rectangle)
60 * $expose_area (Gtk2::Gdk::Rectangle)
61 * $flags (Gtk2::CellRendererState)
62 (x_offset, y_offset, width, height) = $cell->get_size ($widget,
64 $cell_area)
65 * $widget (Gtk2::Widget)
67 * $cell_area (Gtk2::Gdk::Rectangle or undef)
68 celleditable or undef = $cell->start_editing ($event, $widget, $path,
70 $background_area, $cell_area, $flags)
71 * $event (Gtk2::Gdk::Event)
73 * $widget (Gtk2::Widget)
74 * $path (string)
75 * $background_area (Gtk2::Gdk::Rectangle)
76 * $cell_area (Gtk2::Gdk::Rectangle)
77 * $flags (Gtk2::CellRendererState)
78 $cell->stop_editing ($canceled)
80 * $canceled (boolean)
82
84 'cell-background' (string : writable / private)
85 Cell background color as a string
86 'cell-background-gdk' (Gtk2::Gdk::Color : readable / writable / pri‐
88 vate)
89 Cell background color as a GdkColor
90 'cell-background-set' (boolean : readable / writable / private)
92 Whether this tag affects the cell background color
93 'height' (integer : readable / writable / private)
95 The fixed height
96 'is-expanded' (boolean : readable / writable / private)
98 Row is an expander row, and is expanded
99 'is-expander' (boolean : readable / writable / private)
101 Row has children
102 'mode' (Gtk2::CellRendererMode : readable / writable / private)
104 Editable mode of the CellRenderer
105 'sensitive' (boolean : readable / writable / private)
107 Display the cell sensitive
108 'visible' (boolean : readable / writable / private)
110 Display the cell
111 'width' (integer : readable / writable / private)
113 The fixed width
114 'xalign' (Glib::Float : readable / writable / private)
116 The x-align
117 'xpad' (Glib::UInt : readable / writable / private)
119 The xpad
120 'yalign' (Glib::Float : readable / writable / private)
122 The y-align
123 'ypad' (Glib::UInt : readable / writable / private)
125 The ypad
126
128 editing-canceled (Gtk2::CellRenderer)
129 editing-started (Gtk2::CellRenderer, Gtk2::CellEditable, string)
130
132 enum Gtk2::CellRendererMode
133 * 'inert' / 'GTK_CELL_RENDERER_MODE_INERT'
135 * 'activatable' / 'GTK_CELL_RENDERER_MODE_ACTIVATABLE'
136 * 'editable' / 'GTK_CELL_RENDERER_MODE_EDITABLE'
137 flags Gtk2::CellRendererState
139 * 'selected' / 'GTK_CELL_RENDERER_SELECTED'
141 * 'prelit' / 'GTK_CELL_RENDERER_PRELIT'
142 * 'insensitive' / 'GTK_CELL_RENDERER_INSENSITIVE'
143 * 'sorted' / 'GTK_CELL_RENDERER_SORTED'
144 * 'focused' / 'GTK_CELL_RENDERER_FOCUSED'
145
147 Gtk+ provides three cell renderers: Gtk2::CellRendererText, Gtk2::Cell‐
148 RendererToggle, and Gtk2::CellRendererPixbuf. You may derive a new
149 renderer from any of these, or directly from Gtk2::CellRenderer itself.
150 There are a number of rules that must be followed when writing a new
152 cell renderer. First and foremost, it's important that a certain set
153 of properties always yields a cell of the same size, barring a
154 Gtk2::Style change. The cell renderer also has a number of generic
155 properties that are expected to be honored by all children.
156 The new renderer must be a GObject, so you must follow the normal pro‐
158 cedure for creating a new Glib::Object (i.e., either Glib::Object::Sub‐
159 class or Glib::Type::register_object). The new subclass can customize
160 the object's behavior by providing new implementations of these four
161 methods:
162 (x_offset, y_offset, width, height) = GET_SIZE ($cell, $widget,
164 $cell_area)
165 o $cell (Gtk2::CellRenderer)
166 o $widget (Gtk2::Widget) widget to which $cell is rendering
167 o $cell_area (Gtk2::Gdk::Rectangle or undef) The area a cell will
168 be allocated, or undef.
169 Return Values:
171 - x_offset - x offset of cell relative to $cell_area
173 - y_offset - y offset of cell relative to $cell_area
174 - width - width needed to render cell
175 - height - height needed to render cell
176 This is called to calculate the size of the cell for display, tak‐
178 ing into account the padding and alignment properties of the par‐
179 ent. This one will be called very often. If you need to know your
180 cell's data, then get it from the appropriate object properties,
181 which will be set accordingly before this method is called.
182 RENDER ($cell, $drawable, $widget, $background_area, $cell_area,
184 $expose_area, $flags)
185 o $cell (Gtk2::CellRenderer)
186 o $drawable (Gtk2::Gdk::Drawable) window on which to draw
187 o $widget (Gtk2::Widget) widget owning $drawable
188 o $background_area (Gtk2::Gdk::Rectangle) entire cell area (includ‐
189 ing tree expanders and maybe padding on the sides)
190 o $cell_area (Gtk2::Gdk::Rectangle) area normally rendered by a
191 cell renderer
192 o $expose_area (Gtk2::Gdk::Rectangle) area that actually needs
193 updating
194 o $flags (Gtk2::CellRendererState) flags that affect rendering
195 This is called to render the cell onto the screen. As with
197 GET_SIZE, the data for the cell comes from object properties. In
198 general, you'll want to make use of Gtk2::Style methods for drawing
199 anything fancy.
200 The three passed-in rectangles are areas of $drawable. Most ren‐
202 derers draw within $cell_area; the xalign, yalign, xpad, and ypad
203 fields of the cell renderer should be honored with respect to
204 $cell_area. $background_area includes the blank space around the
205 cell, and also the area containing the tree expander; so the $back‐
206 ground_area rectangles for all cells cover the entire $drawable.
207 $expose_area is a clip rectangle.
208 boolean = ACTIVATE ($cell, $event, $widget, $path, $background_area,
210 $cell_area, $flags)
211 o $cell (Gtk2::CellRenderer)
212 o $event (Gtk2::Gdk::Event)
213 o $widget (Gtk2::Widget) widget that received the event
214 o $path (string) widget-dependent string representation of the
215 event location; e.g. for a Gtk2::TreeView, a string representation
216 of a Gtk2::TreePath.
217 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
218 to "RENDER".
219 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to "REN‐
220 DER".
221 o $flags (Gtk2::CellRendererState) render flags
222 This method is called when an event occurs on a cell. Implementing
224 it is not mandatory. The return value should be TRUE if the event
225 was consumed/handled.
226 celleditable or undef = START_EDITING ($cell, $event, $widget, $path,
228 $background_area, $cell_area, $flags)
229 o $cell (Gtk2::CellRenderer)
230 o $event (Gtk2::Gdk::Event)
231 o $widget (Gtk2::Widget) widget that received the event
232 o $path (string) widget-dependent string representation of the
233 event location; e.g. for a Gtk2::TreeView, a string representation
234 of a Gtk2::TreePath.
235 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
236 to "RENDER".
237 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to "REN‐
238 DER".
239 o $flags (Gtk2::CellRendererState) render flags
240 For cells that are editable, this is called to put the cell into
242 editing mode. If the return value is an object is a Gtk2::CellEd‐
243 itable, that widget will be used to edit the value; the calling
244 code takes care of sizing, placing, and showing the editable, you
245 just need to return it. If the return value is undef, the editing
246 is aborted.
247 Note: for backward compatibility, the bizarre and non-standard scheme
249 used for this in 1.02x is still supported, but is deprecated and should
250 not be used in new code, and since i don't want people to use it any
251 more i will not document it here.
252
254 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object
255
257 Copyright (C) 2003-2007 by the gtk2-perl team.
258 This software is licensed under the LGPL. See Gtk2 for a full notice.
260perl v5.8.8 2007-03-18 Gtk2::CellRenderer(3)