## 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-2001 ACT-Europe                 --

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 implements a generic double-linked list.

33.     --  Such lists are used throughout GtkAda to contain lists of widgets

34.     --  (for the children of containers, or for the list of selected widgets

35.     --  in a Gtk_Clist for instance), list of strings (for Gtk_Combo_Box),...

36.     --

37.     --  They provide a common interface to traverse these lists.

38.     --

39.     --  One useful note: you should only Free the lists that you have allocated

40.     --  yourself, and not the lists that are returned by the subprograms in

41.     --  GtkAda and should be left under GtkAda's control.

42.     --

43.     --  See the example below for an example on how to traverse a list.

44.     --

45.     --  Instantiating the package Generic_List requires two functions to convert

46.     --  back and forth between your data type and a System.Address which is the

47.     --  type stored at the C level.

48.     --  Note that the lists used in GtkAda already have associated packages, like

49.     --  Gtk.Enums.Gint_List, Gtk.Enums.String_List or Gtk.Widget.Widget_List.

50.     --

51.     --  </description>

52.     --  <c_version>1.2.6</c_version>

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

55.     with System;

57.     package Glib.GlistTo API docTo specTo body is

59.        generic

60.           --  <doc_ignore>

62.           type Gpointer (<>) is private;

63.           with function Convert (P : GpointerTo API docTo spec) return System.Address is <>;

64.           with function Convert (S : System.Address) return GpointerTo API docTo spec is <>;

66.           --  </doc_ignore>

68.        package Generic_ListTo API docTo body is

70.           type GlistTo API docTo body is private;

71.           --  This type is both a list and an item in the list.

72.           --  Each item points to its successor.

74.           Null_ListTo API docTo body : constant GlistTo API docTo specTo body;

76.           procedure AllocTo API docTo body (ListTo API docTo body : out GlistTo API docTo specTo body);

77.           --  Allocate a new item in the list.

78.           --  This item isn't associated with any data.

79.           --  You probably don't have to use this subprogram, since Append,

80.           --  Insert, Prepend, etc. already handle the allocation for you and

81.           --  give a new value to the item.

83.           procedure AppendTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body; Data : GpointerTo API docTo spec);

84.           --  Add a new item at the end of the list, and stores the new list

85.           --  directly back in List.

86.           --  The complexity of this operation is O(n)

88.           function ConcatTo API docTo body (List1To API docTo body : GlistTo API docTo specTo body; List2To API docTo body : GlistTo API docTo specTo body) return GlistTo API docTo specTo body;

89.           --  Concatenate two lists, and return the result.

90.           --  List2 is added at the end of List1.

91.           --  The complexity is O(n1) (depends on the size of List1).

93.           procedure InsertTo API docTo body

94.             (ListTo API docTo body     : in out GlistTo API docTo specTo body;

95.              Data     : GpointerTo API docTo spec;

96.              Position : GintTo API docTo spec);

97.           --  Insert an item in the middle of a list.

98.           --  If Position is 0, the item is added at the beginning of the list, if

99.           --  it is negative the item is added at the end.

100.           --  The complexity is O(Position).

102.           function FindTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body; Data : GpointerTo API docTo spec) return GlistTo API docTo specTo body;

103.           --  Find a value in the list, and return the first item that contains it.

104.           --  Note that this function will not work if the function Convert does

105.           --  not return the same value for two identical values.

107.           function FirstTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GlistTo API docTo specTo body;

108.           --  Return the first item in the list.

109.           --  Note that if List is in fact an item of a larger list, the return

110.           --  value is the first item in the larger list itself.

112.           procedure FreeTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body);

113.           --  Free the list (but does not free the data in each of its elements).

114.           --  This only frees the memory associated with the list itself.

115.           --  You should only use this function on the lists that

116.           --  you have created yourself, not on the list that are returned by some

117.           --  functions in GtkAda (like Gtk.Clist.Get_Selection). These functions

118.           --  return directly the list managed by the underlying C widget, and you

119.           --  should never free the result yourself.

120.           --

121.           --  Note also that the memory might not be actually freed. For efficiency

122.           --  reasons, GtkAda will keep the memory allocated and try to reuse it as

123.           --  much as possible.

125.           function Get_DataTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GpointerTo API docTo spec;

126.           --  Return the value pointed to by List.

127.           --  The System.Address container in the C list is converted to a Gpointer

128.           --  through a call to Convert.

