## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   --

5.     --                Copyright (C) 2000-2010, AdaCore                   --

6.     --                                                                   --

7.     -- This library is free software; you can redistribute it and/or     --

8.     -- modify it under the terms of the GNU General Public               --

9.     -- License as published by the Free Software Foundation; either      --

10.     -- version 2 of the License, or (at your option) any later version.  --

11.     --                                                                   --

12.     -- This library is distributed in the hope that it will be useful,   --

13.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

14.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

15.     -- General Public License for more details.                          --

16.     --                                                                   --

17.     -- You should have received a copy of the GNU General Public         --

18.     -- License along with this library; if not, write to the             --

19.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

20.     -- Boston, MA 02111-1307, USA.                                       --

21.     --                                                                   --

22.     -- As a special exception, if other files instantiate generics from  --

23.     -- this unit, or you link this unit with other files to produce an   --

24.     -- executable, this  unit  does not  by itself cause  the resulting  --

25.     -- executable to be covered by the GNU General Public License. This  --

26.     -- exception does not however invalidate any other reasons why the   --

27.     -- executable file  might be covered by the  GNU Public License.     --

28.     -----------------------------------------------------------------------

30.     --  <description>

31.     --

32.     --  This package provides definitions for the basic types used in Glib, Cairo,

33.     --  Gdk and Gtk.

34.     --

35.     --  </description>

36.     --  <group>Glib, the general-purpose library</group>

38.     with Ada.Unchecked_Deallocation;

39.     with Ada.Unchecked_Conversion;

40.     with System;

41.     with Interfaces.C;

43.     package GlibTo API docTo body is

44.        pragma Preelaborate;

46.        package C renames Interfaces.C;

47.        use type C.int;

48.        use type C.unsigned;

50.        -------------------------------------

51.        -- The basic types defined by glib --

52.        -------------------------------------

54.        type Gshort is new C.short;

55.        type Glong  is new C.long;

56.        type Gint   is new C.int;

57.        type Gchar  is new C.char;

58.        type Gboolean is new GintTo API docTo spec;

60.        type Gushort is new C.unsigned_short;

61.        type Gulong  is new C.unsigned_long;

62.        type Guint   is new C.unsigned;

63.        type Guchar  is new C.unsigned_char;

65.        type Gfloat  is new C.C_float;

66.        type Gdouble is new C.double;

68.        type Gint8  is range -(2 ** 7) .. (2 ** 7 - 1);

69.        type Gint16 is range -(2 ** 15) .. (2 ** 15 - 1);

70.        type Gint32 is range -(2 ** 31) .. (2 ** 31 - 1);

71.        type Gint64 is range -(2 ** 63) .. (2 ** 63 - 1);

73.        type Guint8  is mod 2 ** 8;

74.        type Guint16 is mod 2 ** 16;

75.        type Guint32 is mod 2 ** 32;

76.        type Guint64 is mod 2 ** 64;

78.        type Gsize is new C.size_t;

80.        type Gunichar is new Guint32To API docTo spec;

82.        subtype UTF8_String is String;

83.        --  A string that accepts only valid UTF8 sequences.

84.        --  Most Gtk+ function expect valid UTF8 strings instead of regular strings.

86.        type GTime_Val is record

87.           TV_Sec  : GlongTo API docTo spec;

88.           TV_Usec : GlongTo API docTo spec;

89.        end record;

90.        pragma Convention (CTo API docTo spec, GTime_ValTo API docTo spec);

92.        type GTime_Val_Access is access all GTime_ValTo API docTo spec;

93.        pragma Convention (CTo API docTo spec, GTime_Val_AccessTo API docTo spec);

95.        subtype Grange_Float is GdoubleTo API docTo spec;

96.        --  Needed for better compatibility between GtkAda 1.2 and 2.0

98.        subtype Gcolor_Int is Guint16To API docTo spec;

99.        --  Provided for better compatibility between GtkAda 1.2 and 2.0

