## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2001-2007, 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.     --  This package implements a specific model to store your data in. It is

31.     --  basically similar to a small database, in that each field can contain any

32.     --  number of columns.

33.     --

34.     --  Each column can contain a different type of data, specified when the model

35.     --  is created.

36.     --

37.     --  Adding new values in the model is done as in the example at the end.

38.     --  </description>

39.     --  <c_version>2.8.17</c_version>

40.     --  <group>Trees and Lists</group>

42.     with Glib.TypesTo API docTo specTo body;

43.     with Glib.ValuesTo API docTo specTo body; use Glib.ValuesTo API docTo specTo body;

44.     with GtkTo API docTo spec;

45.     with Gtk.Tree_DndTo API docTo specTo body;

46.     with Gtk.Tree_ModelTo API docTo specTo body;

47.     with Gtk.Tree_SortableTo API docTo specTo body;

49.     package Gtk.Tree_StoreTo API docTo specTo body is

51.        type Gtk_Tree_Store_Record is

52.          new Gtk.Tree_Model.Gtk_Tree_Model_RecordTo API docTo specTo body with null record;

53.        type Gtk_Tree_Store is access all Gtk_Tree_Store_RecordTo API docTo spec'Class;

55.        procedure Gtk_NewTo API docTo body

56.          (Tree_Store : out Gtk_Tree_StoreTo API docTo spec;

57.           Types      : GType_ArrayTo API docTo spec);

58.        --  Create a new tree store using Types to fill the columns.

60.        procedure InitializeTo API docTo body

61.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec'Class;

62.           Types      : GType_ArrayTo API docTo spec);

63.        --  Internal initialization function.

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

66.        function Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

67.        --  Return the internal value associated with this widget.

69.        procedure Set_Column_TypesTo API docTo body

70.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

71.           Types      : GType_ArrayTo API docTo spec);

72.        --  This function is meant primarily for GObjects that inherit from

73.        --  Gtk_Tree_Store, and should only be used when constructing a new

74.        --  Gtk_Tree_Store. It will not function after a row has been added, or a

75.        --  method on the Gtk_Tree_Model interface is called.

77.        procedure Set_ValueTo API docTo body

78.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

79.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

80.           Column     : GintTo API docTo spec;

81.           ValueTo API docTo body      : Glib.Values.GValueTo API docTo specTo body);

82.        --  Set a new value in the model. The value is added in the column Column,

83.        --  and in the line Iter.

84.        --  This is the most general of the Set procedures, since it allows you to

85.        --  control what should be done when the cell is freed (useful for instance

86.        --  for reference-controlled types). In particular, you would create a

87.        --  GValue of a special type derived from Boxed (see Glib.Value.Set_Boxed).

88.        --

89.        --  The type of the column must be of the type stored in the GValue itself.

90.        --  Referencing the example given for Set_Boxed, this would be the value

91.        --  in "Typ".

93.        generic

94.           type Data_Type is private;

95.        package Generic_SetTo API docTo body is

96.           type Data_Type_Access is access all Data_TypeTo API docTo spec;

98.           procedure SetTo API docTo body

99.             (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec'Class;

100.              IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

101.              Column     : GintTo API docTo spec;

102.              Value      : Data_Type_AccessTo API docTo spec);

103.           --  Generic procedure used to store access objects in the model.

104.           --  For GObject and all of its descendents (including all widgets),

105.           --  you should use the Set procedure below that takes a GObject as

106.           --  parameter.

107.           --

108.           --  Please see the example at the end for more information on how to

109.           --  create your own Set procedures adapted to your model. Also consider

110.           --  using Set_Value for complex cases

112.           function GetTo API docTo body

113.             (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec'Class;

114.              IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

115.              Column     : GintTo API docTo spec) return Data_Type_AccessTo API docTo spec;

116.           --  Generic procedure used to get access objects back from the model.

117.           --  For GObject and all of its descendents (including all widgets),

118.           --  you should use the Get_Object function defined in Gtk-Tree_Model

119.           --  that returns a GObject.

121.        end Generic_SetTo API docTo specTo body;

123.        procedure SetTo API docTo body

124.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

125.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

126.           Column     : GintTo API docTo spec;

127.           Value      : UTF8_StringTo API docTo spec);

128.        --  Same as Generic_Set, but tailored to use with a string.

130.        procedure SetTo API docTo body

131.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

132.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

133.           Column     : GintTo API docTo spec;

134.           Value      : Boolean);

