## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                   Copyright (C) 2001-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 minimal binding to the GObject type in Glib.

32.     --  See Glib.Properties for information on how to manipulate properties

33.     --

34.     --  </description>

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

37.     with Gtkada.TypesTo API docTo specTo body;

38.     with Glib.GSlistTo API docTo specTo body;

39.     with Glib.GlistTo API docTo specTo body;

40.     pragma Elaborate_All (Glib.GSlistTo API docTo specTo body);

41.     pragma Elaborate_All (Glib.GlistTo API docTo specTo body);

43.     package Glib.ObjectTo API docTo specTo body is

45.        type GObject_RecordTo API docTo body is tagged private;

46.        type GObject is access all GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

47.        --  The base type for Glib/Gdk/Gtk objects. It basically gives access

48.        --  to an underlying C object. This is not a controlled type for

49.        --  efficiency reasons and because glib takes care of the memory

50.        --  management on its own.

52.        function Is_CreatedTo API docTo body (Object : GObject_RecordTo API docTo specTo body'ClassTo API docTo spec) return Boolean;

53.        --  Return True if the associated C object has been created, False if

54.        --  no C object is associated with Object.

55.        --  This is not the same as testing whether an access type (for instance

56.        --  any of the widgets) is "null", since this relates to the underlying

57.        --  C object.

59.        function Get_TypeTo API docTo body (Object : access GObject_RecordTo API docTo specTo body) return GTypeTo API docTo spec;

60.        --  Return the type of Object.

61.        --  This function is mostly used internally, since in Ada you can simply

62.        --  test whether an object belong to a class with a statement like:

63.        --

64.        --     if Object in Gtk_Button_Record'Class then ...

65.        --

66.        --  which is easier.

68.        ----------------

69.        -- Life cycle --

70.        ----------------

72.        procedure G_NewTo API docTo body (Object : out GObjectTo API docTo spec);

73.        --  Create a new GObject.

74.        --  This is only required when you want to create an Ada tagged type to

75.        --  which you can attach new signals. Most of the time, you only need to

76.        --  directly create the appropriate Gtk Widget by calling the correct

77.        --  Gtk_New procedure.

79.        procedure InitializeTo API docTo body (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec);

80.        --  Internal initialization function.

81.        --  See the section "Creating your own widgets" in the documentation.

83.        procedure RefTo API docTo body (Object : access GObject_RecordTo API docTo specTo body);

84.        --  Increment the reference counter for Object. See Unref below.

85.        --  Since an object is not deleted while its reference count is not null,

86.        --  this is a way to keep an object in memory, in particular when you

87.        --  want to temporarily remove a widget from its parent.

89.        procedure UnrefTo API docTo body (Object : access GObject_RecordTo API docTo specTo body);

90.        --  Decrement the reference counter for Object. When this reaches 0, the

91.        --  object is effectively destroy, all the callbacks associated with it are

92.        --  disconnected.

94.        type Weak_Notify is access procedure

95.          (Data                 : System.Address;

96.           Where_The_Object_Was : System.Address);

97.        pragma Convention (C, Weak_NotifyTo API docTo spec);

98.        --  Called when Where_The_Object_Was is destroyed (although you can still

99.        --  use this to reset it). Data is the argument passed to Weak_Ref.

100.        --  You should destroy and free the memory occupied by Data

102.        procedure Weak_RefTo API docTo body

103.          (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

104.           Notify : Weak_NotifyTo API docTo spec;

105.           Data   : System.Address := System.Null_Address);

106.        --  This kind of reference doesn't increment the object's reference

107.        --  counting. However, it can and should be used to monitor the object's

108.        --  life cycle, in particular to detect is destruction.

109.        --  When Object is destroyed, calls Notify

111.        procedure Weak_UnrefTo API docTo body

112.          (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

113.           Notify : Weak_NotifyTo API docTo spec;

114.           Data   : System.Address := System.Null_Address);

115.        --  Cancels the settings of Weak_Ref.

117.        procedure DeallocateTo API docTo body (Object : access GObject_RecordTo API docTo specTo body);

118.        --  This operation is used to deallocate Object.

119.        --  The default implementation assumes that the value passed in is an

120.        --  access value created by an allocator of the default pool, i.e. it

121.        --  will assume that an instance of

122.        --  Unchecked_Deallocation (GObject_Record'Class, GObject)

123.        --  can be used to deallocate the designated object.

124.        --  Types derived of GObject_Record can override this operation in order

125.        --  to cope with objects allocated on other pools or even objects allocated

126.        --  on the stack.

127.        --  This design is limited to support only one allocation strategy for each

128.        --  class, as the class tag is used to identify the applicable strategy.

130.        procedure Ref_SinkTo API docTo body (Object : access GObject_RecordTo API docTo specTo body);

131.        --  Increase the reference count of Object, and possibly remove the

132.        --  floating reference, if Object has a floating reference.

133.        --  In other words, if the object is floating, then this call "assumes

134.        --  ownership" of the floating reference, converting it to a normal

135.        --  reference by clearing the floating flag while leaving the reference

136.        --  count unchanged.  If the object is not floating, then this call

137.        --  adds a new normal reference increasing the reference count by one.

139.        ------------------------

140.        -- Interfacing with C --

141.        ------------------------

142.        --  The following functions are made public so that one can easily create

143.        --  new objects outside the Glib or Gtk package hierarchy.

144.        --  Only experienced users should make use of these functions.

146.        function Get_ObjectTo API docTo body

147.          (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec) return System.Address;

148.        --  Access the underlying C pointer.

150.        function Get_Object_Or_NullTo API docTo body (Object : GObjectTo API docTo spec) return System.Address;

151.        --  Same as above, but passing "null" is valid.

153.        procedure Set_ObjectTo API docTo body

154.          (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

155.           Value  : System.Address);

156.        --  Modify the underlying C pointer.

158.        function Get_User_DataTo API docTo body

159.          (Obj  : System.Address;

160.           Stub : GObject_RecordTo API docTo specTo body'ClassTo API docTo spec) return GObjectTo API docTo spec;

161.        --  Return the Ada object matching the C object Obj. If Obj was created

162.        --  explicitely from GtkAda, this will be the exact same widget. If Obj was

163.        --  created implicitely by gtk+ (buttons in complex windows,...), a new Ada

164.        --  object of type Stub will be created.

166.        function Get_User_Data_FastTo API docTo body

167.          (Obj  : System.Address;

168.           Stub : GObject_RecordTo API docTo specTo body'ClassTo API docTo spec) return GObjectTo API docTo spec;

169.        --  Same as Get_User_Data, but does not try to guess the type of Obj,

170.        --  always default to Stub if Obj is unknown to GtkAda.

172.        function Unchecked_CastTo API docTo body

173.          (Obj  : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

174.           Stub : GObject_RecordTo API docTo specTo body'ClassTo API docTo spec) return GObjectTo API docTo spec;

175.        --  Cast Obj in an object of tag Stub'Class.

176.        --  Return the resulting object and free the memory pointed by Obj.

178.        -------------

179.        -- Signals --

180.        -------------

181.        --  Any child of GObject can be associated with any number of signals. The

182.        --  mechanism for signals is fully generic, and any number of arguments can

183.        --  be associated with signals.

184.        --  See the function Initialize_Class_Record for more information on how

185.        --  to create new signals for your own new widgets.

186.        --  The subprograms below are provided for introspection: they make it

187.        --  possible to query the list of signals defined for a specific widget,

188.        --  as well as their parameters and return types.

190.        type Signal_Id_Array is array (GuintTo API docTo spec range <>) of Glib.Signal_IdTo API docTo spec;

192.        type Signal_QueryTo API docTo body is private;

194.        function LookupTo API docTo body

195.          (Object : Glib.GTypeTo API docTo spec; Signal : String) return Glib.Signal_IdTo API docTo spec;

196.        --  Returns the signal Id associated with a specific Object/Signal pair.

197.        --  Null_Signal_Id is returned if no such signal exists for Object.

198.        --  You can then use the Query procedure to get more information on the

199.        --  signal.

201.        function List_IdsTo API docTo body (Typ : Glib.GTypeTo API docTo spec) return Signal_Id_ArrayTo API docTo spec;

202.        --  Return the list of signals defined for Typ. You can get more information

203.        --  on each of this signals by using the Query function below.

204.        --  See also the function Get_Type above to convert from an object instance

205.        --  to its type. Using a GType as the parameter makes it easier to find the

206.        --  signals for a widget and its ancestors (using Glib.Parent).

208.        procedure QueryTo API docTo body (Id : Glib.Signal_IdTo API docTo spec; Result : out Signal_QueryTo API docTo specTo body);

209.        --  Return the description associated with the signal Id. You can get the

210.        --  various fields from Query with one of the functions below.

211.        --  Result is undefined if Id is Invalid_Signal_Id or Null_Signal_Id

213.        function IdTo API docTo body (Q : Signal_QueryTo API docTo specTo body) return Glib.Signal_IdTo API docTo spec;

214.        --  Return the signal Id. Each Id is specific to a widget/signal name pair.

215.        --  These Ids can then be used to temporarily block a signal for instance,

216.        --  through the subprograms in Gtk.Handlers.

218.        function Signal_NameTo API docTo body (QTo API docTo body : Signal_QueryTo API docTo specTo body) return Glib.Signal_NameTo API docTo spec;

219.        --  Return the name of the signal, as should be used in a call to Connect.

221.        function Return_TypeTo API docTo body (Q : Signal_QueryTo API docTo specTo body) return Glib.GTypeTo API docTo spec;

222.        --  Return the type of object returned by the handlers for this signal.

224.        function ParamsTo API docTo body (QTo API docTo body : Signal_QueryTo API docTo specTo body) return GType_ArrayTo API docTo spec;

225.        --  Return the list of parameters for the handlers for this signal

227.        --------------------------

228.        -- Creating new widgets --

229.        --------------------------

230.        --  These types and functions are used only when creating new widget types

231.        --  directly in Ada. These functions initialize the classes so that they are

232.        --  correctly recognized by gtk+ itself

233.        --  See the GtkAda user's guide for more information on how to create your

234.        --  own widget types in Ada.

236.        type Interface_Vtable is private;

237.        --  The virtual table of an interface (see Glib.Types). This is only useful

238.        --  when doing introspection.

240.        type GObject_Class is new GType_ClassTo API docTo spec;

241.        Uninitialized_Class : constant GObject_ClassTo API docTo spec;

242.        --  This type encloses all the informations related to a specific type of

243.        --  object or widget. All instances of such an object have a pointer to this

244.        --  structure, that includes the definition of all the signals that exist

245.        --  for a given object, all its properties,...

247.        type Signal_Parameter_Types is

248.          array (Natural range <>, Natural range <>) of GTypeTo API docTo spec;

249.        --  The description of the parameters for each event. These are the

250.        --  parameters that the application must provide when emitting the

251.        --  signal. The user can of course add his own parameters when connecting

252.        --  the signal in his application, through the use of

253.        --  Gtk.Handlers.User_Callback.

254.        --

255.        --  Each event defined with Initialize_Class_Record below should have an

256.        --  entry in this table. If Gtk_Type_None is found in the table, it is

257.        --  ignored. For instance, a Signal_Parameter_Type like:

258.        --    (1 => (1 => Gdk_Type_Gdk_Event, 2 => GType_None),

259.        --     2 => (1 => GType_Int,          2 => GType_Int));

260.        --  defines two signals, the first with a single Gdk_Event parameter, the

261.        --  second with two ints parameters.

263.        Null_Parameter_Types : constant Signal_Parameter_TypesTo API docTo spec (1 .. 0, 1 .. 0) :=

264.          (others => (others => GType_NoneTo API docTo spec));

265.        --  An empty array, used as a default parameter in Initialize_Class_Record.

267.        procedure Initialize_Class_RecordTo API docTo body

268.          (Object       : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

269.           Signals      : Gtkada.Types.Chars_Ptr_ArrayTo API docTo spec;

270.           Class_Record : in out GObject_ClassTo API docTo spec;

271.           Type_Name    : String;

272.           Parameters   : Signal_Parameter_TypesTo API docTo spec := Null_Parameter_TypesTo API docTo spec);

273.        --  Create the class record for a new object type.

274.        --  It is associated with Signals'Length new signals. A pointer to the

275.        --  newly created structure is also returned in Class_Record.

276.        --  If Class_Record /= System.Null_Address, no memory allocation is

277.        --  performed, we just reuse it. As a result, each instantiation of an

278.        --  object will share the same GObject_Class, exactly as is done for gtk+.

279.        --

280.        --  Note: The underlying C object must already have been initialized

281.        --  by a call to its parent's Initialize function.

282.        --  Parameters'Length should be the same as Signals'Length, or the result

283.        --  is undefined.

284.        --  As a special case, if Parameters has its default value, all signals are

285.        --  created with no argument. This is done for backward compatibility

286.        --  mainly, and you should instead give it an explicit value.

287.        --  Type_Name should be a unique name identifying the name of the new type.

288.        --

289.        --  Only the signals with no parameter can be connected from C code.

290.        --  However, any signal can be connected from Ada. This is due to the way

291.        --  we define default marshallers for the signals.

293.        function Type_From_ClassTo API docTo body (Class_Record : GObject_ClassTo API docTo spec) return GTypeTo API docTo spec;

294.        --  Return the internal gtk+ type that describes the newly created

295.        --  Class_Record.

296.        --  See the function Glib.Types.Class_Peek for the opposite function

297.        --  converting from a GType to a GObject_Class.

299.        ------------------------------

300.        -- Properties introspection --

301.        ------------------------------

302.        --  See glib.ads for more information on properties

304.        function Interface_List_PropertiesTo API docTo body

305.          (Vtable : Interface_VtableTo API docTo spec) return Glib.Param_Spec_ArrayTo API docTo spec;

306.        --  Return the list of properties of an interface (see also Glib.Properties)

307.        --  from a Vtable from Default_Interface_Peek).

308.        --  See also Class_List_Properties for a similar function for objects.

310.        function Class_List_PropertiesTo API docTo body

311.          (Class : GObject_ClassTo API docTo spec) return Glib.Param_Spec_ArrayTo API docTo spec;

312.        --  Return the list of all properties of the class.

314.        -------------

315.        -- Signals --

316.        -------------

317.        --  ??? This section is incomplete.

319.        --  <signals>

320.        --  The following new signals are defined for this object:

321.        --

322.        --  - "notify"

323.        --    procedure Handler

324.        --      (Object : access GObject_Record'Class; Name : String);

325.        --

326.        --    Emitted when the property Name has been modified

327.        --  </signals>

329.        procedure NotifyTo API docTo body

330.          (Object        : access GObject_RecordTo API docTo specTo body;

331.           Property_Name : String);

332.        --  Emits the "notify" signal, to signal every listener that the property

333.        --  has been changed.

335.        ---------------

336.        -- User_Data --

337.        ---------------

338.        --  This package allow you to associate your own Data to the C widgets. No

339.        --  type verification is made to check if you are using the correct

340.        --  matching Get function. This is your own responsability.

341.        --

342.        --  We recommend using this package only if you want your data to be

343.        --  available from your own C code. If you just want to access it from Ada,

344.        --  you should consider creating a new tagged type instead, that extends

345.        --  either GObject_Record or the specific widget type you need.

347.        --  <doc_ignore>

349.        generic

350.           type Data_Type (<>) is private;

351.        package User_DataTo API docTo body is

352.           type On_Destroyed_Callback is access procedure (Data : Data_TypeTo API docTo spec);

353.           --  On_Destroyed is called when the data is overriden in the object, by

354.           --  an other object with the same ID, or when the object itself is

355.           --  destroyed

357.           function GetTo API docTo body

358.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

359.              Id     : String := "user_data") return Data_TypeTo API docTo spec;

360.           --  Get the information associated with the key ID.

361.           --  Raise Gtkada.Types.Data_Error if there is none.

363.           function GetTo API docTo body

364.             (Object  : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

365.              Id      : String := "user_data";

366.              Default : Data_TypeTo API docTo spec) return Data_TypeTo API docTo spec;

367.           --  Get the information associated with the key ID.

368.           --  Return Default instead of raising an exception if there is no such

369.           --  user data

371.           procedure SetTo API docTo body

372.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

373.              Data   : Data_TypeTo API docTo spec;

374.              Id     : String := "user_data";

375.              On_Destroyed : On_Destroyed_CallbackTo API docTo spec := null);

376.           --  Associate some new user data with the object.

377.           --  The strings starting with "gtkada_" are reserved for GtkAda's

378.           --  internal use, please avoid using them.

380.           procedure RemoveTo API docTo body

381.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec; Id : String := "user_data");

382.           --  Remove some data from the object

384.           function GetTo API docTo body

385.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

386.              Id     : Glib.GQuarkTo API docTo spec) return Data_TypeTo API docTo spec;

387.           function GetTo API docTo body

388.             (Object  : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

389.              Id      : Glib.GQuarkTo API docTo spec;

390.              Default : Data_TypeTo API docTo spec) return Data_TypeTo API docTo spec;

391.           --  Same function as Get above, but uses directly the Quark associated

392.           --  with the string, which speeds up the access time significantly.

394.           procedure SetTo API docTo body

395.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec;

396.              Data   : Data_TypeTo API docTo spec;

397.              Id     : Glib.GQuarkTo API docTo spec;

398.              On_Destroyed : On_Destroyed_CallbackTo API docTo spec := null);