101.        subtype Allocation_Int is GintTo API docTo spec;

102.        --  Provided for better compatibility between GtkAda 1.2 and 2.0

104.        ----------------------

105.        -- Some Array types --

106.        ----------------------

108.        type Gboolean_Array is array (Natural range <>) of GbooleanTo API docTo spec;

109.        type Gshort_Array   is array (Natural range <>) of GshortTo API docTo spec;

110.        type Glong_Array    is array (Natural range <>) of GlongTo API docTo spec;

111.        type Gint_Array     is array (Natural range <>) of GintTo API docTo spec;

112.        type Guint_Array    is array (Natural range <>) of GuintTo API docTo spec;

113.        type Guint32_Array  is array (Natural range <>) of Guint32To API docTo spec;

114.        type Gushort_Array  is array (Natural range <>) of GushortTo API docTo spec;

115.        type Gulong_Array   is array (Natural range <>) of GulongTo API docTo spec;

116.        type Gfloat_Array   is array (Natural range <>) of GfloatTo API docTo spec;

117.        type Guchar_Array   is array (Natural range <>) of GucharTo API docTo spec;

118.        type Gdouble_Array  is array (Natural range <>) of GdoubleTo API docTo spec;

120.        type Boolean_Array  is array (Natural range <>) of Boolean;

122.        type Short_Array    is array (Natural range <>) of C.short;

123.        type Long_Array     is array (Natural range <>) of C.long;

125.        -------------------------

126.        -- Conversion services --

127.        -------------------------

129.        function To_Boolean_ArrayTo API docTo body (A : Gboolean_ArrayTo API docTo spec) return Boolean_ArrayTo API docTo spec;

130.        --  Convert a C-style boolean array into an Ada-style array.

132.        function To_GintTo API docTo body (Bool : Boolean) return GintTo API docTo spec;

133.        --  Convert an Ada boolean into a C int.

135.        -----------------------

136.        -- Some Access types --

137.        -----------------------

139.        type Guchar_Array_Access is access Guchar_ArrayTo API docTo spec;

141.        type String_Ptr is access all String;

143.        --  <doc_ignore>

144.        procedure Free is new Ada.Unchecked_Deallocation

145.          (Object => Guchar_ArrayTo API docTo spec, Name => Guchar_Array_AccessTo API docTo spec);

147.        procedure Free is new Ada.Unchecked_Deallocation

148.          (Object => String, Name => String_PtrTo API docTo spec);

149.        --  </doc_ignore>

151.        --  <doc_ignore>

152.        type C_DummyTo API docTo body is limited private;

153.        --  </doc_ignore>

155.        type C_Proxy is access all C_DummyTo API docTo specTo body;

156.        --  General proxy for C structures.

157.        --  This type is used instead of System.Address so that the variables are

158.        --  automatically initialized to 'null'.

159.        --  The value pointed to is irrelevant, and in fact should not be accessed.

160.        --  It has thus been made limited private with no subprogram to access it.

161.        --  C_Proxy is a public type so that one can compare directly the value

162.        --  of the variables with 'null'.

164.        --  <doc_ignore>

165.        pragma Convention (CTo API docTo spec, C_ProxyTo API docTo spec);

167.        function To_Proxy is new Ada.Unchecked_Conversion (System.Address, C_ProxyTo API docTo spec);

168.        function To_Address is new

169.          Ada.Unchecked_Conversion (C_ProxyTo API docTo spec, System.Address);

170.        --  Converts from a System.Address returned by a C function to an

171.        --  internal C_Proxy.

173.        --  </doc_ignore>

175.        type G_Destroy_Notify_Address is

176.          access procedure (Data : System.Address);

177.        pragma Convention (CTo API docTo spec, G_Destroy_Notify_AddressTo API docTo spec);

179.        type G_Destroy_Notify is access procedure (Data : Glib.C_ProxyTo API docTo spec);

