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.PadController;
26 
27 private import gdk.Device;
28 private import gio.ActionGroupIF;
29 private import glib.ConstructionException;
30 private import glib.Str;
31 private import gobject.ObjectG;
32 private import gtk.EventController;
33 private import gtk.Window;
34 private import gtk.c.functions;
35 public  import gtk.c.types;
36 public  import gtkc.gtktypes;
37 
38 
39 /**
40  * #GtkPadController is an event controller for the pads found in drawing
41  * tablets (The collection of buttons and tactile sensors often found around
42  * the stylus-sensitive area).
43  * 
44  * These buttons and sensors have no implicit meaning, and by default they
45  * perform no action, this event controller is provided to map those to
46  * #GAction objects, thus letting the application give those a more semantic
47  * meaning.
48  * 
49  * Buttons and sensors are not constrained to triggering a single action, some
50  * %GDK_SOURCE_TABLET_PAD devices feature multiple "modes", all these input
51  * elements have one current mode, which may determine the final action
52  * being triggered. Pad devices often divide buttons and sensors into groups,
53  * all elements in a group share the same current mode, but different groups
54  * may have different modes. See gdk_device_pad_get_n_groups() and
55  * gdk_device_pad_get_group_n_modes().
56  * 
57  * Each of the actions that a given button/strip/ring performs for a given
58  * mode is defined by #GtkPadActionEntry, it contains an action name that
59  * will be looked up in the given #GActionGroup and activated whenever the
60  * specified input element and mode are triggered.
61  * 
62  * A simple example of #GtkPadController usage, assigning button 1 in all
63  * modes and pad devices to an "invert-selection" action:
64  * |[
65  * GtkPadActionEntry *pad_actions[] = {
66  * { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
67  * …
68  * };
69  * 
70  * …
71  * action_group = g_simple_action_group_new ();
72  * action = g_simple_action_new ("pad-actions.invert-selection", NULL);
73  * g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
74  * g_action_map_add_action (G_ACTION_MAP (action_group), action);
75  * …
76  * pad_controller = gtk_pad_controller_new (window, action_group, NULL);
77  * ]|
78  * 
79  * The actions belonging to rings/strips will be activated with a parameter
80  * of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it
81  * is required that those are made stateful and accepting this #GVariantType.
82  */
83 public class PadController : EventController
84 {
85 	/** the main Gtk struct */
86 	protected GtkPadController* gtkPadController;
87 
88 	/** Get the main Gtk struct */
89 	public GtkPadController* getPadControllerStruct(bool transferOwnership = false)
90 	{
91 		if (transferOwnership)
92 			ownedRef = false;
93 		return gtkPadController;
94 	}
95 
96 	/** the main Gtk struct as a void* */
97 	protected override void* getStruct()
98 	{
99 		return cast(void*)gtkPadController;
100 	}
101 
102 	protected override void setStruct(GObject* obj)
103 	{
104 		gtkPadController = cast(GtkPadController*)obj;
105 		super.setStruct(obj);
106 	}
107 
108 	/**
109 	 * Sets our main struct and passes it to the parent class.
110 	 */
111 	public this (GtkPadController* gtkPadController, bool ownedRef = false)
112 	{
113 		this.gtkPadController = gtkPadController;
114 		super(cast(GtkEventController*)gtkPadController, ownedRef);
115 	}
116 
117 
118 	/** */
119 	public static GType getType()
120 	{
121 		return gtk_pad_controller_get_type();
122 	}
123 
124 	/**
125 	 * Creates a new #GtkPadController that will associate events from @pad to
126 	 * actions. A %NULL pad may be provided so the controller manages all pad devices
127 	 * generically, it is discouraged to mix #GtkPadController objects with %NULL
128 	 * and non-%NULL @pad argument on the same @window, as execution order is not
129 	 * guaranteed.
130 	 *
131 	 * The #GtkPadController is created with no mapped actions. In order to map pad
132 	 * events to actions, use gtk_pad_controller_set_action_entries() or
133 	 * gtk_pad_controller_set_action().
134 	 *
135 	 * Params:
136 	 *     window = a #GtkWindow
137 	 *     group = #GActionGroup to trigger actions from
138 	 *     pad = A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads
139 	 *
140 	 * Returns: A newly created #GtkPadController
141 	 *
142 	 * Since: 3.22
143 	 *
144 	 * Throws: ConstructionException GTK+ fails to create the object.
145 	 */
146 	public this(Window window, ActionGroupIF group, Device pad)
147 	{
148 		auto p = gtk_pad_controller_new((window is null) ? null : window.getWindowStruct(), (group is null) ? null : group.getActionGroupStruct(), (pad is null) ? null : pad.getDeviceStruct());
149 
150 		if(p is null)
151 		{
152 			throw new ConstructionException("null returned by new");
153 		}
154 
155 		this(cast(GtkPadController*) p, true);
156 	}
157 
158 	/**
159 	 * Adds an individual action to @controller. This action will only be activated
160 	 * if the given button/ring/strip number in @index is interacted while
161 	 * the current mode is @mode. -1 may be used for simple cases, so the action
162 	 * is triggered on all modes.
163 	 *
164 	 * The given @label should be considered user-visible, so internationalization
165 	 * rules apply. Some windowing systems may be able to use those for user
166 	 * feedback.
167 	 *
168 	 * Params:
169 	 *     type = the type of pad feature that will trigger this action
170 	 *     index = the 0-indexed button/ring/strip number that will trigger this action
171 	 *     mode = the mode that will trigger this action, or -1 for all modes.
172 	 *     label = Human readable description of this action, this string should
173 	 *         be deemed user-visible.
174 	 *     actionName = action name that will be activated in the #GActionGroup
175 	 *
176 	 * Since: 3.22
177 	 */
178 	public void setAction(GtkPadActionType type, int index, int mode, string label, string actionName)
179 	{
180 		gtk_pad_controller_set_action(gtkPadController, type, index, mode, Str.toStringz(label), Str.toStringz(actionName));
181 	}
182 
183 	/**
184 	 * This is a convenience function to add a group of action entries on
185 	 * @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action().
186 	 *
187 	 * Params:
188 	 *     entries = the action entries to set on @controller
189 	 *
190 	 * Since: 3.22
191 	 */
192 	public void setActionEntries(GtkPadActionEntry[] entries)
193 	{
194 		gtk_pad_controller_set_action_entries(gtkPadController, entries.ptr, cast(int)entries.length);
195 	}
196 }