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.AccelLabel;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.Closure;
30 private import gobject.ObjectG;
31 private import gtk.Label;
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  * The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an
40  * accelerator key on the right of the label text, e.g. “Ctrl+S”.
41  * It is commonly used in menus to show the keyboard short-cuts for commands.
42  * 
43  * The accelerator key to display is typically not set explicitly (although it
44  * can be, with gtk_accel_label_set_accel()). Instead, the #GtkAccelLabel displays
45  * the accelerators which have been added to a particular widget. This widget is
46  * set by calling gtk_accel_label_set_accel_widget().
47  * 
48  * For example, a #GtkMenuItem widget may have an accelerator added to emit
49  * the “activate” signal when the “Ctrl+S” key combination is pressed.
50  * A #GtkAccelLabel is created and added to the #GtkMenuItem, and
51  * gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the
52  * second argument. The #GtkAccelLabel will now display “Ctrl+S” after its label.
53  * 
54  * Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or
55  * one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem)
56  * automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls
57  * gtk_accel_label_set_accel_widget() to set it up for you.
58  * 
59  * A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE
60  * set (see #GtkAccelFlags).
61  * A #GtkAccelLabel can display multiple accelerators and even signal names,
62  * though it is almost always used to display just one accelerator key.
63  * 
64  * ## Creating a simple menu item with an accelerator key.
65  * 
66  * |[<!-- language="C" -->
67  * GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
68  * GtkWidget *menu = gtk_menu_new ();
69  * GtkWidget *save_item;
70  * GtkAccelGroup *accel_group;
71  * 
72  * // Create a GtkAccelGroup and add it to the window.
73  * accel_group = gtk_accel_group_new ();
74  * gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
75  * 
76  * // Create the menu item using the convenience function.
77  * save_item = gtk_menu_item_new_with_label ("Save");
78  * gtk_widget_show (save_item);
79  * gtk_container_add (GTK_CONTAINER (menu), save_item);
80  * 
81  * // Now add the accelerator to the GtkMenuItem. Note that since we
82  * // called gtk_menu_item_new_with_label() to create the GtkMenuItem
83  * // the GtkAccelLabel is automatically set up to display the
84  * // GtkMenuItem accelerators. We just need to make sure we use
85  * // GTK_ACCEL_VISIBLE here.
86  * gtk_widget_add_accelerator (save_item, "activate", accel_group,
87  * GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
88  * ]|
89  * 
90  * # CSS nodes
91  * 
92  * |[<!-- language="plain" -->
93  * label
94  * ╰── accelerator
95  * ]|
96  * 
97  * Like #GtkLabel, GtkAccelLabel has a main CSS node with the name label.
98  * It adds a subnode with name accelerator.
99  */
100 public class AccelLabel : Label
101 {
102 	/** the main Gtk struct */
103 	protected GtkAccelLabel* gtkAccelLabel;
104 
105 	/** Get the main Gtk struct */
106 	public GtkAccelLabel* getAccelLabelStruct(bool transferOwnership = false)
107 	{
108 		if (transferOwnership)
109 			ownedRef = false;
110 		return gtkAccelLabel;
111 	}
112 
113 	/** the main Gtk struct as a void* */
114 	protected override void* getStruct()
115 	{
116 		return cast(void*)gtkAccelLabel;
117 	}
118 
119 	protected override void setStruct(GObject* obj)
120 	{
121 		gtkAccelLabel = cast(GtkAccelLabel*)obj;
122 		super.setStruct(obj);
123 	}
124 
125 	/**
126 	 * Sets our main struct and passes it to the parent class.
127 	 */
128 	public this (GtkAccelLabel* gtkAccelLabel, bool ownedRef = false)
129 	{
130 		this.gtkAccelLabel = gtkAccelLabel;
131 		super(cast(GtkLabel*)gtkAccelLabel, ownedRef);
132 	}
133 
134 
135 	/** */
136 	public static GType getType()
137 	{
138 		return gtk_accel_label_get_type();
139 	}
140 
141 	/**
142 	 * Creates a new #GtkAccelLabel.
143 	 *
144 	 * Params:
145 	 *     str = the label string. Must be non-%NULL.
146 	 *
147 	 * Returns: a new #GtkAccelLabel.
148 	 *
149 	 * Throws: ConstructionException GTK+ fails to create the object.
150 	 */
151 	public this(string str)
152 	{
153 		auto p = gtk_accel_label_new(Str.toStringz(str));
154 
155 		if(p is null)
156 		{
157 			throw new ConstructionException("null returned by new");
158 		}
159 
160 		this(cast(GtkAccelLabel*) p);
161 	}
162 
163 	/**
164 	 * Gets the keyval and modifier mask set with
165 	 * gtk_accel_label_set_accel().
166 	 *
167 	 * Params:
168 	 *     acceleratorKey = return location for the keyval
169 	 *     acceleratorMods = return location for the modifier mask
170 	 *
171 	 * Since: 3.12
172 	 */
173 	public void getAccel(out uint acceleratorKey, out GdkModifierType acceleratorMods)
174 	{
175 		gtk_accel_label_get_accel(gtkAccelLabel, &acceleratorKey, &acceleratorMods);
176 	}
177 
178 	/**
179 	 * Fetches the widget monitored by this accelerator label. See
180 	 * gtk_accel_label_set_accel_widget().
181 	 *
182 	 * Returns: the object monitored by the accelerator label, or %NULL.
183 	 */
184 	public Widget getAccelWidget()
185 	{
186 		auto p = gtk_accel_label_get_accel_widget(gtkAccelLabel);
187 
188 		if(p is null)
189 		{
190 			return null;
191 		}
192 
193 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
194 	}
195 
196 	/**
197 	 * Returns the width needed to display the accelerator key(s).
198 	 * This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't
199 	 * be needed by applications.
200 	 *
201 	 * Returns: the width needed to display the accelerator key(s).
202 	 */
203 	public uint getAccelWidth()
204 	{
205 		return gtk_accel_label_get_accel_width(gtkAccelLabel);
206 	}
207 
208 	/**
209 	 * Recreates the string representing the accelerator keys.
210 	 * This should not be needed since the string is automatically updated whenever
211 	 * accelerators are added or removed from the associated widget.
212 	 *
213 	 * Returns: always returns %FALSE.
214 	 */
215 	public bool refetch()
216 	{
217 		return gtk_accel_label_refetch(gtkAccelLabel) != 0;
218 	}
219 
220 	/**
221 	 * Manually sets a keyval and modifier mask as the accelerator rendered
222 	 * by @accel_label.
223 	 *
224 	 * If a keyval and modifier are explicitly set then these values are
225 	 * used regardless of any associated accel closure or widget.
226 	 *
227 	 * Providing an @accelerator_key of 0 removes the manual setting.
228 	 *
229 	 * Params:
230 	 *     acceleratorKey = a keyval, or 0
231 	 *     acceleratorMods = the modifier mask for the accel
232 	 *
233 	 * Since: 3.6
234 	 */
235 	public void setAccel(uint acceleratorKey, GdkModifierType acceleratorMods)
236 	{
237 		gtk_accel_label_set_accel(gtkAccelLabel, acceleratorKey, acceleratorMods);
238 	}
239 
240 	/**
241 	 * Sets the closure to be monitored by this accelerator label. The closure
242 	 * must be connected to an accelerator group; see gtk_accel_group_connect().
243 	 * Passing %NULL for @accel_closure will dissociate @accel_label from its
244 	 * current closure, if any.
245 	 *
246 	 * Params:
247 	 *     accelClosure = the closure to monitor for accelerator changes,
248 	 *         or %NULL
249 	 */
250 	public void setAccelClosure(Closure accelClosure)
251 	{
252 		gtk_accel_label_set_accel_closure(gtkAccelLabel, (accelClosure is null) ? null : accelClosure.getClosureStruct());
253 	}
254 
255 	/**
256 	 * Sets the widget to be monitored by this accelerator label. Passing %NULL for
257 	 * @accel_widget will dissociate @accel_label from its current widget, if any.
258 	 *
259 	 * Params:
260 	 *     accelWidget = the widget to be monitored, or %NULL
261 	 */
262 	public void setAccelWidget(Widget accelWidget)
263 	{
264 		gtk_accel_label_set_accel_widget(gtkAccelLabel, (accelWidget is null) ? null : accelWidget.getWidgetStruct());
265 	}
266 }