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