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 	/**
120 	 * Sets our main struct and passes it to the parent class.
121 	 */
122 	public this (GtkAccelLabel* gtkAccelLabel, bool ownedRef = false)
123 	{
124 		this.gtkAccelLabel = gtkAccelLabel;
125 		super(cast(GtkLabel*)gtkAccelLabel, ownedRef);
126 	}
127 
128 
129 	/** */
130 	public static GType getType()
131 	{
132 		return gtk_accel_label_get_type();
133 	}
134 
135 	/**
136 	 * Creates a new #GtkAccelLabel.
137 	 *
138 	 * Params:
139 	 *     str = the label string. Must be non-%NULL.
140 	 *
141 	 * Returns: a new #GtkAccelLabel.
142 	 *
143 	 * Throws: ConstructionException GTK+ fails to create the object.
144 	 */
145 	public this(string str)
146 	{
147 		auto p = gtk_accel_label_new(Str.toStringz(str));
148 
149 		if(p is null)
150 		{
151 			throw new ConstructionException("null returned by new");
152 		}
153 
154 		this(cast(GtkAccelLabel*) p);
155 	}
156 
157 	/**
158 	 * Gets the keyval and modifier mask set with
159 	 * gtk_accel_label_set_accel().
160 	 *
161 	 * Params:
162 	 *     acceleratorKey = return location for the keyval
163 	 *     acceleratorMods = return location for the modifier mask
164 	 *
165 	 * Since: 3.12
166 	 */
167 	public void getAccel(out uint acceleratorKey, out GdkModifierType acceleratorMods)
168 	{
169 		gtk_accel_label_get_accel(gtkAccelLabel, &acceleratorKey, &acceleratorMods);
170 	}
171 
172 	/**
173 	 * Fetches the widget monitored by this accelerator label. See
174 	 * gtk_accel_label_set_accel_widget().
175 	 *
176 	 * Returns: the object monitored by the accelerator label, or %NULL.
177 	 */
178 	public Widget getAccelWidget()
179 	{
180 		auto p = gtk_accel_label_get_accel_widget(gtkAccelLabel);
181 
182 		if(p is null)
183 		{
184 			return null;
185 		}
186 
187 		return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p);
188 	}
189 
190 	/**
191 	 * Returns the width needed to display the accelerator key(s).
192 	 * This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't
193 	 * be needed by applications.
194 	 *
195 	 * Returns: the width needed to display the accelerator key(s).
196 	 */
197 	public uint getAccelWidth()
198 	{
199 		return gtk_accel_label_get_accel_width(gtkAccelLabel);
200 	}
201 
202 	/**
203 	 * Recreates the string representing the accelerator keys.
204 	 * This should not be needed since the string is automatically updated whenever
205 	 * accelerators are added or removed from the associated widget.
206 	 *
207 	 * Returns: always returns %FALSE.
208 	 */
209 	public bool refetch()
210 	{
211 		return gtk_accel_label_refetch(gtkAccelLabel) != 0;
212 	}
213 
214 	/**
215 	 * Manually sets a keyval and modifier mask as the accelerator rendered
216 	 * by @accel_label.
217 	 *
218 	 * If a keyval and modifier are explicitly set then these values are
219 	 * used regardless of any associated accel closure or widget.
220 	 *
221 	 * Providing an @accelerator_key of 0 removes the manual setting.
222 	 *
223 	 * Params:
224 	 *     acceleratorKey = a keyval, or 0
225 	 *     acceleratorMods = the modifier mask for the accel
226 	 *
227 	 * Since: 3.6
228 	 */
229 	public void setAccel(uint acceleratorKey, GdkModifierType acceleratorMods)
230 	{
231 		gtk_accel_label_set_accel(gtkAccelLabel, acceleratorKey, acceleratorMods);
232 	}
233 
234 	/**
235 	 * Sets the closure to be monitored by this accelerator label. The closure
236 	 * must be connected to an accelerator group; see gtk_accel_group_connect().
237 	 * Passing %NULL for @accel_closure will dissociate @accel_label from its
238 	 * current closure, if any.
239 	 *
240 	 * Params:
241 	 *     accelClosure = the closure to monitor for accelerator changes,
242 	 *         or %NULL
243 	 */
244 	public void setAccelClosure(Closure accelClosure)
245 	{
246 		gtk_accel_label_set_accel_closure(gtkAccelLabel, (accelClosure is null) ? null : accelClosure.getClosureStruct());
247 	}
248 
249 	/**
250 	 * Sets the widget to be monitored by this accelerator label. Passing %NULL for
251 	 * @accel_widget will dissociate @accel_label from its current widget, if any.
252 	 *
253 	 * Params:
254 	 *     accelWidget = the widget to be monitored, or %NULL
255 	 */
256 	public void setAccelWidget(Widget accelWidget)
257 	{
258 		gtk_accel_label_set_accel_widget(gtkAccelLabel, (accelWidget is null) ? null : accelWidget.getWidgetStruct());
259 	}
260 }