180.        pragma Convention (CTo API docTo spec, G_Destroy_NotifyTo API docTo spec);

181.        --  Callback used when some named data associated with an object is

182.        --  destroyed.

184.        ------------

185.        -- Quarks --

186.        ------------

188.        type GQuark is new Guint32To API docTo spec;

189.        --  Represents a string internally in GtkAda. Once you know the

190.        --  equivalent for a string, you can always use it instead of the string,

191.        --  which provides a faster access for all the functions that use htables

192.        --  in GtkAda.

193.        --  There is a global htable that contains all the quarks defined in

194.        --  your application and GtkAda itself.

196.        Unknown_Quark : constant GQuarkTo API docTo spec := 0;

198.        function Quark_From_StringTo API docTo body (Id : String) return GQuarkTo API docTo spec;

199.        --  Return, or create the quark associated with the string.

200.        --  Note that if the quark does not already exist, an entry is created for

201.        --  it in the global htable for quarks.

203.        function Quark_Try_StringTo API docTo body (Id : String) return GQuarkTo API docTo spec;

204.        --  Return the quark associated with the string, if it exists.

205.        --  If it does not exist, return Unknown_Quark.

207.        -------------

208.        -- Signals --

209.        -------------

211.        type Signal_Id is private;

212.        --  This uniquely identifies a connection widget<->signal.

214.        type Signal_Name is new String;

215.        --  A signal name as used in connect, shared type between the Gtk

216.        --  and Glib layer.

218.        Invalid_Signal_Id : constant Signal_IdTo API docTo spec;

219.        Null_Signal_Id : constant Signal_IdTo API docTo spec;

221.        type G_Connect_Flags is mod 2 ** C.int'Size;

222.        G_Connect_After   : constant G_Connect_FlagsTo API docTo spec := 2 ** 0;

223.        G_Connect_Swapped : constant G_Connect_FlagsTo API docTo spec := 2 ** 1;

224.        --  Used to specify the behavior of a signal's connection.

226.        ----------------

227.        -- Properties --

228.        ----------------

229.        --  This is only the definition of the property types. See Glib.Properties

230.        --  on how to get and set the value of properties for specific objects, or

231.        --  the package Glib.Properties.Creation for information on how to create

232.        --  new properties in your own widgets.

233.        --  Introspection is available, ie from an existing object you can find out

234.        --  the list of properties it supports. See the functions

235.        --  Glib.Object.Interface_List_Properties and

236.        --  Glib.Object.Class_List_Properties

238.        type Property (<>) is private;

240.        function BuildTo API docTo body (Name : String) return PropertyTo API docTo spec;

241.        --  You should use this function only if you are creating new widgets, and

242.        --  their properties. Normal usage of properties doesn't require the use

243.        --  of this function.

244.        --  An ASCII.NUL character is automatically appended if necessary

246.        function Property_NameTo API docTo body (Prop : PropertyTo API docTo spec) return String;

247.        --  Return the name of the property.

248.        --  This name includes the trailing ASCII.Nul, and thus can be passed as is

249.        --  to C.

251.        type Param_Spec is new Glib.C_ProxyTo API docTo spec;

252.        type Param_Spec_Array is array (Natural range <>) of Param_SpecTo API docTo spec;

253.        --  See Glib.Properties.Creation for more information on this type

255.        type Param_Flags is mod 2 ** 6;

256.        Param_Readable       : constant Param_FlagsTo API docTo spec := 2 ** 0;

257.        Param_Writable       : constant Param_FlagsTo API docTo spec := 2 ** 1;

258.        Param_Construct      : constant Param_FlagsTo API docTo spec := 2 ** 2;

259.        Param_Construct_Only : constant Param_FlagsTo API docTo spec := 2 ** 3;

260.        Param_Lax_Validation : constant Param_FlagsTo API docTo spec := 2 ** 4;

261.        Param_Private        : constant Param_FlagsTo API docTo spec := 2 ** 5;

