1-----------------------------------------------------------------------
2--              GtkAda - Ada95 binding for Gtk+/Gnome                --
3--                                                                   --
4--                Copyright (C) 2006-2013, AdaCore                   --
5--                                                                   --
6-- This library is free software; you can redistribute it and/or     --
7-- modify it under the terms of the GNU General Public               --
8-- License as published by the Free Software Foundation; either      --
9-- version 2 of the License, or (at your option) any later version.  --
10--                                                                   --
11-- This library is distributed in the hope that it will be useful,   --
12-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --
13-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --
14-- General Public License for more details.                          --
15--                                                                   --
16-- You should have received a copy of the GNU General Public         --
17-- License along with this library; if not, write to the             --
18-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --
19-- Boston, MA 02111-1307, USA.                                       --
20--                                                                   --
21-- As a special exception, if other files instantiate generics from  --
22-- this unit, or you link this unit with other files to produce an   --
23-- executable, this  unit  does not  by itself cause  the resulting  --
24-- executable to be covered by the GNU General Public License. This  --
25-- exception does not however invalidate any other reasons why the   --
26-- executable file  might be covered by the  GNU Public License.     --
27-----------------------------------------------------------------------
28
29--  <description>
30--  Gtk_Bindings provides a mechanism for configuring Gtk+ key bindings through
31--  RC files. This eases key binding adjustments for application developers as
32--  well as users and provides Gtk+ users or administrators with high key
33--  binding configurability which requires no application or toolkit side
34--  changes.
35--
36--  Installing a key binding
37--  ========================
38--
39--  A resource file binding consists of a 'binding' definition and a match
40--  statement to apply the binding to specific widget types. Details on the
41--  matching mechanism are described under Pathnames and patterns. Inside the
42--  binding definition, key combinations are bound to specific signal emissions
43--  on the target widget. Key combinations are strings consisting of an
44--  optional Gdk_Modifier_Type name and key names such as those defined in
45--  Gdk.Types.Keysyms or returned from gdk_keyval_name(), they have to be
46--  parsable by gtk_accelerator_parse(). Specifications of signal emissions
47--  consist of a string identifying the signal name, and a list of signal
48--  specific arguments in parenthesis. For example for binding Control and the
49--  left or right cursor keys of a Gtk_Entry widget to the
50--  Gtk_Entry::move-cursor signal, so movement occurs in 3 letter steps, the
51--  following binding can be used:
52--
53--  binding "MoveCursor3" {
54--     bind "<Control>Right" {
55--       "move-cursor" (visual-positions, 3, 0)
56--     }
57--     bind "<Control>Left" {
58--       "move-cursor" (visual-positions, -3, 0)
59--     }
60--  }
61--  class "GtkEntry" binding "MoveCursor3"
62--
63--  Unbinding existing key bindings
64--  ===============================
65--
66--  Gtk+ already defines a number of useful bindings for the widgets it
67--  provides. Because custom bindings set up in RC files take precedence over
68--  the default bindings shipped with Gtk+, overriding existing bindings as
69--  demonstrated in Installing a key binding works as expected. The same
70--  mechanism can not be used to "unbind" existing bindings, however.
71--
72--  binding "MoveCursor3" {
73--     bind "<Control>Right" { }
74--     bind "<Control>Left" { }
75--  }
76--  class "GtkEntry" binding "MoveCursor3"
77--
78--  The above example will not have the desired effect of causing
79--  "<Control>Right" and "<Control>Left" key presses to be ignored by Gtk+.
80--  Instead, it just causes any existing bindings from the bindings set
81--  "MoveCursor3" to be deleted, so when "<Control>Right" or "<Control>Left"
82--  are pressed, no binding for these keys is found in binding set
83--  "MoveCursor3". Gtk+ will thus continue to search for matching key bindings,
84--  and will eventually lookup and find the default Gtk+ bindings for entries
85--  which implement word movement. To keep Gtk+ from activating its default
86--  bindings, the "unbind" keyword can be used like this:
87--
88--  binding "MoveCursor3" {
89--     unbind "<Control>Right"
90--     unbind "<Control>Left"
91--  }
92--  class "GtkEntry" binding "MoveCursor3"
93--
94--  Now, Gtk+ will find a match when looking up "<Control>Right" and
95--  "<Control>Left" key presses before it resorts to its default bindings, and
96--  the match instructs it to abort ("unbind") the search, so the key presses
97--  are not consumed by this widget. As usual, further processing of the key
98--  presses, e.g. by an entries parent widget, is now possible.
99--  </description>
100--  <c_version>2.14</c_version>
101--  <group>Configuration and Themes</group>
102
103with Gdk.Event;
104with Gdk.Types;
105with Glib.Object;
106
107package Gtk.Bindings is
108
109   type Gtk_Binding_Set is new Glib.C_Proxy;
110   --  A binding set maintains a list of activatable key bindings. A single
111   --  binding set can match multiple types of widgets. Similar to styles,
112   --  widgets can be mapped by widget name paths, widget class paths or widget
113   --  class types. When a binding within a set is matched upon activation, an
114   --  action signal is emitted on the target widget to carry out the actual
115   --  activation.
116
117   function Binding_Set_New (Set_Name : String) return Gtk_Binding_Set;
118   --  Gtk+ maintains a global list of binding sets. Each binding set has a
119   --  unique name which needs to be specified upon creation.
120
121   function Binding_Set_By_Class
122     (Object_Class : Glib.Object.GObject_Class) return Gtk_Binding_Set;
123   --  This function returns the binding set named after the type name of the
124   --  passed in class structure. New binding sets are created on demand by
125   --  this function.
126
127   function Binding_Set_Find (Set_Name : String) return Gtk_Binding_Set;
128   --  Find a binding set by its globally unique name. The set_name can either
129   --  be a name used for Binding_Set_New or the type name of a class
130   --  used in Binding_Set_By_Class.
131
132   function Activate
133     (Object    : access Glib.Object.GObject_Record'Class;
134      Keyval    : Guint;
135      Modifiers : Gdk.Types.Gdk_Modifier_Type)
136      return Boolean;
137   --  Find a key binding matching keyval and modifiers and activate the
138   --  binding on object.
139
140   function Activate_Event
141     (Object : access Glib.Object.GObject_Record;
142      Event  : Gdk.Event.Gdk_Event_Key)
143      return Boolean;
144   --  Looks up key bindings for Object to find one matching
145   --  Event, and if one was found, activate it.
146   --  Return value: True if a matching key binding was found
147
148   function Binding_Set_Activate
149     (Binding_Set : Gtk_Binding_Set;
150      Keyval      : Guint;
151      Modifiers   : Gdk.Types.Gdk_Modifier_Type;
152      Object      : access Glib.Object.GObject_Record'Class)
153      return Boolean;
154   --  Find a key binding matching keyval and modifiers within binding_set and
155   --  activate the binding on object.
156
157   procedure Binding_Entry_Skip
158     (Binding_Set : Gtk_Binding_Set;
159      Keyval      : Guint;
160      Modifiers   : Gdk.Types.Gdk_Modifier_Type);
161   --  Install a binding on Binding_Set which causes key lookups
162   --  to be aborted, to prevent bindings from lower priority sets
163   --  to be activated.
164   --  Since: 2.12
165
166   procedure Add_Signal
167     (Binding_Set : Gtk_Binding_Set;
168      Keyval      : Guint;
169      Modifiers   : Gdk.Types.Gdk_Modifier_Type;
170      Signal_Name : String);
171   procedure Add_Signal
172     (Binding_Set : Gtk_Binding_Set;
173      Keyval      : Guint;
174      Modifiers   : Gdk.Types.Gdk_Modifier_Type;
175      Signal_Name : String;
176      Arg1        : Gint);
177   procedure Add_Signal
178     (Binding_Set : Gtk_Binding_Set;
179      Keyval      : Guint;
180      Modifiers   : Gdk.Types.Gdk_Modifier_Type;
181      Signal_Name : String;
182      Arg1        : Boolean);
183   procedure Add_Signal
184     (Binding_Set : Gtk_Binding_Set;
185      Keyval      : Guint;
186      Modifiers   : Gdk.Types.Gdk_Modifier_Type;
187      Signal_Name : String;
188      Arg1        : Gint;
189      Arg2        : Gint);
190   --  Override or install a new key binding for keyval with modifiers on
191   --  binding_set. When the binding is activated, signal_name will be emitted
192   --  on the target widget, with the given arguments as argument.
193
194private
195   pragma Import (C, Binding_Set_By_Class, "gtk_binding_set_by_class");
196   pragma Import (C, Binding_Entry_Skip,   "gtk_binding_entry_skip");
197end Gtk.Bindings;
198
199--  These are bound through our own C wrappers:
200--  No binding: gtk_binding_entry_add_signal
201
202--  These are internal gtk+ functions
203--  No binding: gtk_binding_entry_add_signall
204--  No binding: gtk_binding_entry_clear
205--  No binding: gtk_binding_entry_remove
206--  No binding: gtk_binding_parse_binding
207--  No binding: gtk_binding_set_add_path
208