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.Popover;
26 
27 private import gio.MenuModel;
28 private import glib.ConstructionException;
29 private import glib.Str;
30 private import gobject.ObjectG;
31 private import gobject.Signals;
32 private import gtk.Bin;
33 private import gtk.Widget;
34 public  import gtkc.gdktypes;
35 private import gtkc.gtk;
36 public  import gtkc.gtktypes;
37 
38 
39 /**
40  * GtkPopover is a bubble-like context window, primarily meant to
41  * provide context-dependent information or options. Popovers are
42  * attached to a widget, passed at construction time on gtk_popover_new(),
43  * or updated afterwards through gtk_popover_set_relative_to(), by
44  * default they will point to the whole widget area, although this
45  * behavior can be changed through gtk_popover_set_pointing_to().
46  * 
47  * The position of a popover relative to the widget it is attached to
48  * can also be changed through gtk_popover_set_position().
49  * 
50  * By default, #GtkPopover performs a GTK+ grab, in order to ensure
51  * input events get redirected to it while it is shown, and also so
52  * the popover is dismissed in the expected situations (clicks outside
53  * the popover, or the Esc key being pressed). If no such modal behavior
54  * is desired on a popover, gtk_popover_set_modal() may be called on it
55  * to tweak its behavior.
56  * 
57  * ## GtkPopover as menu replacement
58  * 
59  * GtkPopover is often used to replace menus. To facilitate this, it
60  * supports being populated from a #GMenuModel, using
61  * gtk_popover_new_from_model(). In addition to all the regular menu
62  * model features, this function supports rendering sections in the
63  * model in a more compact form, as a row of icon buttons instead of
64  * menu items.
65  * 
66  * To use this rendering, set the ”display-hint” attribute of the
67  * section to ”horizontal-buttons” and set the icons of your items
68  * with the ”verb-icon” attribute.
69  * 
70  * |[
71  * <section>
72  * <attribute name="display-hint">horizontal-buttons</attribute>
73  * <item>
74  * <attribute name="label">Cut</attribute>
75  * <attribute name="action">app.cut</attribute>
76  * <attribute name="verb-icon">edit-cut-symbolic</attribute>
77  * </item>
78  * <item>
79  * <attribute name="label">Copy</attribute>
80  * <attribute name="action">app.copy</attribute>
81  * <attribute name="verb-icon">edit-copy-symbolic</attribute>
82  * </item>
83  * <item>
84  * <attribute name="label">Paste</attribute>
85  * <attribute name="action">app.paste</attribute>
86  * <attribute name="verb-icon">edit-paste-symbolic</attribute>
87  * </item>
88  * </section>
89  * ]|
90  */
91 public class Popover : Bin
92 {
93 	/** the main Gtk struct */
94 	protected GtkPopover* gtkPopover;
95 
96 	/** Get the main Gtk struct */
97 	public GtkPopover* getPopoverStruct()
98 	{
99 		return gtkPopover;
100 	}
101 
102 	/** the main Gtk struct as a void* */
103 	protected override void* getStruct()
104 	{
105 		return cast(void*)gtkPopover;
106 	}
107 
108 	protected override void setStruct(GObject* obj)
109 	{
110 		gtkPopover = cast(GtkPopover*)obj;
111 		super.setStruct(obj);
112 	}
113 
114 	/**
115 	 * Sets our main struct and passes it to the parent class.
116 	 */
117 	public this (GtkPopover* gtkPopover, bool ownedRef = false)
118 	{
119 		this.gtkPopover = gtkPopover;
120 		super(cast(GtkBin*)gtkPopover, ownedRef);
121 	}
122 
123 	/**
124 	 */
125 
126 	public static GType getType()
127 	{
128 		return gtk_popover_get_type();
129 	}
130 
131 	/**
132 	 * Creates a new popover to point to @relative_to
133 	 *
134 	 * Params:
135 	 *     relativeTo = #GtkWidget the popover is related to
136 	 *
137 	 * Return: a new #GtkPopover
138 	 *
139 	 * Since: 3.12
140 	 *
141 	 * Throws: ConstructionException GTK+ fails to create the object.
142 	 */
143 	public this(Widget relativeTo)
144 	{
145 		auto p = gtk_popover_new((relativeTo is null) ? null : relativeTo.getWidgetStruct());
146 		
147 		if(p is null)
148 		{
149 			throw new ConstructionException("null returned by new");
150 		}
151 		
152 		this(cast(GtkPopover*) p);
153 	}
154 
155 	/**
156 	 * Creates a #GtkPopover and populates it according to
157 	 * @model. The popover is pointed to the @relative_to widget.
158 	 *
159 	 * The created buttons are connected to actions found in the
160 	 * #GtkApplicationWindow to which the popover belongs - typically
161 	 * by means of being attached to a widget that is contained within
162 	 * the #GtkApplicationWindows widget hierarchy.
163 	 *
164 	 * Actions can also be added using gtk_widget_insert_action_group()
165 	 * on the menus attach widget or on any of its parent widgets.
166 	 *
167 	 * Params:
168 	 *     relativeTo = #GtkWidget the popover is related to
169 	 *     model = a #GMenuModel
170 	 *
171 	 * Return: the new #GtkPopover
172 	 *
173 	 * Since: 3.12
174 	 *
175 	 * Throws: ConstructionException GTK+ fails to create the object.
176 	 */
177 	public this(Widget relativeTo, MenuModel model)
178 	{
179 		auto p = gtk_popover_new_from_model((relativeTo is null) ? null : relativeTo.getWidgetStruct(), (model is null) ? null : model.getMenuModelStruct());
180 		
181 		if(p is null)
182 		{
183 			throw new ConstructionException("null returned by new_from_model");
184 		}
185 		
186 		this(cast(GtkPopover*) p);
187 	}
188 
189 	/**
190 	 * Establishes a binding between a #GtkPopover and a #GMenuModel.
191 	 *
192 	 * The contents of @popover are removed and then refilled with menu items
193 	 * according to @model.  When @model changes, @popover is updated.
194 	 * Calling this function twice on @popover with different @model will
195 	 * cause the first binding to be replaced with a binding to the new
196 	 * model. If @model is %NULL then any previous binding is undone and
197 	 * all children are removed.
198 	 *
199 	 * If @action_namespace is non-%NULL then the effect is as if all
200 	 * actions mentioned in the @model have their names prefixed with the
201 	 * namespace, plus a dot.  For example, if the action “quit” is
202 	 * mentioned and @action_namespace is “app” then the effective action
203 	 * name is “app.quit”.
204 	 *
205 	 * This function uses #GtkActionable to define the action name and
206 	 * target values on the created menu items.  If you want to use an
207 	 * action group other than “app” and “win”, or if you want to use a
208 	 * #GtkMenuShell outside of a #GtkApplicationWindow, then you will need
209 	 * to attach your own action group to the widget hierarchy using
210 	 * gtk_widget_insert_action_group().  As an example, if you created a
211 	 * group with a “quit” action and inserted it with the name “mygroup”
212 	 * then you would use the action name “mygroup.quit” in your
213 	 * #GMenuModel.
214 	 *
215 	 * Params:
216 	 *     model = the #GMenuModel to bind to or %NULL to remove
217 	 *         binding
218 	 *     actionNamespace = the namespace for actions in @model
219 	 *
220 	 * Since: 3.12
221 	 */
222 	public void bindModel(MenuModel model, string actionNamespace)
223 	{
224 		gtk_popover_bind_model(gtkPopover, (model is null) ? null : model.getMenuModelStruct(), Str.toStringz(actionNamespace));
225 	}
226 
227 	/**
228 	 * Gets the widget that should be set as the default while
229 	 * the popover is shown.
230 	 *
231 	 * Return: the default widget, or %NULL if there is none
232 	 *
233 	 * Since: 3.18
234 	 */
235 	public Widget getDefaultWidget()
236 	{
237 		auto p = gtk_popover_get_default_widget(gtkPopover);
238 		
239 		if(p is null)
240 		{
241 			return null;
242 		}
243 		
244 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
245 	}
246 
247 	/**
248 	 * Returns whether the popover is modal, see gtk_popover_set_modal to
249 	 * see the implications of this.
250 	 *
251 	 * Return: #TRUE if @popover is modal
252 	 *
253 	 * Since: 3.12
254 	 */
255 	public bool getModal()
256 	{
257 		return gtk_popover_get_modal(gtkPopover) != 0;
258 	}
259 
260 	/**
261 	 * If a rectangle to point to has been set, this function will
262 	 * return %TRUE and fill in @rect with such rectangle, otherwise
263 	 * it will return %FALSE and fill in @rect with the attached
264 	 * widget coordinates.
265 	 *
266 	 * Params:
267 	 *     rect = location to store the rectangle
268 	 *
269 	 * Return: %TRUE if a rectangle to point to was set.
270 	 */
271 	public bool getPointingTo(out GdkRectangle rect)
272 	{
273 		return gtk_popover_get_pointing_to(gtkPopover, &rect) != 0;
274 	}
275 
276 	/**
277 	 * Returns the preferred position of @popover.
278 	 *
279 	 * Return: The preferred position.
280 	 */
281 	public GtkPositionType getPosition()
282 	{
283 		return gtk_popover_get_position(gtkPopover);
284 	}
285 
286 	/**
287 	 * Returns the widget @popover is currently attached to
288 	 *
289 	 * Return: a #GtkWidget
290 	 *
291 	 * Since: 3.12
292 	 */
293 	public Widget getRelativeTo()
294 	{
295 		auto p = gtk_popover_get_relative_to(gtkPopover);
296 		
297 		if(p is null)
298 		{
299 			return null;
300 		}
301 		
302 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
303 	}
304 
305 	/**
306 	 * Returns whether show/hide transitions are enabled on this popover.
307 	 *
308 	 * Return: #TRUE if the show and hide transitions of the given
309 	 *     popover are enabled, #FALSE otherwise.
310 	 *
311 	 * Since: 3.16
312 	 */
313 	public bool getTransitionsEnabled()
314 	{
315 		return gtk_popover_get_transitions_enabled(gtkPopover) != 0;
316 	}
317 
318 	/**
319 	 * Sets the widget that should be set as default widget while
320 	 * the popover is shown (see gtk_window_set_default()). #GtkPopover
321 	 * remembers the previous default widget and reestablishes it
322 	 * when the popover is dismissed.
323 	 *
324 	 * Params:
325 	 *     widget = the new default widget, or %NULL
326 	 *
327 	 * Since: 3.18
328 	 */
329 	public void setDefaultWidget(Widget widget)
330 	{
331 		gtk_popover_set_default_widget(gtkPopover, (widget is null) ? null : widget.getWidgetStruct());
332 	}
333 
334 	/**
335 	 * Sets whether @popover is modal, a modal popover will grab all input
336 	 * within the toplevel and grab the keyboard focus on it when being
337 	 * displayed. Clicking outside the popover area or pressing Esc will
338 	 * dismiss the popover and ungrab input.
339 	 *
340 	 * Params:
341 	 *     modal = #TRUE to make popover claim all input within the toplevel
342 	 *
343 	 * Since: 3.12
344 	 */
345 	public void setModal(bool modal)
346 	{
347 		gtk_popover_set_modal(gtkPopover, modal);
348 	}
349 
350 	/**
351 	 * Sets the rectangle that @popover will point to, in the
352 	 * coordinate space of the widget @popover is attached to,
353 	 * see gtk_popover_set_relative_to().
354 	 *
355 	 * Params:
356 	 *     rect = rectangle to point to
357 	 *
358 	 * Since: 3.12
359 	 */
360 	public void setPointingTo(GdkRectangle* rect)
361 	{
362 		gtk_popover_set_pointing_to(gtkPopover, rect);
363 	}
364 
365 	/**
366 	 * Sets the preferred position for @popover to appear. If the @popover
367 	 * is currently visible, it will be immediately updated.
368 	 *
369 	 * This preference will be respected where possible, although
370 	 * on lack of space (eg. if close to the window edges), the
371 	 * #GtkPopover may choose to appear on the opposite side
372 	 *
373 	 * Params:
374 	 *     position = preferred popover position
375 	 *
376 	 * Since: 3.12
377 	 */
378 	public void setPosition(GtkPositionType position)
379 	{
380 		gtk_popover_set_position(gtkPopover, position);
381 	}
382 
383 	/**
384 	 * Sets a new widget to be attached to @popover. If @popover is
385 	 * visible, the position will be updated.
386 	 *
387 	 * Note: the ownership of popovers is always given to their @relative_to
388 	 * widget, so if @relative_to is set to %NULL on an attached @popover, it
389 	 * will be detached from its previous widget, and consequently destroyed
390 	 * unless extra references are kept.
391 	 *
392 	 * Params:
393 	 *     relativeTo = a #GtkWidget
394 	 *
395 	 * Since: 3.12
396 	 */
397 	public void setRelativeTo(Widget relativeTo)
398 	{
399 		gtk_popover_set_relative_to(gtkPopover, (relativeTo is null) ? null : relativeTo.getWidgetStruct());
400 	}
401 
402 	/**
403 	 * Sets whether show/hide transitions are enabled on this popover
404 	 *
405 	 * Params:
406 	 *     transitionsEnabled = Whether transitions are enabled
407 	 *
408 	 * Since: 3.16
409 	 */
410 	public void setTransitionsEnabled(bool transitionsEnabled)
411 	{
412 		gtk_popover_set_transitions_enabled(gtkPopover, transitionsEnabled);
413 	}
414 
415 	int[string] connectedSignals;
416 
417 	void delegate(Popover)[] onClosedListeners;
418 	void addOnClosed(void delegate(Popover) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
419 	{
420 		if ( "closed" !in connectedSignals )
421 		{
422 			Signals.connectData(
423 				this,
424 				"closed",
425 				cast(GCallback)&callBackClosed,
426 				cast(void*)this,
427 				null,
428 				connectFlags);
429 			connectedSignals["closed"] = 1;
430 		}
431 		onClosedListeners ~= dlg;
432 	}
433 	extern(C) static void callBackClosed(GtkPopover* popoverStruct, Popover _popover)
434 	{
435 		foreach ( void delegate(Popover) dlg; _popover.onClosedListeners )
436 		{
437 			dlg(_popover);
438 		}
439 	}
440 }