262.        --  These are the various flags that help define if, and when, a property

263.        --  can be read and modified.

265.        -----------

266.        -- GType --

267.        -----------

269.        type GType is new GsizeTo API docTo spec;

270.        --  This type describes an internal type in Glib.

271.        --  You shouldn't have to use it in your own applications, however it might

272.        --  be useful sometimes.

273.        --  Every object type is associated with a specific value, created

274.        --  dynamically at run time the first time you instantiate an object of that

275.        --  type (thus if you have never used e.g a Gtk_File_Selection, it won't

276.        --  have any GType associated with it).

277.        --  You can get the exact type value for each type by using the functions

278.        --  Get_Type provided in all the packages in GtkAda.

279.        --  You can get the specific value for an existing widget by using the

280.        --  function Glib.Object.Get_Type.

282.        type GType_Class is private;

283.        --  An opaque structure used as the base for all classes in glib and gtk+.

284.        --  See also Glib.Object.GObject_Class for a more useful child of this

285.        --  type.

287.        type GType_Array is array (GuintTo API docTo spec range <>) of Glib.GTypeTo API docTo spec;

289.        function ParentTo API docTo body (Typ : GTypeTo API docTo spec) return GTypeTo API docTo spec;

290.        --  Return the parent type of Typ (eg if Typ is associated with a Gtk

291.        --  widget, it returns the typ of its parent).

293.        function FundamentalTo API docTo body (Typ : GTypeTo API docTo spec) return GTypeTo API docTo spec;

294.        --  Return the fundamental type for Type.  In gtk+, the types are organized

295.        --  into several hierarchies, similar to what is done for widgets.

296.        --  All of these hierarchies are based on one of the fundamental types

297.        --  defined below.

298.        --  This function returns that fundamental type.

299.        --

300.        --  For instance, each enumeration type in gtk+ has its own GType.

301.        --  However, Fundamental will return GType_Enum in all of these cases.

303.        function Type_NameTo API docTo body (Type_Num : GTypeTo API docTo spec) return String;

304.        --  Return the name of the type (enumeration,...) associated with Typ.

305.        --  If Fundamental (Typ) return GType_Enum, this returns the name of

306.        --  the enumeration type that Typ represents.

307.        --  This might be useful in debug messages.

309.        function Type_From_NameTo API docTo body (Name : String) return GTypeTo API docTo spec;

310.        --  Convert a string to the matching type.

311.        --  Name should be the C GObject name rather than the Ada name: thus,

312.        --  use names such as GtkScrollbar or GtkButton for widgets.

314.        function Get_QdataTo API docTo body (Typ : GTypeTo API docTo spec; Quark : GQuarkTo API docTo spec) return Glib.C_ProxyTo API docTo spec;

315.        --  Return the user data set for Typ

317.        procedure Set_QdataTo API docTo body

318.          (Typ     : GTypeTo API docTo spec;

319.           Quark   : GQuarkTo API docTo spec;

320.           Data    : Glib.C_ProxyTo API docTo spec);

321.        --  Associate some named data with Typ.

323.        --  The list of fundamental types defined in Glib. As opposed to most other

324.        --  types (for instance the ones used for widgets), the types have static

325.        --  values, always the same.

327.        GType_Fundamental_Shift : constant Integer := 2;

329.        GType_Invalid   : constant GTypeTo API docTo spec := 0 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

330.        GType_None      : constant GTypeTo API docTo spec := 1 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

331.        GType_Interface : constant GTypeTo API docTo spec := 2 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

333.        GType_Char      : constant GTypeTo API docTo spec := 3 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

334.        GType_Uchar     : constant GTypeTo API docTo spec := 4 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

335.        GType_Boolean   : constant GTypeTo API docTo spec := 5 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

336.        GType_Int       : constant GTypeTo API docTo spec := 6 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

337.        GType_Uint      : constant GTypeTo API docTo spec := 7 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