399.           --  Same function as Set above, but uses directly the Quark associated

400.           --  with the string, which speeds up the access time significantly.

402.           procedure RemoveTo API docTo body

403.             (Object : access GObject_RecordTo API docTo specTo body'ClassTo API docTo spec; Id : Glib.GQuarkTo API docTo spec);

404.           --  Same function as Remove above, but uses directly the Quark associated

405.           --  with the string, which speeds up the access time significantly.

407.        private

408.           --  <doc_ignore>

409.           procedure Free_Data (Data : System.Address);

410.           --  Internal procedure used to free user data in the package body

411.           pragma Convention (C, Free_Data);

412.           --  </doc_ignore>

413.        end User_DataTo API docTo specTo body;

415.        --  </doc_ignore>

417.        -----------

418.        -- Lists --

419.        -----------

421.        function ConvertTo API docTo body (W : GObjectTo API docTo spec) return System.Address;

422.        function ConvertTo API docTo body (W : System.Address) return GObjectTo API docTo spec;

424.        package Object_List is new Glib.GSlist.Generic_SListTo API docTo specTo body (GObjectTo API docTo spec);

425.        package Object_Simple_List is new Glib.Glist.Generic_ListTo API docTo specTo body (GObjectTo API docTo spec);

427.     private

429.        type GObject_RecordTo API docTo spec is tagged record

430.           Ptr : System.Address := System.Null_Address;

431.        end record;

433.        type Interface_VtableTo API docTo spec is new Glib.C_ProxyTo API docTo spec;

435.        Uninitialized_ClassTo API docTo spec : constant GObject_ClassTo API docTo spec :=

436.          GObject_ClassTo API docTo spec (System.Null_Address);

438.        type Signal_QueryTo API docTo spec is record

439.           Signal_Id    : GuintTo API docTo spec;

440.           Signal_Name  : System.Address;  --  const gchar*

441.           IType        : GTypeTo API docTo spec;

442.           Signal_Flags : GintTo API docTo spec;            --  enum GSignalFlags

443.           Return_Type  : GTypeTo API docTo spec;

444.           N_Params     : GuintTo API docTo spec;

445.           Param_Types  : System.Address;  --  const gtype*

446.        end record;

447.        pragma Convention (C, Signal_QueryTo API docTo specTo body);

449.        --  <doc_ignore>

451.        --  Note: the following functions and types should only be used

452.        --  for internal usage, not in the user's applications.

453.        --  If you use type inheritance for new widgets, you should not need

454.        --  these functions.

456.        GtkAda_String : constant String := "_GtkAda" & ASCII.NUL;

457.        GtkAda_String_Quark : Glib.GQuarkTo API docTo spec := Glib.Unknown_QuarkTo API docTo spec;

458.        --  The name for the user data that we set in the objects.

459.        --  The Quark version is to speed up the string lookup (this is done

460.        --  only once).

462.        --  </doc_ignore>

464.        pragma Inline (Get_ObjectTo API docTo specTo body);

465.        pragma Inline (Set_ObjectTo API docTo specTo body);

466.        pragma Import (C, Type_From_ClassTo API docTo spec, "ada_type_from_class");

467.        pragma Import (C, QueryTo API docTo spec, "g_signal_query");

468.        pragma Import (C, IdTo API docTo spec, "ada_gsignal_query_id");

469.        pragma Import (C, Return_TypeTo API docTo spec, "ada_gsignal_query_return_type");

470.     end Glib.ObjectTo API docTo specTo body;