130.           function Get_Data_AddressTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return System.Address;

131.           --  Return directly the System.Address contained in the C list.

132.           --  This is used mainly internally in GtkAda to implement String lists,

133.           --  and you should not have to use this subprogram yourself.

135.           --  <doc_ignore>

136.           function Get_GpointerTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GpointerTo API docTo spec;

137.           --  Sometimes, the data is not stored in the "data" field

138.           --  of each cell, but rather at each cell. In such cases,

139.           --  to retrieve the address of the data, we need to return

140.           --  the address of the cell itself, insted of the address

141.           --  pointed to by data.

142.           --

143.           --  Ex: the Gtk_Ctree row_list.

144.           --  </doc_ignore>

146.           function IndexTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body; Data : GpointerTo API docTo spec) return GintTo API docTo spec;

147.           --  Return the index of the first element in List that contains Data.

148.           --  Note that this function is irrelevant if Convert does not return the

149.           --  same value for two identical data.

151.           function LastTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GlistTo API docTo specTo body;

152.           --  Return the last element in the list.

154.           function LengthTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GuintTo API docTo spec;

155.           --  Return the number of elements in the list.

156.           --  The last item's index is Length - 1.

158.           procedure List_ReverseTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body);

159.           --  Reverse the order of the list (the last item becomes the first, etc.)

161.           function NextTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GlistTo API docTo specTo body;

162.           --  Returns the Item following List in the global list that contains

163.           --  both.

164.           --  If there is no such item, return Null_List. This is how you

165.           --  stop iterating over a list.

167.           function NthTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body; N : GuintTo API docTo spec) return GlistTo API docTo specTo body;

168.           --  Give the nth item following LIST in the global list that

169.           --  contains both.

170.           --  If there is no such item, return Null_List.

172.           function Nth_DataTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body; N : GuintTo API docTo spec) return GpointerTo API docTo spec;

173.           --  Return the Data contained in the N-th item of List.

174.           --  The result is undefined if there is no such item in the list.

175.           --  The actual result in that case is the result of

176.           --      Convert (System.Null_Address);

177.           --  which might not mean anything.

179.           function PositionTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body; LinkTo API docTo body : GlistTo API docTo specTo body) return GintTo API docTo spec;

180.           --  Return the position of Link in the List.

181.           --  If Link is not contained in the list, -1 is returned.

183.           procedure PrependTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body; Data : GpointerTo API docTo spec);

184.           --  Add an item at the beginning of the list.

185.           --  This operation always succeed.

187.           function PrevTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return GlistTo API docTo specTo body;

188.           --  Return the item before List in the global list that contains both.

189.           --  Return Null_List if there is no such item.

191.           procedure RemoveTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body; Data : GpointerTo API docTo spec);

192.           --  Remove the first item in List that contains Data.

193.           --  Note that this operation can succeed only if Convert always return

194.           --  the same address for a given value.

196.           procedure Remove_LinkTo API docTo body (ListTo API docTo body : in out GlistTo API docTo specTo body; LinkTo API docTo body : GlistTo API docTo specTo body);

197.           --  Remove Link from the list to which it belongs.

198.           --  If that list is not List, no error is returned, but Link is removed

199.           --  anyway.

201.           function Is_CreatedTo API docTo body (ListTo API docTo body : GlistTo API docTo specTo body) return Boolean;

202.           --  Return True if there is a C widget associated with List.

204.           ------------------------

205.           -- Internal functions --

206.           ------------------------

207.           --  Please do not use the following functions. They are used internally

208.           --  by GtkAda.

209.           --  <doc_ignore>

211.           function Get_ObjectTo API docTo body (ObjTo API docTo body : GlistTo API docTo specTo body) return System.Address;

212.           --  Returns the C object contained in Obj.

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

215.           procedure Set_ObjectTo API docTo body (ObjTo API docTo body : in out GlistTo API docTo specTo body; Value : System.Address);

216.           --  Modifies the C object contained in Obj.

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

219.           --  </doc_ignore>

221.        private

223.           type GlistTo API docTo spec is record

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

225.           end record;

227.           Null_ListTo API docTo spec : constant GlistTo API docTo specTo body := (Ptr => System.Null_Address);

228.        end Generic_ListTo API docTo specTo body;

230.     end Glib.GlistTo API docTo specTo body;

232.     --  <example>

233.     --  <include>../examples/documentation/glist_traverse.adb</include>

234.     --  </example>