1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gtk.CellRenderer;
26 
27 private import gdk.Event;
28 private import glib.MemorySlice;
29 private import glib.Str;
30 private import gobject.ObjectG;
31 private import gobject.Signals;
32 private import gtk.CellEditableIF;
33 private import gtk.Requisition;
34 private import gtk.Snapshot;
35 private import gtk.Widget;
36 private import gtk.c.functions;
37 public  import gtk.c.types;
38 private import std.algorithm;
39 
40 
41 /**
42  * An object for rendering a single cell
43  * 
44  * The #GtkCellRenderer is a base class of a set of objects used for
45  * rendering a cell to a #cairo_t.  These objects are used primarily by
46  * the #GtkTreeView widget, though they aren’t tied to them in any
47  * specific way.  It is worth noting that #GtkCellRenderer is not a
48  * #GtkWidget and cannot be treated as such.
49  * 
50  * The primary use of a #GtkCellRenderer is for drawing a certain graphical
51  * elements on a #cairo_t. Typically, one cell renderer is used to
52  * draw many cells on the screen.  To this extent, it isn’t expected that a
53  * CellRenderer keep any permanent state around.  Instead, any state is set
54  * just prior to use using #GObjects property system.  Then, the
55  * cell is measured using gtk_cell_renderer_get_preferred_size(). Finally, the cell
56  * is rendered in the correct location using gtk_cell_renderer_snapshot().
57  * 
58  * There are a number of rules that must be followed when writing a new
59  * #GtkCellRenderer.  First and foremost, it’s important that a certain set
60  * of properties will always yield a cell renderer of the same size,
61  * barring a style change. The #GtkCellRenderer also has a number of
62  * generic properties that are expected to be honored by all children.
63  * 
64  * Beyond merely rendering a cell, cell renderers can optionally
65  * provide active user interface elements. A cell renderer can be
66  * “activatable” like #GtkCellRendererToggle,
67  * which toggles when it gets activated by a mouse click, or it can be
68  * “editable” like #GtkCellRendererText, which
69  * allows the user to edit the text using a widget implementing the
70  * #GtkCellEditable interface, e.g. #GtkEntry.
71  * To make a cell renderer activatable or editable, you have to
72  * implement the #GtkCellRendererClass.activate or
73  * #GtkCellRendererClass.start_editing virtual functions, respectively.
74  * 
75  * Many properties of #GtkCellRenderer and its subclasses have a
76  * corresponding “set” property, e.g. “cell-background-set” corresponds
77  * to “cell-background”. These “set” properties reflect whether a property
78  * has been set or not. You should not set them independently.
79  */
80 public class CellRenderer : ObjectG
81 {
82 	/** the main Gtk struct */
83 	protected GtkCellRenderer* gtkCellRenderer;
84 
85 	/** Get the main Gtk struct */
86 	public GtkCellRenderer* getCellRendererStruct(bool transferOwnership = false)
87 	{
88 		if (transferOwnership)
89 			ownedRef = false;
90 		return gtkCellRenderer;
91 	}
92 
93 	/** the main Gtk struct as a void* */
94 	protected override void* getStruct()
95 	{
96 		return cast(void*)gtkCellRenderer;
97 	}
98 
99 	/**
100 	 * Sets our main struct and passes it to the parent class.
101 	 */
102 	public this (GtkCellRenderer* gtkCellRenderer, bool ownedRef = false)
103 	{
104 		this.gtkCellRenderer = gtkCellRenderer;
105 		super(cast(GObject*)gtkCellRenderer, ownedRef);
106 	}
107 
108 
109 	/** */
110 	public static GType getType()
111 	{
112 		return gtk_cell_renderer_get_type();
113 	}
114 
115 	/**
116 	 * Passes an activate event to the cell renderer for possible processing.
117 	 * Some cell renderers may use events; for example, #GtkCellRendererToggle
118 	 * toggles when it gets a mouse click.
119 	 *
120 	 * Params:
121 	 *     event = a #GdkEvent
122 	 *     widget = widget that received the event
123 	 *     path = widget-dependent string representation of the event location;
124 	 *         e.g. for #GtkTreeView, a string representation of #GtkTreePath
125 	 *     backgroundArea = background area as passed to gtk_cell_renderer_render()
126 	 *     cellArea = cell area as passed to gtk_cell_renderer_render()
127 	 *     flags = render flags
128 	 *
129 	 * Returns: %TRUE if the event was consumed/handled
130 	 */
131 	public bool activate(Event event, Widget widget, string path, GdkRectangle* backgroundArea, GdkRectangle* cellArea, GtkCellRendererState flags)
132 	{
133 		return gtk_cell_renderer_activate(gtkCellRenderer, (event is null) ? null : event.getEventStruct(), (widget is null) ? null : widget.getWidgetStruct(), Str.toStringz(path), backgroundArea, cellArea, flags) != 0;
134 	}
135 
136 	/**
137 	 * Gets the aligned area used by @cell inside @cell_area. Used for finding
138 	 * the appropriate edit and focus rectangle.
139 	 *
140 	 * Params:
141 	 *     widget = the #GtkWidget this cell will be rendering to
142 	 *     flags = render flags
143 	 *     cellArea = cell area which would be passed to gtk_cell_renderer_render()
144 	 *     alignedArea = the return location for the space inside @cell_area
145 	 *         that would actually be used to render.
146 	 */
147 	public void getAlignedArea(Widget widget, GtkCellRendererState flags, GdkRectangle* cellArea, out GdkRectangle alignedArea)
148 	{
149 		gtk_cell_renderer_get_aligned_area(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), flags, cellArea, &alignedArea);
150 	}
151 
152 	/**
153 	 * Fills in @xalign and @yalign with the appropriate values of @cell.
154 	 *
155 	 * Params:
156 	 *     xalign = location to fill in with the x alignment of the cell, or %NULL
157 	 *     yalign = location to fill in with the y alignment of the cell, or %NULL
158 	 */
159 	public void getAlignment(out float xalign, out float yalign)
160 	{
161 		gtk_cell_renderer_get_alignment(gtkCellRenderer, &xalign, &yalign);
162 	}
163 
164 	/**
165 	 * Fills in @width and @height with the appropriate size of @cell.
166 	 *
167 	 * Params:
168 	 *     width = location to fill in with the fixed width of the cell, or %NULL
169 	 *     height = location to fill in with the fixed height of the cell, or %NULL
170 	 */
171 	public void getFixedSize(out int width, out int height)
172 	{
173 		gtk_cell_renderer_get_fixed_size(gtkCellRenderer, &width, &height);
174 	}
175 
176 	/**
177 	 * Checks whether the given #GtkCellRenderer is expanded.
178 	 *
179 	 * Returns: %TRUE if the cell renderer is expanded
180 	 */
181 	public bool getIsExpanded()
182 	{
183 		return gtk_cell_renderer_get_is_expanded(gtkCellRenderer) != 0;
184 	}
185 
186 	/**
187 	 * Checks whether the given #GtkCellRenderer is an expander.
188 	 *
189 	 * Returns: %TRUE if @cell is an expander, and %FALSE otherwise
190 	 */
191 	public bool getIsExpander()
192 	{
193 		return gtk_cell_renderer_get_is_expander(gtkCellRenderer) != 0;
194 	}
195 
196 	/**
197 	 * Fills in @xpad and @ypad with the appropriate values of @cell.
198 	 *
199 	 * Params:
200 	 *     xpad = location to fill in with the x padding of the cell, or %NULL
201 	 *     ypad = location to fill in with the y padding of the cell, or %NULL
202 	 */
203 	public void getPadding(out int xpad, out int ypad)
204 	{
205 		gtk_cell_renderer_get_padding(gtkCellRenderer, &xpad, &ypad);
206 	}
207 
208 	/**
209 	 * Retrieves a renderer’s natural size when rendered to @widget.
210 	 *
211 	 * Params:
212 	 *     widget = the #GtkWidget this cell will be rendering to
213 	 *     minimumSize = location to store the minimum size, or %NULL
214 	 *     naturalSize = location to store the natural size, or %NULL
215 	 */
216 	public void getPreferredHeight(Widget widget, out int minimumSize, out int naturalSize)
217 	{
218 		gtk_cell_renderer_get_preferred_height(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), &minimumSize, &naturalSize);
219 	}
220 
221 	/**
222 	 * Retrieves a cell renderers’s minimum and natural height if it were rendered to
223 	 * @widget with the specified @width.
224 	 *
225 	 * Params:
226 	 *     widget = the #GtkWidget this cell will be rendering to
227 	 *     width = the size which is available for allocation
228 	 *     minimumHeight = location for storing the minimum size, or %NULL
229 	 *     naturalHeight = location for storing the preferred size, or %NULL
230 	 */
231 	public void getPreferredHeightForWidth(Widget widget, int width, out int minimumHeight, out int naturalHeight)
232 	{
233 		gtk_cell_renderer_get_preferred_height_for_width(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), width, &minimumHeight, &naturalHeight);
234 	}
235 
236 	/**
237 	 * Retrieves the minimum and natural size of a cell taking
238 	 * into account the widget’s preference for height-for-width management.
239 	 *
240 	 * Params:
241 	 *     widget = the #GtkWidget this cell will be rendering to
242 	 *     minimumSize = location for storing the minimum size, or %NULL
243 	 *     naturalSize = location for storing the natural size, or %NULL
244 	 */
245 	public void getPreferredSize(Widget widget, out Requisition minimumSize, out Requisition naturalSize)
246 	{
247 		GtkRequisition* outminimumSize = sliceNew!GtkRequisition();
248 		GtkRequisition* outnaturalSize = sliceNew!GtkRequisition();
249 
250 		gtk_cell_renderer_get_preferred_size(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), outminimumSize, outnaturalSize);
251 
252 		minimumSize = ObjectG.getDObject!(Requisition)(outminimumSize, true);
253 		naturalSize = ObjectG.getDObject!(Requisition)(outnaturalSize, true);
254 	}
255 
256 	/**
257 	 * Retrieves a renderer’s natural size when rendered to @widget.
258 	 *
259 	 * Params:
260 	 *     widget = the #GtkWidget this cell will be rendering to
261 	 *     minimumSize = location to store the minimum size, or %NULL
262 	 *     naturalSize = location to store the natural size, or %NULL
263 	 */
264 	public void getPreferredWidth(Widget widget, out int minimumSize, out int naturalSize)
265 	{
266 		gtk_cell_renderer_get_preferred_width(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), &minimumSize, &naturalSize);
267 	}
268 
269 	/**
270 	 * Retrieves a cell renderers’s minimum and natural width if it were rendered to
271 	 * @widget with the specified @height.
272 	 *
273 	 * Params:
274 	 *     widget = the #GtkWidget this cell will be rendering to
275 	 *     height = the size which is available for allocation
276 	 *     minimumWidth = location for storing the minimum size, or %NULL
277 	 *     naturalWidth = location for storing the preferred size, or %NULL
278 	 */
279 	public void getPreferredWidthForHeight(Widget widget, int height, out int minimumWidth, out int naturalWidth)
280 	{
281 		gtk_cell_renderer_get_preferred_width_for_height(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), height, &minimumWidth, &naturalWidth);
282 	}
283 
284 	/**
285 	 * Gets whether the cell renderer prefers a height-for-width layout
286 	 * or a width-for-height layout.
287 	 *
288 	 * Returns: The #GtkSizeRequestMode preferred by this renderer.
289 	 */
290 	public GtkSizeRequestMode getRequestMode()
291 	{
292 		return gtk_cell_renderer_get_request_mode(gtkCellRenderer);
293 	}
294 
295 	/**
296 	 * Returns the cell renderer’s sensitivity.
297 	 *
298 	 * Returns: %TRUE if the cell renderer is sensitive
299 	 */
300 	public bool getSensitive()
301 	{
302 		return gtk_cell_renderer_get_sensitive(gtkCellRenderer) != 0;
303 	}
304 
305 	/**
306 	 * Translates the cell renderer state to #GtkStateFlags,
307 	 * based on the cell renderer and widget sensitivity, and
308 	 * the given #GtkCellRendererState.
309 	 *
310 	 * Params:
311 	 *     widget = a #GtkWidget, or %NULL
312 	 *     cellState = cell renderer state
313 	 *
314 	 * Returns: the widget state flags applying to @cell
315 	 */
316 	public GtkStateFlags getState(Widget widget, GtkCellRendererState cellState)
317 	{
318 		return gtk_cell_renderer_get_state(gtkCellRenderer, (widget is null) ? null : widget.getWidgetStruct(), cellState);
319 	}
320 
321 	/**
322 	 * Returns the cell renderer’s visibility.
323 	 *
324 	 * Returns: %TRUE if the cell renderer is visible
325 	 */
326 	public bool getVisible()
327 	{
328 		return gtk_cell_renderer_get_visible(gtkCellRenderer) != 0;
329 	}
330 
331 	/**
332 	 * Checks whether the cell renderer can do something when activated.
333 	 *
334 	 * Returns: %TRUE if the cell renderer can do anything when activated
335 	 */
336 	public bool isActivatable()
337 	{
338 		return gtk_cell_renderer_is_activatable(gtkCellRenderer) != 0;
339 	}
340 
341 	/**
342 	 * Sets the renderer’s alignment within its available space.
343 	 *
344 	 * Params:
345 	 *     xalign = the x alignment of the cell renderer
346 	 *     yalign = the y alignment of the cell renderer
347 	 */
348 	public void setAlignment(float xalign, float yalign)
349 	{
350 		gtk_cell_renderer_set_alignment(gtkCellRenderer, xalign, yalign);
351 	}
352 
353 	/**
354 	 * Sets the renderer size to be explicit, independent of the properties set.
355 	 *
356 	 * Params:
357 	 *     width = the width of the cell renderer, or -1
358 	 *     height = the height of the cell renderer, or -1
359 	 */
360 	public void setFixedSize(int width, int height)
361 	{
362 		gtk_cell_renderer_set_fixed_size(gtkCellRenderer, width, height);
363 	}
364 
365 	/**
366 	 * Sets whether the given #GtkCellRenderer is expanded.
367 	 *
368 	 * Params:
369 	 *     isExpanded = whether @cell should be expanded
370 	 */
371 	public void setIsExpanded(bool isExpanded)
372 	{
373 		gtk_cell_renderer_set_is_expanded(gtkCellRenderer, isExpanded);
374 	}
375 
376 	/**
377 	 * Sets whether the given #GtkCellRenderer is an expander.
378 	 *
379 	 * Params:
380 	 *     isExpander = whether @cell is an expander
381 	 */
382 	public void setIsExpander(bool isExpander)
383 	{
384 		gtk_cell_renderer_set_is_expander(gtkCellRenderer, isExpander);
385 	}
386 
387 	/**
388 	 * Sets the renderer’s padding.
389 	 *
390 	 * Params:
391 	 *     xpad = the x padding of the cell renderer
392 	 *     ypad = the y padding of the cell renderer
393 	 */
394 	public void setPadding(int xpad, int ypad)
395 	{
396 		gtk_cell_renderer_set_padding(gtkCellRenderer, xpad, ypad);
397 	}
398 
399 	/**
400 	 * Sets the cell renderer’s sensitivity.
401 	 *
402 	 * Params:
403 	 *     sensitive = the sensitivity of the cell
404 	 */
405 	public void setSensitive(bool sensitive)
406 	{
407 		gtk_cell_renderer_set_sensitive(gtkCellRenderer, sensitive);
408 	}
409 
410 	/**
411 	 * Sets the cell renderer’s visibility.
412 	 *
413 	 * Params:
414 	 *     visible = the visibility of the cell
415 	 */
416 	public void setVisible(bool visible)
417 	{
418 		gtk_cell_renderer_set_visible(gtkCellRenderer, visible);
419 	}
420 
421 	/**
422 	 * Invokes the virtual render function of the #GtkCellRenderer. The three
423 	 * passed-in rectangles are areas in @cr. Most renderers will draw within
424 	 * @cell_area; the xalign, yalign, xpad, and ypad fields of the #GtkCellRenderer
425 	 * should be honored with respect to @cell_area. @background_area includes the
426 	 * blank space around the cell, and also the area containing the tree expander;
427 	 * so the @background_area rectangles for all cells tile to cover the entire
428 	 * @window.
429 	 *
430 	 * Params:
431 	 *     snapshot = a #GtkSnapshot to draw to
432 	 *     widget = the widget owning @window
433 	 *     backgroundArea = entire cell area (including tree expanders and maybe
434 	 *         padding on the sides)
435 	 *     cellArea = area normally rendered by a cell renderer
436 	 *     flags = flags that affect rendering
437 	 */
438 	public void snapshot(Snapshot snapshot, Widget widget, GdkRectangle* backgroundArea, GdkRectangle* cellArea, GtkCellRendererState flags)
439 	{
440 		gtk_cell_renderer_snapshot(gtkCellRenderer, (snapshot is null) ? null : snapshot.getGtkSnapshotStruct(), (widget is null) ? null : widget.getWidgetStruct(), backgroundArea, cellArea, flags);
441 	}
442 
443 	/**
444 	 * Starts editing the contents of this @cell, through a new #GtkCellEditable
445 	 * widget created by the #GtkCellRendererClass.start_editing virtual function.
446 	 *
447 	 * Params:
448 	 *     event = a #GdkEvent
449 	 *     widget = widget that received the event
450 	 *     path = widget-dependent string representation of the event location;
451 	 *         e.g. for #GtkTreeView, a string representation of #GtkTreePath
452 	 *     backgroundArea = background area as passed to gtk_cell_renderer_render()
453 	 *     cellArea = cell area as passed to gtk_cell_renderer_render()
454 	 *     flags = render flags
455 	 *
456 	 * Returns: A new #GtkCellEditable for editing this
457 	 *     @cell, or %NULL if editing is not possible
458 	 */
459 	public CellEditableIF startEditing(Event event, Widget widget, string path, GdkRectangle* backgroundArea, GdkRectangle* cellArea, GtkCellRendererState flags)
460 	{
461 		auto __p = gtk_cell_renderer_start_editing(gtkCellRenderer, (event is null) ? null : event.getEventStruct(), (widget is null) ? null : widget.getWidgetStruct(), Str.toStringz(path), backgroundArea, cellArea, flags);
462 
463 		if(__p is null)
464 		{
465 			return null;
466 		}
467 
468 		return ObjectG.getDObject!(CellEditableIF)(cast(GtkCellEditable*) __p);
469 	}
470 
471 	/**
472 	 * Informs the cell renderer that the editing is stopped.
473 	 * If @canceled is %TRUE, the cell renderer will emit the
474 	 * #GtkCellRenderer::editing-canceled signal.
475 	 *
476 	 * This function should be called by cell renderer implementations
477 	 * in response to the #GtkCellEditable::editing-done signal of
478 	 * #GtkCellEditable.
479 	 *
480 	 * Params:
481 	 *     canceled = %TRUE if the editing has been canceled
482 	 */
483 	public void stopEditing(bool canceled)
484 	{
485 		gtk_cell_renderer_stop_editing(gtkCellRenderer, canceled);
486 	}
487 
488 	/**
489 	 * This signal gets emitted when the user cancels the process of editing a
490 	 * cell.  For example, an editable cell renderer could be written to cancel
491 	 * editing when the user presses Escape.
492 	 *
493 	 * See also: gtk_cell_renderer_stop_editing().
494 	 */
495 	gulong addOnEditingCanceled(void delegate(CellRenderer) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
496 	{
497 		return Signals.connect(this, "editing-canceled", dlg, connectFlags ^ ConnectFlags.SWAPPED);
498 	}
499 
500 	/**
501 	 * This signal gets emitted when a cell starts to be edited.
502 	 * The intended use of this signal is to do special setup
503 	 * on @editable, e.g. adding a #GtkEntryCompletion or setting
504 	 * up additional columns in a #GtkComboBox.
505 	 *
506 	 * See gtk_cell_editable_start_editing() for information on the lifecycle of
507 	 * the @editable and a way to do setup that doesn’t depend on the @renderer.
508 	 *
509 	 * Note that GTK doesn't guarantee that cell renderers will
510 	 * continue to use the same kind of widget for editing in future
511 	 * releases, therefore you should check the type of @editable
512 	 * before doing any specific setup, as in the following example:
513 	 * |[<!-- language="C" -->
514 	 * static void
515 	 * text_editing_started (GtkCellRenderer *cell,
516 	 * GtkCellEditable *editable,
517 	 * const char      *path,
518 	 * gpointer         data)
519 	 * {
520 	 * if (GTK_IS_ENTRY (editable))
521 	 * {
522 	 * GtkEntry *entry = GTK_ENTRY (editable);
523 	 *
524 	 * // ... create a GtkEntryCompletion
525 	 *
526 	 * gtk_entry_set_completion (entry, completion);
527 	 * }
528 	 * }
529 	 * ]|
530 	 *
531 	 * Params:
532 	 *     editable = the #GtkCellEditable
533 	 *     path = the path identifying the edited cell
534 	 */
535 	gulong addOnEditingStarted(void delegate(CellEditableIF, string, CellRenderer) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
536 	{
537 		return Signals.connect(this, "editing-started", dlg, connectFlags ^ ConnectFlags.SWAPPED);
538 	}
539 }