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.ImageMenuItem;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gtk.AccelGroup;
31 private import gtk.MenuItem;
32 private import gtk.Widget;
33 private import gtk.c.functions;
34 public  import gtk.c.types;
35 public  import gtkc.gtktypes;
36 
37 
38 /**
39  * A GtkImageMenuItem is a menu item which has an icon next to the text label.
40  * 
41  * This is functionally equivalent to:
42  * 
43  * |[<!-- language="C" -->
44  * GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
45  * GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU);
46  * GtkWidget *label = gtk_label_new ("Music");
47  * GtkWidget *menu_item = gtk_menu_item_new ();
48  * 
49  * gtk_container_add (GTK_CONTAINER (box), icon);
50  * gtk_container_add (GTK_CONTAINER (box), label);
51  * 
52  * gtk_container_add (GTK_CONTAINER (menu_item), box);
53  * 
54  * gtk_widget_show_all (menu_item);
55  * ]|
56  * 
57  * Note that the user may disable display of menu icons using
58  * the #GtkSettings:gtk-menu-images setting, so make sure to still
59  * fill in the text label. If you want to ensure that your menu items
60  * show an icon you are strongly encouraged to use a #GtkMenuItem
61  * with a #GtkImage instead.
62  * 
63  * #GtkImageMenuItem has been deprecated since GTK+ 3.10. If you want to
64  * display an icon in a menu item, you should use #GtkMenuItem and pack a
65  * #GtkBox with a #GtkImage and a #GtkLabel instead. You should also consider
66  * using #GtkBuilder and the XML #GMenu description for creating menus, by
67  * following the [GMenu guide][https://developer.gnome.org/GMenu/]. You should
68  * consider using icons in menu items only sparingly, and for "objects" (or
69  * "nouns") elements only, like bookmarks, files, and links; "actions" (or
70  * "verbs") should not have icons.
71  * 
72  * Furthermore, if you would like to display keyboard accelerator, you must
73  * pack the accel label into the box using gtk_box_pack_end() and align the
74  * label, otherwise the accelerator will not display correctly. The following
75  * code snippet adds a keyboard accelerator to the menu item, with a key
76  * binding of Ctrl+M:
77  * 
78  * |[<!-- language="C" -->
79  * GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
80  * GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU);
81  * GtkWidget *label = gtk_accel_label_new ("Music");
82  * GtkWidget *menu_item = gtk_menu_item_new ();
83  * GtkAccelGroup *accel_group = gtk_accel_group_new ();
84  * 
85  * gtk_container_add (GTK_CONTAINER (box), icon);
86  * 
87  * gtk_label_set_use_underline (GTK_LABEL (label), TRUE);
88  * gtk_label_set_xalign (GTK_LABEL (label), 0.0);
89  * 
90  * gtk_widget_add_accelerator (menu_item, "activate", accel_group,
91  * GDK_KEY_m, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
92  * gtk_accel_label_set_accel_widget (GTK_ACCEL_LABEL (label), menu_item);
93  * 
94  * gtk_box_pack_end (GTK_BOX (box), label, TRUE, TRUE, 0);
95  * 
96  * gtk_container_add (GTK_CONTAINER (menu_item), box);
97  * 
98  * gtk_widget_show_all (menu_item);
99  * ]|
100  */
101 public class ImageMenuItem : MenuItem
102 {
103 	/** the main Gtk struct */
104 	protected GtkImageMenuItem* gtkImageMenuItem;
105 
106 	/** Get the main Gtk struct */
107 	public GtkImageMenuItem* getImageMenuItemStruct(bool transferOwnership = false)
108 	{
109 		if (transferOwnership)
110 			ownedRef = false;
111 		return gtkImageMenuItem;
112 	}
113 
114 	/** the main Gtk struct as a void* */
115 	protected override void* getStruct()
116 	{
117 		return cast(void*)gtkImageMenuItem;
118 	}
119 
120 	/**
121 	 * Sets our main struct and passes it to the parent class.
122 	 */
123 	public this (GtkImageMenuItem* gtkImageMenuItem, bool ownedRef = false)
124 	{
125 		this.gtkImageMenuItem = gtkImageMenuItem;
126 		super(cast(GtkMenuItem*)gtkImageMenuItem, ownedRef);
127 	}
128 
129 	/**
130 	 * Creates a new GtkImageMenuItem containing a label.
131 	 * If mnemonic it true the label will be created using
132 	 * gtk_label_new_with_mnemonic(), so underscores
133 	 * in label indicate the mnemonic for the menu item.
134 	 * Params:
135 	 *  label = the text of the menu item.
136 	 * Throws: ConstructionException GTK+ fails to create the object.
137 	 */
138 	public this (string label, bool mnemonic=true)
139 	{
140 		GtkImageMenuItem* p;
141 
142 		if ( mnemonic )
143 		{
144 			// GtkWidget* gtk_image_menu_item_new_with_mnemonic  (const gchar *label);
145 			p = cast(GtkImageMenuItem*)gtk_image_menu_item_new_with_mnemonic(Str.toStringz(label));
146 		}
147 		else
148 		{
149 			// GtkWidget* gtk_image_menu_item_new_with_label  (const gchar *label);
150 			p = cast(GtkImageMenuItem*)gtk_image_menu_item_new_with_label(Str.toStringz(label));
151 		}
152 
153 		if(p is null)
154 		{
155 			throw new ConstructionException("null returned by gtk_image_menu_item_new_with_");
156 		}
157 
158 		this(p);
159 	}
160 
161 	/**
162 	 * Creates a new GtkImageMenuItem containing the image and text from a
163 	 * stock item.
164 	 * If you want this menu item to have changeable accelerators, then pass in
165 	 * null for accelGroup. Next call setAccelPath() with an appropriate path
166 	 * for the menu item, use gtk.StockItem.StockItem.lookup() to look up the
167 	 * standard accelerator for the stock item, and if one is found, call
168 	 * gtk.AccelMap.AccelMap.addEntry() to register it.
169 	 * Params:
170 	 *   StockID    = the name of the stock item
171 	 *   accelGroup = the GtkAccelGroup to add the menu items accelerator to,
172 	 *                or NULL.
173 	 * Throws: ConstructionException GTK+ fails to create the object.
174 	 */
175 	public this (StockID stockID, AccelGroup accelGroup)
176 	{
177 		auto p = gtk_image_menu_item_new_from_stock(Str.toStringz(stockID), (accelGroup is null) ? null : accelGroup.getAccelGroupStruct());
178 		if(p is null)
179 		{
180 			throw new ConstructionException("null returned by gtk_image_menu_item_new_from_stock");
181 		}
182 		this(cast(GtkImageMenuItem*) p);
183 	}
184 
185 	/**
186 	 */
187 
188 	/** */
189 	public static GType getType()
190 	{
191 		return gtk_image_menu_item_get_type();
192 	}
193 
194 	/**
195 	 * Creates a new #GtkImageMenuItem with an empty label.
196 	 *
197 	 * Deprecated: Use gtk_menu_item_new() instead.
198 	 *
199 	 * Returns: a new #GtkImageMenuItem
200 	 *
201 	 * Throws: ConstructionException GTK+ fails to create the object.
202 	 */
203 	public this()
204 	{
205 		auto p = gtk_image_menu_item_new();
206 
207 		if(p is null)
208 		{
209 			throw new ConstructionException("null returned by new");
210 		}
211 
212 		this(cast(GtkImageMenuItem*) p);
213 	}
214 
215 	/**
216 	 * Returns whether the menu item will ignore the #GtkSettings:gtk-menu-images
217 	 * setting and always show the image, if available.
218 	 *
219 	 * Returns: %TRUE if the menu item will always show the image
220 	 *
221 	 * Since: 2.16
222 	 */
223 	public bool getAlwaysShowImage()
224 	{
225 		return gtk_image_menu_item_get_always_show_image(gtkImageMenuItem) != 0;
226 	}
227 
228 	/**
229 	 * Gets the widget that is currently set as the image of @image_menu_item.
230 	 * See gtk_image_menu_item_set_image().
231 	 *
232 	 * Returns: the widget set as image of @image_menu_item
233 	 */
234 	public Widget getImage()
235 	{
236 		auto p = gtk_image_menu_item_get_image(gtkImageMenuItem);
237 
238 		if(p is null)
239 		{
240 			return null;
241 		}
242 
243 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
244 	}
245 
246 	/**
247 	 * Checks whether the label set in the menuitem is used as a
248 	 * stock id to select the stock item for the item.
249 	 *
250 	 * Returns: %TRUE if the label set in the menuitem is used as a
251 	 *     stock id to select the stock item for the item
252 	 *
253 	 * Since: 2.16
254 	 */
255 	public bool getUseStock()
256 	{
257 		return gtk_image_menu_item_get_use_stock(gtkImageMenuItem) != 0;
258 	}
259 
260 	/**
261 	 * Specifies an @accel_group to add the menu items accelerator to
262 	 * (this only applies to stock items so a stock item must already
263 	 * be set, make sure to call gtk_image_menu_item_set_use_stock()
264 	 * and gtk_menu_item_set_label() with a valid stock item first).
265 	 *
266 	 * If you want this menu item to have changeable accelerators then
267 	 * you shouldnt need this (see gtk_image_menu_item_new_from_stock()).
268 	 *
269 	 * Params:
270 	 *     accelGroup = the #GtkAccelGroup
271 	 *
272 	 * Since: 2.16
273 	 */
274 	public void setAccelGroup(AccelGroup accelGroup)
275 	{
276 		gtk_image_menu_item_set_accel_group(gtkImageMenuItem, (accelGroup is null) ? null : accelGroup.getAccelGroupStruct());
277 	}
278 
279 	/**
280 	 * If %TRUE, the menu item will ignore the #GtkSettings:gtk-menu-images
281 	 * setting and always show the image, if available.
282 	 *
283 	 * Use this property if the menuitem would be useless or hard to use
284 	 * without the image.
285 	 *
286 	 * Params:
287 	 *     alwaysShow = %TRUE if the menuitem should always show the image
288 	 *
289 	 * Since: 2.16
290 	 */
291 	public void setAlwaysShowImage(bool alwaysShow)
292 	{
293 		gtk_image_menu_item_set_always_show_image(gtkImageMenuItem, alwaysShow);
294 	}
295 
296 	/**
297 	 * Sets the image of @image_menu_item to the given widget.
298 	 * Note that it depends on the show-menu-images setting whether
299 	 * the image will be displayed or not.
300 	 *
301 	 * Params:
302 	 *     image = a widget to set as the image for the menu item.
303 	 */
304 	public void setImage(Widget image)
305 	{
306 		gtk_image_menu_item_set_image(gtkImageMenuItem, (image is null) ? null : image.getWidgetStruct());
307 	}
308 
309 	/**
310 	 * If %TRUE, the label set in the menuitem is used as a
311 	 * stock id to select the stock item for the item.
312 	 *
313 	 * Params:
314 	 *     useStock = %TRUE if the menuitem should use a stock item
315 	 *
316 	 * Since: 2.16
317 	 */
318 	public void setUseStock(bool useStock)
319 	{
320 		gtk_image_menu_item_set_use_stock(gtkImageMenuItem, useStock);
321 	}
322 }