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 $cell->editing_canceled
42 Since: gtk+ 2.4
43 (width, height) = $cell->get_fixed_size
45 Fetch the fixed size if $cell. Values of -1 mean "this dimension
46 is not fixed."
47 $cell->set_fixed_size ($width, $height)
49 · $width (integer)
50 · $height (integer)
52 Set the renderer's size explicitly, independent of object
54 properties. A value of -1 means "don't use a fixed size for this
55 dimension."
56 $cell->render ($drawable, $widget, $background_area, $cell_area,
58 $expose_area, $flags)
59 · $drawable (Gtk2::Gdk::Drawable)
60 · $widget (Gtk2::Widget)
62 · $background_area (Gtk2::Gdk::Rectangle)
64 · $cell_area (Gtk2::Gdk::Rectangle)
66 · $expose_area (Gtk2::Gdk::Rectangle)
68 · $flags (Gtk2::CellRendererState)
70 (x_offset, y_offset, width, height) = $cell->get_size ($widget, $cell_area)
72 · $widget (Gtk2::Widget)
73 · $cell_area (Gtk2::Gdk::Rectangle or undef)
75 celleditable or undef = $cell->start_editing ($event, $widget, $path,
77 $background_area, $cell_area, $flags)
78 · $event (Gtk2::Gdk::Event)
79 · $widget (Gtk2::Widget)
81 · $path (string)
83 · $background_area (Gtk2::Gdk::Rectangle)
85 · $cell_area (Gtk2::Gdk::Rectangle)
87 · $flags (Gtk2::CellRendererState)
89 $cell->stop_editing ($canceled)
91 · $canceled (boolean)
92 Since: gtk+ 2.6
94
96 'cell-background' (string : writable / private)
97 Cell background color as a string
98 'cell-background-gdk' (Gtk2::Gdk::Color : readable / writable /
100 private)
101 Cell background color as a GdkColor
102 'cell-background-set' (boolean : readable / writable / private)
104 Whether this tag affects the cell background color
105 'editing' (boolean : readable / private)
107 Whether the cell renderer is currently in editing mode
108 'height' (integer : readable / writable / private)
110 The fixed height
111 'is-expanded' (boolean : readable / writable / private)
113 Row is an expander row, and is expanded
114 'is-expander' (boolean : readable / writable / private)
116 Row has children
117 'mode' (Gtk2::CellRendererMode : readable / writable / private)
119 Editable mode of the CellRenderer
120 'sensitive' (boolean : readable / writable / private)
122 Display the cell sensitive
123 'visible' (boolean : readable / writable / private)
125 Display the cell
126 'width' (integer : readable / writable / private)
128 The fixed width
129 'xalign' (Glib::Float : readable / writable / private)
131 The x-align
132 'xpad' (Glib::UInt : readable / writable / private)
134 The xpad
135 'yalign' (Glib::Float : readable / writable / private)
137 The y-align
138 'ypad' (Glib::UInt : readable / writable / private)
140 The ypad
141
143 editing-canceled (Gtk2::CellRenderer)
144 editing-started (Gtk2::CellRenderer, Gtk2::CellEditable, string)
145
147 enum Gtk2::CellRendererMode
148 · 'inert' / 'GTK_CELL_RENDERER_MODE_INERT'
149 · 'activatable' / 'GTK_CELL_RENDERER_MODE_ACTIVATABLE'
151 · 'editable' / 'GTK_CELL_RENDERER_MODE_EDITABLE'
153 flags Gtk2::CellRendererState
155 · 'selected' / 'GTK_CELL_RENDERER_SELECTED'
156 · 'prelit' / 'GTK_CELL_RENDERER_PRELIT'
158 · 'insensitive' / 'GTK_CELL_RENDERER_INSENSITIVE'
160 · 'sorted' / 'GTK_CELL_RENDERER_SORTED'
162 · 'focused' / 'GTK_CELL_RENDERER_FOCUSED'
164
166 Gtk+ provides three cell renderers: Gtk2::CellRendererText,
167 Gtk2::CellRendererToggle, and Gtk2::CellRendererPixbuf. You may derive
168 a new renderer from any of these, or directly from Gtk2::CellRenderer
169 itself.
170 There are a number of rules that must be followed when writing a new
172 cell renderer. First and foremost, it's important that a certain set
173 of properties always yields a cell of the same size, barring a
174 Gtk2::Style change. The cell renderer also has a number of generic
175 properties that are expected to be honored by all children.
176 The new renderer must be a GObject, so you must follow the normal
178 procedure for creating a new Glib::Object (i.e., either
179 Glib::Object::Subclass or Glib::Type::register_object). The new
180 subclass can customize the object's behavior by providing new
181 implementations of these four methods:
182 (x_offset, y_offset, width, height) = GET_SIZE ($cell, $widget,
184 $cell_area)
185 o $cell (Gtk2::CellRenderer)
186 o $widget (Gtk2::Widget) widget to which $cell is rendering
187 o $cell_area (Gtk2::Gdk::Rectangle or undef) The area a cell will
188 be allocated, or undef.
189 Return Values:
191 - x_offset - x offset of cell relative to $cell_area
193 - y_offset - y offset of cell relative to $cell_area
194 - width - width needed to render cell
195 - height - height needed to render cell
196 This is called to calculate the size of the cell for display,
198 taking into account the padding and alignment properties of the
199 parent. This one will be called very often. If you need to know
200 your cell's data, then get it from the appropriate object
201 properties, which will be set accordingly before this method is
202 called.
203 RENDER ($cell, $drawable, $widget, $background_area, $cell_area,
205 $expose_area, $flags)
206 o $cell (Gtk2::CellRenderer)
207 o $drawable (Gtk2::Gdk::Drawable) window on which to draw
208 o $widget (Gtk2::Widget) widget owning $drawable
209 o $background_area (Gtk2::Gdk::Rectangle) entire cell area
210 (including tree expanders and maybe padding on the sides)
211 o $cell_area (Gtk2::Gdk::Rectangle) area normally rendered by a
212 cell renderer
213 o $expose_area (Gtk2::Gdk::Rectangle) area that actually needs
214 updating
215 o $flags (Gtk2::CellRendererState) flags that affect rendering
216 This is called to render the cell onto the screen. As with
218 GET_SIZE, the data for the cell comes from object properties. In
219 general, you'll want to make use of Gtk2::Style methods for drawing
220 anything fancy.
221 The three passed-in rectangles are areas of $drawable. Most
223 renderers draw within $cell_area; the xalign, yalign, xpad, and
224 ypad fields of the cell renderer should be honored with respect to
225 $cell_area. $background_area includes the blank space around the
226 cell, and also the area containing the tree expander; so the
227 $background_area rectangles for all cells cover the entire
228 $drawable. $expose_area is a clip rectangle.
229 boolean = ACTIVATE ($cell, $event, $widget, $path, $background_area,
231 $cell_area, $flags)
232 o $cell (Gtk2::CellRenderer)
233 o $event (Gtk2::Gdk::Event)
234 o $widget (Gtk2::Widget) widget that received the event
235 o $path (string) widget-dependent string representation of the
236 event location; e.g. for a Gtk2::TreeView, a string representation
237 of a Gtk2::TreePath.
238 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
239 to "RENDER".
240 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to
241 "RENDER".
242 o $flags (Gtk2::CellRendererState) render flags
243 This method is called when an event occurs on a cell. Implementing
245 it is not mandatory. The return value should be TRUE if the event
246 was consumed/handled.
247 celleditable or undef = START_EDITING ($cell, $event, $widget, $path,
249 $background_area, $cell_area, $flags)
250 o $cell (Gtk2::CellRenderer)
251 o $event (Gtk2::Gdk::Event)
252 o $widget (Gtk2::Widget) widget that received the event
253 o $path (string) widget-dependent string representation of the
254 event location; e.g. for a Gtk2::TreeView, a string representation
255 of a Gtk2::TreePath.
256 o $background_area (Gtk2::Gdk::Rectangle) background area as passed
257 to "RENDER".
258 o $cell_area (Gtk2::Gdk::Rectangle) cell area as passed to
259 "RENDER".
260 o $flags (Gtk2::CellRendererState) render flags
261 For cells that are editable, this is called to put the cell into
263 editing mode. If the return value is an object is a
264 Gtk2::CellEditable, that widget will be used to edit the value; the
265 calling code takes care of sizing, placing, and showing the
266 editable, you just need to return it. If the return value is
267 undef, the editing is aborted.
268 Note: for backward compatibility, the bizarre and non-standard scheme
270 used for this in 1.02x is still supported, but is deprecated and should
271 not be used in new code, and since i don't want people to use it any
272 more i will not document it here.
273
275 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object
276
278 Copyright (C) 2003-2008 by the gtk2-perl team.
279 This software is licensed under the LGPL. See Gtk2 for a full notice.
281perl v5.12.0 2010-05-02 Gtk2::CellRenderer(3)