135.        --  Same as Generic_Set, but tailored to use with a boolean.

137.        procedure SetTo API docTo body

138.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

139.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

140.           Column     : GintTo API docTo spec;

141.           Value      : GintTo API docTo spec);

142.        --  Same as Generic_Set, but tailored to use with an integer.

144.        procedure SetTo API docTo body

145.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

146.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

147.           Column     : GintTo API docTo spec;

148.           Value      : Glib.C_ProxyTo API docTo spec);

149.        --  Same as Generic_Set, but tailored for Gdk types.

151.        procedure SetTo API docTo body

152.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

153.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

154.           Column     : GintTo API docTo spec;

155.           Address    : System.Address);

156.        --  Same as Generic_Set, for a generic address

158.        procedure SetTo API docTo body

159.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

160.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

161.           Column     : GintTo API docTo spec;

162.           Value      : Glib.Object.GObjectTo API docTo spec);

163.        --  Same as Generic_Set, but tailored to objects/widgets.

165.        procedure RemoveTo API docTo body

166.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

167.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

168.        --  Remove Iter from Tree_Store.

169.        --  After being removed, Iter is set to Null_Iter.

171.        procedure InsertTo API docTo body

172.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

173.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

174.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

175.           Position   : GintTo API docTo spec);

176.        --  Create a new row at Position.

177.        --  If parent is non-null, then the row will be made a child of Parent.

178.        --  Otherwise, the row will be created at the toplevel. If Position is

179.        --  larger than the number of rows at that level, then the new row will be

180.        --  inserted to the end of the list. Iter will be changed to point to this

181.        --  new row. The row will be empty before this function is called. To fill

182.        --  in values, you need to call Set_Value.

184.        procedure Insert_BeforeTo API docTo body

185.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

186.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

187.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

188.           SiblingTo API docTo body    : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

189.        --  Insert a new row before Sibling.

190.        --  If Sibling is Null_Iter, then the row will be appended to the beginning

191.        --  of the Parent's children. If Parent and Sibling are Null_Iter, then the

192.        --  row will be appended to the toplevel. If both Sibling and Parent are

193.        --  set, then Parent must be the parent of Sibling. When Sibling is set,

194.        --  Parent is optional. Iter will be changed to point to this new row. The

195.        --  row will be empty after this function is called. To fill in values, you

196.        --  need to call Set_Value.

198.        procedure Insert_AfterTo API docTo body

199.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

200.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

201.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

202.           SiblingTo API docTo body    : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

203.        --  Insert a new row after Sibling.

204.        --  If Sibling is Null_Iter, then the row will be prepended to the beginning

205.        --  of the Parent's children. If Parent and Sibling are Null_Iter, then the

206.        --  row will be prepended to the toplevel. If both Sibling and Parent are

207.        --  set, then Parent must be the parent of Sibling. When Sibling is set,

208.        --  Parent is optional. Iter will be changed to point to this new row. The

209.        --  row will be empty after this function is called. To fill in values, you

210.        --  need to call Set_Value.

212.        procedure PrependTo API docTo body

213.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

214.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

215.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

216.        --  Prepend a new row to Tree_Store.

217.        --  If Parent is non-null, then it will prepend the new row before the first

218.        --  child of Parent, otherwise it will prepend a row to the top level. Iter

219.        --  will be changed to point to this new row. The row will be empty after

220.        --  this function is called. To fill in values, you need to call Set_Value.

221.        --  The efficiency of this procedure is O(N).

223.        procedure AppendTo API docTo body

224.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

225.           IterTo API docTo body       : in out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

226.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

227.        --  Append a new row to Tree_Store.

228.        --  If Parent is non-null, then it will append the new row after the last

229.        --  child of Parent, otherwise it will append a row to the top level. Iter

230.        --  will be changed to point to this new row. The row will be empty after

231.        --  this function is called. To fill in values, you need to call Set_Value.

232.        --  The efficiency of this procedure is O(N^2).

234.        function Is_AncestorTo API docTo body

235.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

236.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

237.           DescendantTo API docTo body : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body) return Boolean;

238.        --  Return True if Iter is an ancestor of Descendant.

239.        --  That is, Iter is the parent (or grandparent or great-grandparent) of

240.        --  Descendant.

242.        function Iter_DepthTo API docTo body

243.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

244.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body) return GintTo API docTo spec;

245.        --  Returns the depth of Iter.

246.        --  This will be 0 for anything on the root level, 1 for anything down a

247.        --  level, etc.

