## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

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

31.     --  This package provides a high-level API for using Gtk.Builder and

32.     --  user interface files produced with the GUI builder glade-3.

33.     --

34.     --  Here is how to use this package:

35.     --

36.     --     Step 1: create a Builder and add the XML data, just as you would a

37.     --             standard Gtk.Builder:

38.     --

39.     --             declare

40.     --                Builder : Gtkada_Builder;

41.     --                Error   : GError;

42.     --             begin

43.     --                Gtk_New (Builder);

44.     --                Error := Add_From_File (Builder, Default_Filename);

45.     --

46.     --     Step 2: add calls to "Register_Handler" to associate your handlers

47.     --             with your callbacks.

48.     --

49.     --                Register_Handler

50.     --                   (Builder      => Builder,

51.     --                    Handler_Name => "my_handler_id",

52.     --                    Handler      => My_Handler'Access);

53.     --

54.     --             Where:

55.     --              - Builder is your Gtkada_Builder,

56.     --              - "my_handler_id" is the name of the handler as specified in

57.     --                  Glade-3, in the "Handler" column of the "Signals" tab for

58.     --                  your object,

59.     --              - Handler is your Ada subprogram.

60.     --

61.     --              You will need one call to "Register_Handler" per handler

62.     --              declared in the Glade-3 interface. If there is one or more

63.     --              handler declared in Glade-3 which does not have an associated

64.     --              call to Register_Handler, an ASSERT_FAILURE will be raised by

65.     --              the Gtk main loop.

66.     --

67.     --              There are multiple way to call Register_Handler, see below.

68.     --

69.     --     Step 3: call Do_Connect.

70.     --

71.     --     Step 4: when the application terminates or all Windows described through

72.     --             your builder should be closed, call Unref to free memory

73.     --             associated with the Builder.

74.     --

75.     --  </description>

76.     --  <group>GUI Builder</group>

78.     pragma Ada_2005;

80.     with Ada.Containers.Hashed_Maps;

81.     with Ada.Strings.Unbounded; use Ada.Strings.Unbounded;

82.     with Ada.Strings.Unbounded.Hash;

84.     with Glib.ObjectTo API docTo specTo body; use Glib.ObjectTo API docTo specTo body;

85.     with Gtk.BuilderTo API docTo specTo body;

87.     package Gtkada.BuilderTo API docTo specTo body is

89.        type Gtkada_Builder_RecordTo API docTo body is new

90.          Gtk.Builder.Gtk_Builder_RecordTo API docTo specTo body with private;

91.        type Gtkada_Builder is access all Gtkada_Builder_RecordTo API docTo specTo body'Class;

93.        procedure Gtk_NewTo API docTo body (Builder : out Gtkada_BuilderTo API docTo spec);

94.        procedure InitializeTo API docTo body (Builder : access Gtkada_Builder_RecordTo API docTo specTo body'Class);

95.        --  Create a new Gtkada_Builder.

97.        procedure Do_ConnectTo API docTo body (Builder : access Gtkada_Builder_RecordTo API docTo specTo body'Class);

98.        --  Activate in the builder callabacks that have been connected using

99.        --  calls to Register_Handler functions below.

101.        --------------------------------------

102.        -- Callbacks working on the Builder --

103.        --------------------------------------

105.        --  These callbacks take as parameter the Gtkada_Builder.

106.        --  If a "User data" is present in the Glade-3, it will be ignored.

108.        type Builder_Handler is access procedure

109.          (Builder : access Gtkada_Builder_RecordTo API docTo specTo body'Class);

111.        type Builder_Return_Handler is access function

112.          (User_Data : access Gtkada_Builder_RecordTo API docTo specTo body'Class) return Boolean;

114.        procedure Register_HandlerTo API docTo body

115.          (Builder      : access Gtkada_Builder_RecordTo API docTo specTo body'Class;

116.           Handler_Name : String;

117.           Handler      : Builder_HandlerTo API docTo spec);

119.        procedure Register_HandlerTo API docTo body

120.          (Builder      : access Gtkada_Builder_RecordTo API docTo specTo body'Class;

121.           Handler_Name : String;

122.           Handler      : Builder_Return_HandlerTo API docTo spec);

124.        --------------------------------------------------------------

125.        -- Callbacks working on user data specified through Glade-3 --

126.        --------------------------------------------------------------

128.        --  Use these registry functions if your signal handler was defined in

129.        --  the Glade-3 interface with a "User data". The parameter User_Data

130.        --  passed to the handlers corresponds to the object entered in the

131.        --  "User data" column in Glade-3.

133.        type Object_Handler is access procedure

134.          (User_Data : access GObject_RecordTo API docTo specTo body'Class);

136.        type Object_Return_Handler is access function

137.          (User_Data : access GObject_RecordTo API docTo specTo body'Class) return Boolean;

139.        procedure Register_HandlerTo API docTo body

140.          (Builder      : access Gtkada_Builder_RecordTo API docTo specTo body'Class;

141.           Handler_Name : String;

142.           Handler      : Object_HandlerTo API docTo spec);

144.        procedure Register_HandlerTo API docTo body

145.          (Builder      : access Gtkada_Builder_RecordTo API docTo specTo body'Class;

146.           Handler_Name : String;

147.           Handler      : Object_Return_HandlerTo API docTo spec);

149.     private

151.        type Handler_Type is (Object, Object_Return, Builder, Builder_Return);

152.        type Universal_Marshaller (T : Handler_Type) is record

153.           case T is

154.              when Object =>

155.                 The_Object_Handler : Object_HandlerTo API docTo spec;

156.              when Object_Return =>

157.                 The_Object_Return_Handler : Object_Return_HandlerTo API docTo spec;

158.              when Builder =>

159.                 The_Builder_Handler : Builder_HandlerTo API docTo spec;

160.              when Builder_Return =>

161.                 The_Builder_Return_Handler : Builder_Return_HandlerTo API docTo spec;

162.           end case;

163.        end record;

165.        type Universal_Marshaller_Access is access Universal_Marshaller;

167.        package Handlers_Map is new Ada.Containers.Hashed_Maps

168.          (Key_Type        => Unbounded_String,

169.           Element_Type    => Universal_Marshaller_Access,

170.           Hash            => Ada.Strings.Unbounded.Hash,

171.           Equivalent_Keys => "=",

172.           "="             => "=");

174.        type Gtkada_Builder_RecordTo API docTo spec is new

175.          Gtk.Builder.Gtk_Builder_RecordTo API docTo specTo body

176.        with record

177.           Handlers : Handlers_Map.Map;

178.        end record;

180.     end Gtkada.BuilderTo API docTo specTo body;