1Gtk2::CellRenderer(3) User Contributed Perl DocumentationGtk2::CellRenderer(3)
2
3
4

NAME

6       Gtk2::CellRenderer - An object that renders a single cell onto a
7       Gtk2::Gdk::Drawable
8

DESCRIPTION

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
14       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

HIERARCHY

21         Glib::Object
22         +----Glib::InitiallyUnowned
23              +----Gtk2::Object
24                   +----Gtk2::CellRenderer
25

METHODS

27   boolean = $cell->activate ($event, $widget, $path, $background_area,
28       $cell_area, $flags)
29       •   $event (Gtk2::Gdk::Event)
30
31       •   $widget (Gtk2::Widget)
32
33       •   $path (string)
34
35       •   $background_area (Gtk2::Gdk::Rectangle)
36
37       •   $cell_area (Gtk2::Gdk::Rectangle)
38
39       •   $flags (Gtk2::CellRendererState)
40
41   (xalign, yalign) = $cell->get_alignment
42       Since: gtk+ 2.18
43
44   $cell->set_alignment ($xalign, $yalign)
45       •   $xalign (double)
46
47       •   $yalign (double)
48
49       Since: gtk+ 2.18
50
51   $cell->editing_canceled
52       Since: gtk+ 2.4
53
54   (width, height) = $cell->get_fixed_size
55       Fetch the fixed size if $cell.  Values of -1 mean "this dimension is
56       not fixed."
57
58   $cell->set_fixed_size ($width, $height)
59       •   $width (integer)
60
61       •   $height (integer)
62
63       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
66   (xpad, ypad) = $cell->get_padding
67       Since: gtk+ 2.18
68
69   $cell->set_padding ($xpad, $ypad)
70       •   $xpad (integer)
71
72       •   $ypad (integer)
73
74       Since: gtk+ 2.18
75
76   $cell->render ($drawable, $widget, $background_area, $cell_area,
77       $expose_area, $flags)
78       •   $drawable (Gtk2::Gdk::Drawable)
79
80       •   $widget (Gtk2::Widget)
81
82       •   $background_area (Gtk2::Gdk::Rectangle)
83
84       •   $cell_area (Gtk2::Gdk::Rectangle)
85
86       •   $expose_area (Gtk2::Gdk::Rectangle)
87
88       •   $flags (Gtk2::CellRendererState)
89
90   boolean = $cell->get_sensitive
91       Since: gtk+ 2.18
92
93   $cell->set_sensitive ($sensitive)
94       •   $sensitive (boolean)
95
96       Since: gtk+ 2.18
97
98   (x_offset, y_offset, width, height) = $cell->get_size ($widget, $cell_area)
99       •   $widget (Gtk2::Widget)
100
101       •   $cell_area (Gtk2::Gdk::Rectangle or undef)
102
103   celleditable or undef = $cell->start_editing ($event, $widget, $path,
104       $background_area, $cell_area, $flags)
105       •   $event (Gtk2::Gdk::Event)
106
107       •   $widget (Gtk2::Widget)
108
109       •   $path (string)
110
111       •   $background_area (Gtk2::Gdk::Rectangle)
112
113       •   $cell_area (Gtk2::Gdk::Rectangle)
114
115       •   $flags (Gtk2::CellRendererState)
116
117   $cell->stop_editing ($canceled)
118       •   $canceled (boolean)
119
120       Since: gtk+ 2.6
121
122   boolean = $cell->get_visible
123       Since: gtk+ 2.18
124
125   $cell->set_visible ($visible)
126       •   $visible (boolean)
127
128       Since: gtk+ 2.18
129

PROPERTIES

131       'cell-background' (string : default undef : writable / private /
132       static-nick / static-blurb)
133           Cell background color as a string
134
135       'cell-background-gdk' (Gtk2::Gdk::Color : default undef : readable /
136       writable / private / static-nick / static-blurb)
137           Cell background color as a GdkColor
138
139       'cell-background-set' (boolean : default false : readable / writable /
140       private / static-nick / static-blurb)
141           Whether this tag affects the cell background color
142
143       'editing' (boolean : default false : readable / private / static-nick /
144       static-blurb)
145           Whether the cell renderer is currently in editing mode
146
147       'height' (integer : default -1 : readable / writable / private /
148       static-nick / static-blurb)
149           The fixed height
150
151       'is-expanded' (boolean : default false : readable / writable / private
152       / static-nick / static-blurb)
153           Row is an expander row, and is expanded
154
155       'is-expander' (boolean : default false : readable / writable / private
156       / static-nick / static-blurb)
157           Row has children
158
159       'mode' (Gtk2::CellRendererMode : default "inert" : readable / writable
160       / private / static-nick / static-blurb)
161           Editable mode of the CellRenderer
162
163       'sensitive' (boolean : default true : readable / writable / private /
164       static-nick / static-blurb)
165           Display the cell sensitive
166
167       'visible' (boolean : default true : readable / writable / private /
168       static-nick / static-blurb)
169           Display the cell
170
171       'width' (integer : default -1 : readable / writable / private / static-
172       nick / static-blurb)
173           The fixed width
174
175       'xalign' (float : default 0.5 : readable / writable / private / static-
176       nick / static-blurb)
177           The x-align
178
179       'xpad' (Glib::UInt : default 0 : readable / writable / private /
180       static-nick / static-blurb)
181           The xpad
182
183       'yalign' (float : default 0.5 : readable / writable / private / static-
184       nick / static-blurb)
185           The y-align
186
187       'ypad' (Glib::UInt : default 0 : readable / writable / private /
188       static-nick / static-blurb)
189           The ypad
190

SIGNALS

192       editing-canceled (Gtk2::CellRenderer)
193       editing-started (Gtk2::CellRenderer, Gtk2::CellEditable, string)
194

ENUMS AND FLAGS

196   enum Gtk2::CellRendererMode
197       •   'inert' / 'GTK_CELL_RENDERER_MODE_INERT'
198
199       •   'activatable' / 'GTK_CELL_RENDERER_MODE_ACTIVATABLE'
200
201       •   'editable' / 'GTK_CELL_RENDERER_MODE_EDITABLE'
202
203   flags Gtk2::CellRendererState
204       •   'selected' / 'GTK_CELL_RENDERER_SELECTED'
205
206       •   'prelit' / 'GTK_CELL_RENDERER_PRELIT'
207
208       •   'insensitive' / 'GTK_CELL_RENDERER_INSENSITIVE'
209
210       •   'sorted' / 'GTK_CELL_RENDERER_SORTED'
211
212       •   'focused' / 'GTK_CELL_RENDERER_FOCUSED'
213

DERIVING NEW CELL RENDERERS

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
220       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
226       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
232       (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
239           Return Values:
240
241           - 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
246           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
253       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
266           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
271           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
279       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
293           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
297       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
311           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
318       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

SEE ALSO

324       Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object
325
327       Copyright (C) 2003-2011 by the gtk2-perl team.
328
329       This software is licensed under the LGPL.  See Gtk2 for a full notice.
330
331
332
333perl v5.38.0                      2023-07-20             Gtk2::CellRenderer(3)
Impressum