249.        function Iter_Is_ValidTo API docTo body

250.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

251.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body)

252.           return Boolean;

253.        --  WARNING: This function is slow. Only use it for debugging and/or testing

254.        --  purposes.

255.        --  Checks if the given iter is a valid iter for Tree_Store.

257.        procedure Move_AfterTo API docTo body

258.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

259.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

260.           PositionTo API docTo body   : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

261.        --  Moves the row pointed to by Iter to the position after Position. Iter

262.        --  and Position should be in the same level. Note that this function only

263.        --  works with unsorted stores. If Position is Null_Iter, Iter will be

264.        --  moved to the start of the level.

266.        procedure Move_BeforeTo API docTo body

267.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

268.           IterTo API docTo body       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

269.           PositionTo API docTo body   : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

270.        --  Moves the row pointed to by Iter to the position before Position. Iter

271.        --  and Position should be in the same level. Note that this function only

272.        --  works with unsorted stores. If Position is Null_Iter, Iter will be

274.        procedure ClearTo API docTo body (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec);

275.        --  Removes all rows from Tree_Store

277.        procedure ReorderTo API docTo body

278.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

279.           ParentTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

280.           New_Order  : Glib.Gint_ArrayTo API docTo spec);

281.        --  Reorders the children of Parent to follow the order indicated by

282.        --  New_order. Note that this function only works with unsorted stores. New

283.        --  order is an array of integers mapping the new position of each child to

284.        --  its old position before the re-ordering,

285.        --  i.e. New_order[newpos] = oldpos

286.        --  If Parent is Null_Iter, it also reorders the root nodes

288.        procedure SwapTo API docTo body

