## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --              GtkAda - Ada95 binding for Gtk+/Gnome                --

3.     --                                                                   --

4.     --                Copyright (C) 2006-2011, 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.     -----------------------------------------------------------------------

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>

103.     with Gdk.EventTo API docTo specTo body;

104.     with Gdk.TypesTo API docTo spec;

105.     with Glib.ObjectTo API docTo specTo body;

107.     package Gtk.BindingsTo API docTo specTo body is

109.        type Gtk_Binding_Set is new Glib.C_ProxyTo API docTo spec;

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.

117.        function Binding_Set_NewTo API docTo body (Set_Name : String) return Gtk_Binding_SetTo API docTo spec;

118.        --  Gtk+ maintains a global list of binding sets. Each binding set has a

119.        --  unique name which needs to be specified upon creation.

121.        function Binding_Set_By_ClassTo API docTo body

122.          (Object_Class : Glib.Object.GObject_ClassTo API docTo spec) return Gtk_Binding_SetTo API docTo spec;

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.

127.        function Binding_Set_FindTo API docTo body (Set_Name : String) return Gtk_Binding_SetTo API docTo spec;

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.

132.        function ActivateTo API docTo body

133.          (Object    : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

134.           Keyval    : GuintTo API docTo spec;

135.           Modifiers : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec)

136.           return Boolean;

137.        --  Find a key binding matching keyval and modifiers and activate the

138.        --  binding on object.

140.        function Activate_EventTo API docTo body

141.          (Object : access Glib.Object.GObject_RecordTo API docTo specTo body;

142.           Event  : Gdk.Event.Gdk_Event_KeyTo API docTo spec)

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

148.        function Binding_Set_ActivateTo API docTo body

149.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

150.           Keyval      : GuintTo API docTo spec;

151.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec;

152.           Object      : access Glib.Object.GObject_RecordTo API docTo specTo body'Class)

153.           return Boolean;

154.        --  Find a key binding matching keyval and modifiers within binding_set and

155.        --  activate the binding on object.

157.        procedure Binding_Entry_SkipTo API docTo body

158.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

159.           Keyval      : GuintTo API docTo spec;

160.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec);

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

166.        procedure Add_SignalTo API docTo body

167.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

168.           Keyval      : GuintTo API docTo spec;

169.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec;

170.           Signal_Name : String);

171.        procedure Add_SignalTo API docTo body

172.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

173.           Keyval      : GuintTo API docTo spec;

174.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec;

175.           Signal_Name : String;

176.           Arg1        : GintTo API docTo spec);

177.        procedure Add_SignalTo API docTo body

178.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

179.           Keyval      : GuintTo API docTo spec;

180.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec;

181.           Signal_Name : String;

182.           Arg1        : Boolean);

183.        procedure Add_SignalTo API docTo body

184.          (Binding_Set : Gtk_Binding_SetTo API docTo spec;

185.           Keyval      : GuintTo API docTo spec;

186.           Modifiers   : Gdk.Types.Gdk_Modifier_TypeTo API docTo spec;

187.           Signal_Name : String;

188.           Arg1        : GintTo API docTo spec;

189.           Arg2        : GintTo API docTo spec);

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.

194.     private

195.        pragma Import (C, Binding_Set_By_ClassTo API docTo spec, "gtk_binding_set_by_class");

196.        pragma Import (C, Binding_Entry_SkipTo API docTo spec,   "gtk_binding_entry_skip");

197.     end Gtk.BindingsTo API docTo specTo body;

199.     --  These are bound through our own C wrappers:

200.     --  No binding: gtk_binding_entry_add_signal

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