338.        GType_Long      : constant GTypeTo API docTo spec := 8 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

339.        GType_Ulong     : constant GTypeTo API docTo spec := 9 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

340.        GType_Int64     : constant GTypeTo API docTo spec := 10 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

341.        GType_UInt64    : constant GTypeTo API docTo spec := 11 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

342.        GType_Enum      : constant GTypeTo API docTo spec := 12 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

343.        GType_Flags     : constant GTypeTo API docTo spec := 13 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

344.        GType_Float     : constant GTypeTo API docTo spec := 14 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

345.        GType_Double    : constant GTypeTo API docTo spec := 15 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

346.        GType_String    : constant GTypeTo API docTo spec := 16 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

347.        --  Null terminated string.

349.        GType_Pointer   : constant GTypeTo API docTo spec := 17 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

350.        --  A general pointer type.

352.        GType_Param     : constant GTypeTo API docTo spec := 19 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

353.        GType_Object    : constant GTypeTo API docTo spec := 20 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

354.        --  One of the widgets/objects

356.        -----------------

357.        -- Boxed types --

358.        -----------------

359.        --  Boxed types are a convenient way to encapsulate Ada types through a C

360.        --  layer. An initialization and a finalization function can be provided.

361.        --  The most frequent usage of such types is in argument to signals and

362.        --  handlers (See the functions in Glib.Values), or to store such types

363.        --  in a Gtk_Tree_Model. This allows you for instance to store reference

364.        --  counted types where you want to be able to control what should happen

365.        --  when the cell is removed from the tree.

366.        --

367.        --  See an example with the subprogram Glib.Values.Set_Boxed

369.        GType_Boxed     : constant GTypeTo API docTo spec := 18 * (2 ** GType_Fundamental_ShiftTo API docTo spec);

370.        --  The base type for all boxed types. In tree models, you should use the

371.        --  actual type returned by Boxed_Type_Register_Static.

373.        type Boxed_Copy is access

374.           function (Boxed : System.Address) return System.Address;

375.        pragma Convention (CTo API docTo spec, Boxed_CopyTo API docTo spec);

376.        type Boxed_Free is access procedure (Boxed : System.Address);

377.        pragma Convention (CTo API docTo spec, Boxed_FreeTo API docTo spec);

379.        function Boxed_Type_Register_StaticTo API docTo body

380.          (Name : String;

381.           Copy : Boxed_CopyTo API docTo spec;

382.           Free : Boxed_FreeTo API docTo spec) return GTypeTo API docTo spec;

383.        --  Create a new boxed type

385.     private

386.        type C_DummyTo API docTo spec is record

387.           Dummy1 : System.Address;

388.        end record;

389.        pragma Convention (CTo API docTo spec, C_DummyTo API docTo specTo body);

390.        --  This array can contain anything, since it is never used on the Ada side

391.        --  anyway. Pretend it contains an address so that the compiler a

392.        --  reasonable default alignment, compatible with most types.

394.        type GType_ClassTo API docTo spec is new System.Address;

396.        type PropertyTo API docTo spec is new String;

398.        type Signal_IdTo API docTo spec is new GuintTo API docTo spec;

399.        Invalid_Signal_IdTo API docTo spec : constant Signal_IdTo API docTo spec := -1;

400.        Null_Signal_IdTo API docTo spec : constant Signal_IdTo API docTo spec := 0;

402.        pragma Import (CTo API docTo spec, FundamentalTo API docTo spec, "ada_gtype_fundamental");

403.        pragma Import (CTo API docTo spec, ParentTo API docTo spec, "g_type_parent");

404.        pragma Import (CTo API docTo spec, Get_QdataTo API docTo spec, "g_type_get_qdata");

405.        pragma Import (CTo API docTo spec, Set_QdataTo API docTo spec, "g_type_set_qdata");

406.        pragma Inline (BuildTo API docTo specTo body);

408.     end GlibTo API docTo specTo body;