289.          (Tree_Store : access Gtk_Tree_Store_RecordTo API docTo spec;

290.           ATo API docTo body          : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

291.           BTo API docTo body          : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

292.        --  Swaps the rows pointed to by A and B (in the same level). Note that this

293.        --  function only works with unsorted stores.

295.        ---------------------------

296.        -- Sorting Freeze / Thaw --

297.        ---------------------------

299.        --  Note: the following two functions are not part of the Gtk+ API, but

300.        --  are provided by GtkAda.

302.        function Freeze_SortTo API docTo body

303.          (Tree : access Gtk.Tree_Store.Gtk_Tree_Store_RecordTo API docTo spec'Class)

304.           return GintTo API docTo spec;

305.        --  Freeze the sorting in the tree view, and returns the current

306.        --  sort_column_id, which should be used when thawing. (See Thaw_Sort)

308.        procedure Thaw_SortTo API docTo body

309.          (Tree      : access Gtk.Tree_Store.Gtk_Tree_Store_RecordTo API docTo spec'Class;

310.           Column_Id : GintTo API docTo spec);

311.        --  Thaw a frozen tree_view. Column_Id should be the value returned by

312.        --  the corresponding call to Freeze_Sort.

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

315.        -- Interfaces --

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

317.        --  This class implements several interfaces. See Glib.Types

318.        --

319.        --  - "Gtk_Tree_Sortable"

320.        --    This interface allows you to specify your own sort function

321.        --

322.        --  - "Gtk_Tree_Drag_Source"

323.        --    This interface allows this widget to act as a dnd source

324.        --

325.        --  - "Gtk_Tree_Drag_Dest"

326.        --    This interface allows this widget to act as a dnd destination

328.        package Implements_Tree_Sortable is new Glib.Types.ImplementsTo API docTo specTo body

329.          (Gtk.Tree_Sortable.Gtk_Tree_SortableTo API docTo spec,

330.           Gtk_Tree_Store_RecordTo API docTo spec,

331.           Gtk_Tree_StoreTo API docTo spec);

332.        function "+"

333.          (Model : access Gtk_Tree_Store_RecordTo API docTo spec'Class)

334.           return Gtk.Tree_Sortable.Gtk_Tree_SortableTo API docTo spec

335.           renames Implements_Tree_Sortable.To_InterfaceTo API docTo specTo body;

336.        function "-"

337.          (Sortable : Gtk.Tree_Sortable.Gtk_Tree_SortableTo API docTo spec)

338.           return Gtk_Tree_StoreTo API docTo spec

339.           renames Implements_Tree_Sortable.To_ObjectTo API docTo specTo body;

340.        --  Converts to and from the Gtk_Tree_Sortable interface

342.        package Implements_Drag_Source is new Glib.Types.ImplementsTo API docTo specTo body

343.          (Gtk.Tree_Dnd.Gtk_Tree_Drag_SourceTo API docTo spec,

344.           Gtk_Tree_Store_RecordTo API docTo spec,

345.           Gtk_Tree_StoreTo API docTo spec);

346.        function "+"

347.          (Model : access Gtk_Tree_Store_RecordTo API docTo spec'Class)

348.           return Gtk.Tree_Dnd.Gtk_Tree_Drag_SourceTo API docTo spec

349.           renames Implements_Drag_Source.To_InterfaceTo API docTo specTo body;

350.        function "-"

351.          (Drag_Source : Gtk.Tree_Dnd.Gtk_Tree_Drag_SourceTo API docTo spec)

352.           return Gtk_Tree_StoreTo API docTo spec

353.           renames Implements_Drag_Source.To_ObjectTo API docTo specTo body;

354.        --  Converts to and from the Gtk_Tree_Drag_Source interface

356.        package Implements_Drag_Dest is new Glib.Types.ImplementsTo API docTo specTo body

357.          (Gtk.Tree_Dnd.Gtk_Tree_Drag_DestTo API docTo spec,

358.           Gtk_Tree_Store_RecordTo API docTo spec,

359.           Gtk_Tree_StoreTo API docTo spec);

360.        function "+"

361.          (Model : access Gtk_Tree_Store_RecordTo API docTo spec'Class)

362.           return Gtk.Tree_Dnd.Gtk_Tree_Drag_DestTo API docTo spec

363.           renames Implements_Drag_Dest.To_InterfaceTo API docTo specTo body;

364.        function "-"

365.          (Drag_Dest : Gtk.Tree_Dnd.Gtk_Tree_Drag_DestTo API docTo spec)

366.           return Gtk_Tree_StoreTo API docTo spec

367.           renames Implements_Drag_Dest.To_ObjectTo API docTo specTo body;

368.        --  Converts to and from the Gtk_Tree_Drag_Source interface

370.     private

371.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_tree_store_get_type");

372.     end Gtk.Tree_StoreTo API docTo specTo body;

374.     --  <example>

375.     --  Adding a new line in the model:

376.     --

377.     --  declare

378.     --     Iter  : Gtk_Text_Iter;

379.     --     Value : Glib.Values.GValue;

380.     --  begin

381.     --     Append (Model, Iter, Null_Iter);

382.     --

383.     --     --  First method:

384.     --

385.     --     Init (Value, GType_String);

386.     --     Set_String (Value, "foo");

387.     --     Set_Value (Model, Iter, 0, Value);

388.     --     Unref (Value);

389.     --

390.     --     --  Second method:

391.     --

392.     --     Set (Model, Iter, 0, "foo");

393.     --  end;

394.     --

395.     --  </example>

397.     --  <example>

398.     --  Defining your own Set function for your model: This can be done by directly

399.     --  importing the C function, with the appropriate number of parameters.

400.     --  Remember that you are passing data directly to C, thus you need to end

401.     --  strings with ASCII.NUL

402.     --

403.     --  procedure My_Set

404.     --     (Tree_Store : access Gtk_Tree_Store_Record'Class;

405.     --      Iter       : Gtk.Tree_Model.Gtk_Tree_Iter;

406.     --      Column1 : Gint; Value1 : UTF8_String;

407.     --      Column2 : Gint; Value2 : Boolean)

408.     --  is

409.     --      procedure Set_String

410.     --        (Tree : System.Address;

411.     --         Iter : Gtk.Tree_Model.Gtk_Tree_Iter;

412.     --         Column : Gint; Value : UTF8_String);

413.     --      pragma Import (C, Set_String, "ada_gtk_tree_store_set_ptr");

414.     --

415.     --      procedure Set_Int

416.     --        (Tree : System.Address;

417.     --         Iter : Gtk.Tree_Model.Gtk_Tree_Iter;

418.     --         Column : Gint; Value : Gint);

419.     --      pragma Import (C, Internal, "ada_gtk_tree_store_set_int");

420.     --   begin

421.     --      Internal

422.     --        (Get_Object (Tree_Store), Iter, Column1, Value1 & ASCII.NUL);

423.     --      Internal

424.     --        (Get_Object (Tree_Store), Iter, Column2, Boolean'Pos (Value2));

425.     --   end Set;

426.     --

427.     --  </example>

429.     --  No binding: gtk_tree_store_new

430.     --  No binding: gtk_tree_store_set

431.     --  No binding: gtk_tree_store_set_valist