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.MenuItem;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gtk.AccelGroup;
32 private import gtk.ActionableIF;
33 private import gtk.ActionableT;
34 private import gtk.ActivatableIF;
35 private import gtk.ActivatableT;
36 private import gtk.Bin;
37 private import gtk.Menu;
38 private import gtk.Widget;
39 private import gtk.c.functions;
40 public  import gtk.c.types;
41 public  import gtkc.gtktypes;
42 private import std.algorithm;
43 
44 
45 /**
46  * The #GtkMenuItem widget and the derived widgets are the only valid
47  * children for menus. Their function is to correctly handle highlighting,
48  * alignment, events and submenus.
49  * 
50  * As a GtkMenuItem derives from #GtkBin it can hold any valid child widget,
51  * although only a few are really useful.
52  * 
53  * By default, a GtkMenuItem sets a #GtkAccelLabel as its child.
54  * GtkMenuItem has direct functions to set the label and its mnemonic.
55  * For more advanced label settings, you can fetch the child widget from the GtkBin.
56  * 
57  * An example for setting markup and accelerator on a MenuItem:
58  * |[<!-- language="C" -->
59  * GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item");
60  * 
61  * GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item));
62  * gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
63  * gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);
64  * ]|
65  * 
66  * # GtkMenuItem as GtkBuildable
67  * 
68  * The GtkMenuItem implementation of the #GtkBuildable interface supports
69  * adding a submenu by specifying “submenu” as the “type” attribute of
70  * a <child> element.
71  * 
72  * An example of UI definition fragment with submenus:
73  * |[
74  * <object class="GtkMenuItem">
75  * <child type="submenu">
76  * <object class="GtkMenu"/>
77  * </child>
78  * </object>
79  * ]|
80  * 
81  * # CSS nodes
82  * 
83  * |[<!-- language="plain" -->
84  * menuitem
85  * ├── <child>
86  * ╰── [arrow.right]
87  * ]|
88  * 
89  * GtkMenuItem has a single CSS node with name menuitem. If the menuitem
90  * has a submenu, it gets another CSS node with name arrow, which has
91  * the .left or .right style class.
92  */
93 public class MenuItem : Bin, ActionableIF, ActivatableIF
94 {
95 	/** the main Gtk struct */
96 	protected GtkMenuItem* gtkMenuItem;
97 
98 	/** Get the main Gtk struct */
99 	public GtkMenuItem* getMenuItemStruct(bool transferOwnership = false)
100 	{
101 		if (transferOwnership)
102 			ownedRef = false;
103 		return gtkMenuItem;
104 	}
105 
106 	/** the main Gtk struct as a void* */
107 	protected override void* getStruct()
108 	{
109 		return cast(void*)gtkMenuItem;
110 	}
111 
112 	/**
113 	 * Sets our main struct and passes it to the parent class.
114 	 */
115 	public this (GtkMenuItem* gtkMenuItem, bool ownedRef = false)
116 	{
117 		this.gtkMenuItem = gtkMenuItem;
118 		super(cast(GtkBin*)gtkMenuItem, ownedRef);
119 	}
120 
121 	// add the Actionable capabilities
122 	mixin ActionableT!(GtkMenuItem);
123 
124 	// add the Activatable capabilities
125 	mixin ActivatableT!(GtkMenuItem);
126 
127 	/** store the action code passed in by the applcation */
128 	private string actionLabel;
129 
130 	/** Gets the application set action code */
131 	public string getActionName()
132 	{
133 		if ( actionLabel is null )
134 		{
135 			actionLabel = "";
136 		}
137 		return actionLabel;
138 	}
139 
140 	/**
141 	 * Creates a new menu item with a label and a listener and a action.
142 	 * used for backward compatibily with DUI.
143 	 */
144 	this(string label, void delegate(MenuItem)dlg, string action)
145 	{
146 		this(label);
147 		this.actionLabel = action;
148 		addOnActivate(dlg);
149 	}
150 
151 	/**
152 	 * Creates a new Item associated with a "activate" delegate and with a action code
153 	 * and optionally accelGroup
154 	 */
155 	public this(void delegate(MenuItem) dlg, string label, string action,
156 	bool mnemonic=true,
157 	AccelGroup accelGroup=null,
158 	char accelKey='\0',
159 	GdkModifierType modifierType=GdkModifierType.CONTROL_MASK,
160 	GtkAccelFlags accelFlags=GtkAccelFlags.VISIBLE
161 	)
162 	{
163 		this(label, mnemonic);
164 		this.actionLabel = action;
165 		addOnActivate(dlg);
166 		if ( accelGroup !is null && accelKey != '\0' )
167 		{
168 			addAccelerator("activate",accelGroup,accelKey,modifierType,accelFlags);
169 		}
170 	}
171 
172 	/**
173 	 * Creates a new Item associated with a "activate" delegate
174 	 */
175 	public this(void delegate(MenuItem) dlg, string label, bool mnemonic=true)
176 	{
177 		this(label, mnemonic);
178 		addOnActivate(dlg);
179 	}
180 
181 	/**
182 	 * Creates a new GtkMenuItem whose child is a GtkLabel.
183 	 * Params:
184 	 *  label = the text for the label
185 	 *  mnemonic = if true the label
186 	 *  will be created using gtk_label_new_with_mnemonic(), so underscores
187 	 *  in label indicate the mnemonic for the menu item.
188 	 * Throws: ConstructionException GTK+ fails to create the object.
189 	 */
190 	public this (string label, bool mnemonic=true)
191 	{
192 		GtkMenuItem* p;
193 
194 		if ( mnemonic )
195 		{
196 			// GtkWidget* gtk_menu_item_new_with_mnemonic (const gchar *label);
197 			p = cast(GtkMenuItem*)gtk_menu_item_new_with_mnemonic(Str.toStringz(label));
198 		}
199 		else
200 		{
201 			// GtkWidget* gtk_menu_item_new_with_label (const gchar *label);
202 			p = cast(GtkMenuItem*)gtk_menu_item_new_with_label(Str.toStringz(label));
203 		}
204 
205 		if(p is null)
206 		{
207 			throw new ConstructionException("null returned by gtk_menu_item_new_with_");
208 		}
209 
210 		this(p);
211 
212 		setName(label);
213 	}
214 
215 	/**
216 	 */
217 
218 	/** */
219 	public static GType getType()
220 	{
221 		return gtk_menu_item_get_type();
222 	}
223 
224 	/**
225 	 * Creates a new #GtkMenuItem.
226 	 *
227 	 * Returns: the newly created #GtkMenuItem
228 	 *
229 	 * Throws: ConstructionException GTK+ fails to create the object.
230 	 */
231 	public this()
232 	{
233 		auto p = gtk_menu_item_new();
234 
235 		if(p is null)
236 		{
237 			throw new ConstructionException("null returned by new");
238 		}
239 
240 		this(cast(GtkMenuItem*) p);
241 	}
242 
243 	/**
244 	 * Emits the #GtkMenuItem::activate signal on the given item
245 	 */
246 	public void itemActivate()
247 	{
248 		gtk_menu_item_activate(gtkMenuItem);
249 	}
250 
251 	/**
252 	 * Emits the #GtkMenuItem::deselect signal on the given item.
253 	 */
254 	public void deselect()
255 	{
256 		gtk_menu_item_deselect(gtkMenuItem);
257 	}
258 
259 	/**
260 	 * Retrieve the accelerator path that was previously set on @menu_item.
261 	 *
262 	 * See gtk_menu_item_set_accel_path() for details.
263 	 *
264 	 * Returns: the accelerator path corresponding to
265 	 *     this menu item’s functionality, or %NULL if not set
266 	 *
267 	 * Since: 2.14
268 	 */
269 	public string getAccelPath()
270 	{
271 		return Str.toString(gtk_menu_item_get_accel_path(gtkMenuItem));
272 	}
273 
274 	/**
275 	 * Sets @text on the @menu_item label
276 	 *
277 	 * Returns: The text in the @menu_item label. This is the internal
278 	 *     string used by the label, and must not be modified.
279 	 *
280 	 * Since: 2.16
281 	 */
282 	public string getLabel()
283 	{
284 		return Str.toString(gtk_menu_item_get_label(gtkMenuItem));
285 	}
286 
287 	/**
288 	 * Returns whether the @menu_item reserves space for
289 	 * the submenu indicator, regardless if it has a submenu
290 	 * or not.
291 	 *
292 	 * Returns: %TRUE if @menu_item always reserves space for the
293 	 *     submenu indicator
294 	 *
295 	 * Since: 3.0
296 	 */
297 	public bool getReserveIndicator()
298 	{
299 		return gtk_menu_item_get_reserve_indicator(gtkMenuItem) != 0;
300 	}
301 
302 	/**
303 	 * Gets whether the menu item appears justified at the right
304 	 * side of the menu bar.
305 	 *
306 	 * Deprecated: See gtk_menu_item_set_right_justified()
307 	 *
308 	 * Returns: %TRUE if the menu item will appear at the
309 	 *     far right if added to a menu bar.
310 	 */
311 	public bool getRightJustified()
312 	{
313 		return gtk_menu_item_get_right_justified(gtkMenuItem) != 0;
314 	}
315 
316 	/**
317 	 * Gets the submenu underneath this menu item, if any.
318 	 * See gtk_menu_item_set_submenu().
319 	 *
320 	 * Returns: submenu for this menu item, or %NULL if none
321 	 */
322 	public Widget getSubmenu()
323 	{
324 		auto p = gtk_menu_item_get_submenu(gtkMenuItem);
325 
326 		if(p is null)
327 		{
328 			return null;
329 		}
330 
331 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
332 	}
333 
334 	/**
335 	 * Checks if an underline in the text indicates the next character
336 	 * should be used for the mnemonic accelerator key.
337 	 *
338 	 * Returns: %TRUE if an embedded underline in the label
339 	 *     indicates the mnemonic accelerator key.
340 	 *
341 	 * Since: 2.16
342 	 */
343 	public bool getUseUnderline()
344 	{
345 		return gtk_menu_item_get_use_underline(gtkMenuItem) != 0;
346 	}
347 
348 	/**
349 	 * Emits the #GtkMenuItem::select signal on the given item.
350 	 */
351 	public void select()
352 	{
353 		gtk_menu_item_select(gtkMenuItem);
354 	}
355 
356 	/**
357 	 * Set the accelerator path on @menu_item, through which runtime
358 	 * changes of the menu item’s accelerator caused by the user can be
359 	 * identified and saved to persistent storage (see gtk_accel_map_save()
360 	 * on this). To set up a default accelerator for this menu item, call
361 	 * gtk_accel_map_add_entry() with the same @accel_path. See also
362 	 * gtk_accel_map_add_entry() on the specifics of accelerator paths,
363 	 * and gtk_menu_set_accel_path() for a more convenient variant of
364 	 * this function.
365 	 *
366 	 * This function is basically a convenience wrapper that handles
367 	 * calling gtk_widget_set_accel_path() with the appropriate accelerator
368 	 * group for the menu item.
369 	 *
370 	 * Note that you do need to set an accelerator on the parent menu with
371 	 * gtk_menu_set_accel_group() for this to work.
372 	 *
373 	 * Note that @accel_path string will be stored in a #GQuark.
374 	 * Therefore, if you pass a static string, you can save some memory
375 	 * by interning it first with g_intern_static_string().
376 	 *
377 	 * Params:
378 	 *     accelPath = accelerator path, corresponding to this menu
379 	 *         item’s functionality, or %NULL to unset the current path.
380 	 */
381 	public void setAccelPath(string accelPath)
382 	{
383 		gtk_menu_item_set_accel_path(gtkMenuItem, Str.toStringz(accelPath));
384 	}
385 
386 	/**
387 	 * Sets @text on the @menu_item label
388 	 *
389 	 * Params:
390 	 *     label = the text you want to set
391 	 *
392 	 * Since: 2.16
393 	 */
394 	public void setLabel(string label)
395 	{
396 		gtk_menu_item_set_label(gtkMenuItem, Str.toStringz(label));
397 	}
398 
399 	/**
400 	 * Sets whether the @menu_item should reserve space for
401 	 * the submenu indicator, regardless if it actually has
402 	 * a submenu or not.
403 	 *
404 	 * There should be little need for applications to call
405 	 * this functions.
406 	 *
407 	 * Params:
408 	 *     reserve = the new value
409 	 *
410 	 * Since: 3.0
411 	 */
412 	public void setReserveIndicator(bool reserve)
413 	{
414 		gtk_menu_item_set_reserve_indicator(gtkMenuItem, reserve);
415 	}
416 
417 	/**
418 	 * Sets whether the menu item appears justified at the right
419 	 * side of a menu bar. This was traditionally done for “Help”
420 	 * menu items, but is now considered a bad idea. (If the widget
421 	 * layout is reversed for a right-to-left language like Hebrew
422 	 * or Arabic, right-justified-menu-items appear at the left.)
423 	 *
424 	 * Deprecated: If you insist on using it, use
425 	 * gtk_widget_set_hexpand() and gtk_widget_set_halign().
426 	 *
427 	 * Params:
428 	 *     rightJustified = if %TRUE the menu item will appear at the
429 	 *         far right if added to a menu bar
430 	 */
431 	public void setRightJustified(bool rightJustified)
432 	{
433 		gtk_menu_item_set_right_justified(gtkMenuItem, rightJustified);
434 	}
435 
436 	/**
437 	 * Sets or replaces the menu item’s submenu, or removes it when a %NULL
438 	 * submenu is passed.
439 	 *
440 	 * Params:
441 	 *     submenu = the submenu, or %NULL
442 	 */
443 	public void setSubmenu(Menu submenu)
444 	{
445 		gtk_menu_item_set_submenu(gtkMenuItem, (submenu is null) ? null : cast(GtkWidget*)submenu.getMenuStruct());
446 	}
447 
448 	/**
449 	 * If true, an underline in the text indicates the next character
450 	 * should be used for the mnemonic accelerator key.
451 	 *
452 	 * Params:
453 	 *     setting = %TRUE if underlines in the text indicate mnemonics
454 	 *
455 	 * Since: 2.16
456 	 */
457 	public void setUseUnderline(bool setting)
458 	{
459 		gtk_menu_item_set_use_underline(gtkMenuItem, setting);
460 	}
461 
462 	/**
463 	 * Emits the #GtkMenuItem::toggle-size-allocate signal on the given item.
464 	 *
465 	 * Params:
466 	 *     allocation = the allocation to use as signal data.
467 	 */
468 	public void toggleSizeAllocate(int allocation)
469 	{
470 		gtk_menu_item_toggle_size_allocate(gtkMenuItem, allocation);
471 	}
472 
473 	/**
474 	 * Emits the #GtkMenuItem::toggle-size-request signal on the given item.
475 	 *
476 	 * Params:
477 	 *     requisition = the requisition to use as signal data.
478 	 */
479 	public void toggleSizeRequest(ref int requisition)
480 	{
481 		gtk_menu_item_toggle_size_request(gtkMenuItem, &requisition);
482 	}
483 
484 	/**
485 	 * Emitted when the item is activated.
486 	 */
487 	gulong addOnActivate(void delegate(MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
488 	{
489 		return Signals.connect(this, "activate", dlg, connectFlags ^ ConnectFlags.SWAPPED);
490 	}
491 
492 	/**
493 	 * Emitted when the item is activated, but also if the menu item has a
494 	 * submenu. For normal applications, the relevant signal is
495 	 * #GtkMenuItem::activate.
496 	 */
497 	gulong addOnActivateItem(void delegate(MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
498 	{
499 		return Signals.connect(this, "activate-item", dlg, connectFlags ^ ConnectFlags.SWAPPED);
500 	}
501 
502 	/** */
503 	gulong addOnDeselect(void delegate(MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
504 	{
505 		return Signals.connect(this, "deselect", dlg, connectFlags ^ ConnectFlags.SWAPPED);
506 	}
507 
508 	/** */
509 	gulong addOnSelect(void delegate(MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
510 	{
511 		return Signals.connect(this, "select", dlg, connectFlags ^ ConnectFlags.SWAPPED);
512 	}
513 
514 	/** */
515 	gulong addOnToggleSizeAllocate(void delegate(int, MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
516 	{
517 		return Signals.connect(this, "toggle-size-allocate", dlg, connectFlags ^ ConnectFlags.SWAPPED);
518 	}
519 
520 	/** */
521 	gulong addOnToggleSizeRequest(void delegate(void*, MenuItem) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
522 	{
523 		return Signals.connect(this, "toggle-size-request", dlg, connectFlags ^ ConnectFlags.SWAPPED);
524 	}
525 }