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
12 Gtk2::TreeView, 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
18 "render".
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)
30 · $widget (Gtk2::Widget)
32 · $path (string)
34 · $background_area (Gtk2::Gdk::Rectangle)
36 · $cell_area (Gtk2::Gdk::Rectangle)
38 · $flags (Gtk2::CellRendererState)
40 (xalign, yalign) = $cell->get_alignment
42 Since: gtk+ 2.18
43 $cell->set_alignment ($xalign, $yalign)
45 · $xalign (double)
46 · $yalign (double)
48 Since: gtk+ 2.18
50 $cell->editing_canceled
52 Since: gtk+ 2.4
53 (width, height) = $cell->get_fixed_size
55 Fetch the fixed size if $cell. Values of -1 mean "this dimension is
56 not fixed."
57 $cell->set_fixed_size ($width, $height)
59 · $width (integer)
60 · $height (integer)
62 Set the renderer's size explicitly, independent of object properties.
64 A value of -1 means "don't use a fixed size for this dimension."
65 (xpad, ypad) = $cell->get_padding
67 Since: gtk+ 2.18
68 $cell->set_padding ($xpad, $ypad)
70 · $xpad (integer)
71 · $ypad (integer)
73 Since: gtk+ 2.18
75 $cell->render ($drawable, $widget, $background_area, $cell_area,
77 $expose_area, $flags)
78 · $drawable (Gtk2::Gdk::Drawable)
79 · $widget (Gtk2::Widget)
81 · $background_area (Gtk2::Gdk::Rectangle)
83 · $cell_area (Gtk2::Gdk::Rectangle)
85 · $expose_area (Gtk2::Gdk::Rectangle)
87 · $flags (Gtk2::CellRendererState)
89 boolean = $cell->get_sensitive
91 Since: gtk+ 2.18
92 $cell->set_sensitive ($sensitive)
94 · $sensitive (boolean)
95 Since: gtk+ 2.18
97 (x_offset, y_offset, width, height) = $cell->get_size ($widget, $cell_area)
99 · $widget (Gtk2::Widget)
100 · $cell_area (Gtk2::Gdk::Rectangle or undef)
102 celleditable or undef = $cell->start_editing ($event, $widget, $path,
104 $background_area, $cell_area, $flags)
105 · $event (Gtk2::Gdk::Event)
106 · $widget (Gtk2::Widget)
108 · $path (string)
110 · $background_area (Gtk2::Gdk::Rectangle)
112 · $cell_area (Gtk2::Gdk::Rectangle)
114 · $flags (Gtk2::CellRendererState)
116 $cell->stop_editing ($canceled)
118 · $canceled (boolean)
119 Since: gtk+ 2.6
121 boolean = $cell->get_visible
123 Since: gtk+ 2.18
124 $cell->set_visible ($visible)
126 · $visible (boolean)
127 Since: gtk+ 2.18
129
131 'cell-background' (string : default undef : writable / private /
132 static-nick / static-blurb)
133 Cell background color as a string
134 'cell-background-gdk' (Gtk2::Gdk::Color : default undef : readable /
136 writable / private / static-nick / static-blurb)
137 Cell background color as a GdkColor
138 'cell-background-set' (boolean : default false : readable / writable /
140 private / static-nick / static-blurb)
141 Whether this tag affects the cell background color
142 'editing' (boolean : default false : readable / private / static-nick /
144 static-blurb)
145 Whether the cell renderer is currently in editing mode
146 'height' (integer : default -1 : readable / writable / private /
148 static-nick / static-blurb)
149 The fixed height
150 'is-expanded' (boolean : default false : readable / writable / private
152 / static-nick / static-blurb)
153 Row is an expander row, and is expanded
154 'is-expander' (boolean : default false : readable / writable / private
156 / static-nick / static-blurb)
157 Row has children
158 'mode' (Gtk2::CellRendererMode : default "inert" : readable / writable
160 / private / static-nick / static-blurb)
161 Editable mode of the CellRenderer
162 'sensitive' (boolean : default true : readable / writable / private /
164 static-nick / static-blurb)
165 Display the cell sensitive
166 'visible' (boolean : default true : readable / writable / private /
168 static-nick / static-blurb)
169 Display the cell
170 'width' (integer : default -1 : readable / writable / private / static-
172 nick / static-blurb)
173 The fixed width
174 'xalign' (float : default 0.5 : readable / writable / private / static-
176 nick / static-blurb)
177 The x-align
178 'xpad' (Glib::UInt : default 0 : readable / writable / private /
180 static-nick / static-blurb)
181 The xpad
182 'yalign' (float : default 0.5 : readable / writable / private / static-
184 nick / static-blurb)
185 The y-align
186 'ypad' (Glib::UInt : default 0 : readable / writable / private /
188 static-nick / static-blurb)
189 The ypad
190
192 editing-canceled (Gtk2::CellRenderer)
193 editing-started (Gtk2::CellRenderer, Gtk2::CellEditable, string)
194
196 enum Gtk2::CellRendererMode
197 · 'inert' / 'GTK_CELL_RENDERER_MODE_INERT'
198 · 'activatable' / 'GTK_CELL_RENDERER_MODE_ACTIVATABLE'
200 · 'editable' / 'GTK_CELL_RENDERER_MODE_EDITABLE'
202 flags Gtk2::CellRendererState
204 · 'selected' / 'GTK_CELL_RENDERER_SELECTED'
205 · 'prelit' / 'GTK_CELL_RENDERER_PRELIT'
207 · 'insensitive' / 'GTK_CELL_RENDERER_INSENSITIVE'
209 · 'sorted' / 'GTK_CELL_RENDERER_SORTED'
211 · 'focused' / 'GTK_CELL_RENDERER_FOCUSED'
213
215 Gtk+ provides three cell renderers: Gtk2::CellRendererText,
216 Gtk2::CellRendererToggle, and Gtk2::CellRendererPixbuf. You may derive
217 a new renderer from any of these, or directly from Gtk2::CellRenderer
218 itself.
219 There are a number of rules that must be followed when writing a new
221 cell renderer. First and foremost, it's important that a certain set
222 of properties always yields a cell of the same size, barring a
223 Gtk2::Style change. The cell renderer also has a number of generic
224 properties that are expected to be honored by all children.
225 The new renderer must be a GObject, so you must follow the normal
227 procedure for creating a new Glib::Object (i.e., either
228 Glib::Object::Subclass or Glib::Type::register_object). The new
229 subclass can customize the object's behavior by providing new
230 implementations of these four methods:
231 (x_offset, y_offset, width, height) = GET_SIZE ($cell, $widget,
233 $cell_area)
234 o $cell (Gtk2::CellRenderer)
235 o $widget (Gtk2::Widget) widget to which $cell is rendering
236 o $cell_area (Gtk2::Gdk::Rectangle or undef) The area a cell will
237 be allocated, or undef.
238 Return Values:
240 - x_offset - x offset of cell relative to $cell_area
242 - y_offset - y offset of cell relative to $cell_area
243 - width - width needed to render cell
244 - height - height needed to render cell
245 This is called to calculate the size of the cell for display,
247 taking into account the padding and alignment properties of the
248 parent. This one will be called very often. If you need to know
249 your cell's data, then get it from the appropriate object
250 properties, which will be set accordingly before this method is
251 called.
252 RENDER ($cell, $drawable, $widget, $background_area, $cell_area,
254 $expose_area, $flags)
255 o $cell (Gtk2::CellRenderer)
256 o $drawable (Gtk2::Gdk::Drawable) window on which to draw
257 o $widget (Gtk2::Widget) widget owning $drawable
258 o $background_area (Gtk2::Gdk::Rectangle) entire cell area
259 (including tree expanders and maybe padding on the sides)
260 o $cell_area (Gtk2::Gdk::Rectangle) area normally rendered by a
261 cell renderer
262 o $expose_area (Gtk2::Gdk::Rectangle) area that actually needs
263 updating
264 o $flags (Gtk2::CellRendererState) flags that affect rendering
265 This is called to render the cell onto the screen. As with
267 GET_SIZE, the data for the cell comes from object properties. In
268 general, you'll want to make use of Gtk2::Style methods for drawing
269 anything fancy.
270 The three passed-in rectangles are areas of $drawable. Most
272 renderers draw within $cell_area; the xalign, yalign, xpad, and
273 ypad fields of the cell renderer should be honored with respect to
274 $cell_area. $background_area includes the blank space around the
275 cell, and also the area containing the tree expander; so the
276 $background_area rectangles for all cells cover the entire
277 $drawable. $expose_area is a clip rectangle.
278 boolean = ACTIVATE ($cell, $event, $widget, $path, $background_area,
280 $cell_area, $flags)
281 o $cell (Gtk2::CellRenderer)
282 o $event (Gtk2::Gdk::Event)
283 o $widget (Gtk2::Widget) widget that received the event
284 o $path (string) widget-dependent string representation of the
285 event location; e.g. for a Gtk2::TreeView, a string representation
286 of a Gtk2::TreePath.
287 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
288 to "RENDER".
289 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to
290 "RENDER".
291 o $flags (Gtk2::CellRendererState) render flags
292 This method is called when an event occurs on a cell. Implementing
294 it is not mandatory. The return value should be TRUE if the event
295 was consumed/handled.
296 celleditable or undef = START_EDITING ($cell, $event, $widget, $path,
298 $background_area, $cell_area, $flags)
299 o $cell (Gtk2::CellRenderer)
300 o $event (Gtk2::Gdk::Event)
301 o $widget (Gtk2::Widget) widget that received the event
302 o $path (string) widget-dependent string representation of the
303 event location; e.g. for a Gtk2::TreeView, a string representation
304 of a Gtk2::TreePath.
305 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
306 to "RENDER".
307 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to
308 "RENDER".
309 o $flags (Gtk2::CellRendererState) render flags
310 For cells that are editable, this is called to put the cell into
312 editing mode. If the return value is an object is a
313 Gtk2::CellEditable, that widget will be used to edit the value; the
314 calling code takes care of sizing, placing, and showing the
315 editable, you just need to return it. If the return value is
316 undef, the editing is aborted.
317 Note: for backward compatibility, the bizarre and non-standard scheme
319 used for this in 1.02x is still supported, but is deprecated and should
320 not be used in new code, and since i don't want people to use it any
321 more i will not document it here.
322
324 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object
325
327 Copyright (C) 2003-2011 by the gtk2-perl team.
328 This software is licensed under the LGPL. See Gtk2 for a full notice.
330perl v5.32.0 2020-07-28 Gtk2::CellRenderer(3)