## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2001-2006 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.     --  The Gtk_Tree_Model_Sort is a model which implements the Gtk_Tree_Sortable

31.     --  interface. It does not hold any data itself, but rather is created with

32.     --  child model and proxies its data. It has identical column types to this

33.     --  child model, and the changes in the child are propagated. The primary

34.     --  purpose of this model is to provide a way to sort a different model without

35.     --  modifying it. Note that the sort function used by Gtk_Tree_Model_Sort is

36.     --  not guaranteed to be stable.

37.     --

38.     --  The use of this is best demonstrated through an example. In the following

39.     --  sample code we create two Gtk_Tree_View widgets each with a view of the

40.     --  same data. As the model is wrapped here by a Gtk_Tree_Model_Sort, the two

41.     --  Gtk_Tree_Views can each sort their view of the data without affecting the

42.     --  other. By contrast, if we simply put the same model in each widget, then

43.     --  sorting the first would sort the second.

44.     --

45.     --  declare

46.     --     Tree_View1, Tree_View2   : Gtk_Tree_View;

47.     --     Sort_Model1, Sort_Model2 : Gtk_Tree_Model_Sort;

48.     --     Child_Model              : Gtk_Tree_Model;

49.     --  begin

50.     --    Child_Model := Get_My_Model;  --  Your own implementation

51.     --

52.     --    --  Create the first tree

53.     --    Gtk_New_With_Model (Sort_Model1, Child_Model);

54.     --    Gtk_New (Tree_View1, Sort_Model1);

55.     --    Set_Sort_Column_Id (Sort_Model1, COLUMN1, Sort_Ascending);

56.     --

57.     --    --  Create the second tree

58.     --    Gtk_New_With_Model (Sort_Model2, Child_Model);

59.     --    Gtk_New (Tree_View2, Sort_Model2);

60.     --    Set_Sort_Column_Id (Sort_Model2, COLUMN1, Sort_Descending);

61.     --  end;

62.     --

63.     --  To demonstrate how to access the underlying child model from the sort

64.     --  model, the next example will be a callback for the Gtk_Tree_Selection

65.     --  "changed" signal. In this callback, we get a string from COLUMN_1 of the

66.     --  model. We then modify the string, find the same selected row on the child

67.     --  model, and change the row there.

68.     --

69.     --  procedure Selection_Changed

70.     --    (Selection : access Gtk_Tree_Selection_Record'Class)

71.     --  is

72.     --     Sort_Model, Child_Model : Gtk_Tree_Model;

73.     --     Sort_Iter, Child_Iter   : Gtk_Tree_Iter;

74.     --  begin

75.     --     --  Get the currently selected row and the model

76.     --     Get_Selected (Selection, Sort_Model, Sort_Iter);

77.     --     if Sort_Iter = Null_Iter then

78.     --        return;

79.     --     end if;

80.     --

81.     --     --  Lookup the current value on the selected row

82.     --     declare

83.     --       Some_Data : constant String :=

84.     --                     Get_String (Sort_Model, Sort_Iter, COLUMN1);

85.     --     begin

86.     --        --  Get an iterator on the child model instead of the sort model

87.     --        Convert_Iter_To_Child_Iter (Sort_Model, Child_Iter, Sort_Iter);

88.     --

89.     --        --  Get the child model and change the value in the row

90.     --        --  In this example, the model is a Gtk_List_Store, but it could be

91.     --        --  anything

92.     --        Child_Model := Get_Model (Gtk_Sort_Model (Sort_Model));

93.     --        Set (Ctk_List_Store (Child_Model), Child_Iter, COLUMN1, "data");

94.     --     end;

95.     --  end Selection_Changed;

96.     --  </description>

97.     --  <c_version>2.8.17</c_version>

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

100.     with Glib.PropertiesTo API docTo specTo body;

101.     with Glib.TypesTo API docTo specTo body;

102.     with GtkTo API docTo spec;

103.     with Gtk.Tree_DndTo API docTo specTo body;

104.     with Gtk.Tree_ModelTo API docTo specTo body;

105.     with Gtk.Tree_SortableTo API docTo specTo body;

107.     package Gtk.Tree_Model_SortTo API docTo specTo body is

109.        type Gtk_Tree_Model_Sort_Record is

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

111.        type Gtk_Tree_Model_Sort is access all Gtk_Tree_Model_Sort_RecordTo API docTo spec'Class;

113.        procedure Gtk_New_With_ModelTo API docTo body

114.          (Sort_Model  : out Gtk_Tree_Model_SortTo API docTo spec;

115.           Child_Model : access Gtk.Tree_Model.Gtk_Tree_Model_RecordTo API docTo specTo body'Class);

116.        procedure Initialize_With_ModelTo API docTo body

117.          (Sort_Model  : access Gtk_Tree_Model_Sort_RecordTo API docTo spec'Class;

118.           Child_Model : access Gtk.Tree_Model.Gtk_Tree_Model_RecordTo API docTo specTo body'Class);

119.        --  Creates or initialized a new sortable tree model, with Child_Model as

120.        --  the child model.

121.        --  Any change in Child_Model is reflected into Sort_Model

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

124.        --  Return the internal type associated with a Gtk_Tree_Model_Sort.

126.        function Get_ModelTo API docTo body

127.          (Tree_Model : access Gtk_Tree_Model_Sort_RecordTo API docTo spec)

128.           return Gtk.Tree_Model.Gtk_Tree_ModelTo API docTo spec;

129.        --  Return the model the Gtk_Tree_Model_Sort is sorting.

131.        function Convert_Child_Path_To_PathTo API docTo body

132.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec;

133.           Child_Path      : Gtk.Tree_Model.Gtk_Tree_PathTo API docTo spec)

134.           return Gtk.Tree_Model.Gtk_Tree_PathTo API docTo spec;

135.        --  Convert Child_Path to a path relative to Tree_Model_Sort.

136.        --  That is, Child_Path points to a path in the child model.

137.        --  The returned path will point to the same row in the sorted model.

138.        --  If Child_Path isn't a valid path on the child model, then Null

139.        --  is returned.

140.        --  The returned value must be freed with Path_Free.

142.        procedure Convert_Child_Iter_To_IterTo API docTo body

143.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec;

144.           Sort_IterTo API docTo body       : out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

145.           Child_IterTo API docTo body      : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

146.        --  Set Sort_Iter to point to the row in Tree_Model_Sort that

147.        --  corresponds to the row pointed at by Child_Iter.

149.        function Convert_Path_To_Child_PathTo API docTo body

150.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec;

151.           Sorted_Path     : Gtk.Tree_Model.Gtk_Tree_PathTo API docTo spec)

152.           return Gtk.Tree_Model.Gtk_Tree_PathTo API docTo spec;

153.        --  Convert Sort_Path to a path on the child model of Tree_Model_Sort.

154.        --  That is, Sort_Path points ot a location in Tree_Model_Sort.

155.        --  The returned path will point to the same location in the model

156.        --  not being sorted.

158.        procedure Convert_Iter_To_Child_IterTo API docTo body

159.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec;

160.           Child_IterTo API docTo body      : out Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

161.           Sorted_IterTo API docTo body     : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body);

162.        --  Set Child_Iter to point to the row pointed to by Sorted_Iter.

164.        procedure Reset_Default_Sort_FuncTo API docTo body

165.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec);

166.        --  This resets the default sort function to be in the 'unsorted' state.

167.        --  That is, it is in the same order as the child model. It will re-sort the

168.        --  model to be in the same order as the child model only if the

169.        --  Gtk_Tree_Model_Sort is in 'unsorted' state.

171.        procedure Clear_CacheTo API docTo body (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec);

172.        --  This function should almost never be called. It clears the

173.        --  tree_model_sort of any cached iterators that haven't been reffed with

174.        --  gtk.tree_model.ref_node. This might be useful if the child model being

175.        --  sorted is static (and doesn't change often) and there has been a lot of

176.        --  unreffed access to nodes. As a side effect of this function, all

177.        --  unreffed iters will be invalid.

179.        function Iter_Is_ValidTo API docTo body

180.          (Tree_Model_Sort : access Gtk_Tree_Model_Sort_RecordTo API docTo spec;

181.           IterTo API docTo body            : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body) return Boolean;

182.        --  WARNING: this function is slow. Only use if for debugging and/or

183.        --  testing purposes.

184.        --  Checks if the given iter is a valid iter for this model.

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

187.        -- Interfaces --

188.        ----------------

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

190.        --

191.        --  - "Gtk_Tree_Sortable"

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

193.        --

194.        --  - "Gtk_Tree_Drag_Source"

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

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

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

199.           Gtk_Tree_Model_Sort_RecordTo API docTo spec,

200.           Gtk_Tree_Model_SortTo API docTo spec);

201.        function "+"

202.          (Model : access Gtk_Tree_Model_Sort_RecordTo API docTo spec'Class)

203.           return Gtk.Tree_Sortable.Gtk_Tree_SortableTo API docTo spec

204.           renames Implements_Tree_Sortable.To_InterfaceTo API docTo specTo body;

205.        function "-"

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

207.           return Gtk_Tree_Model_SortTo API docTo spec

208.           renames Implements_Tree_Sortable.To_ObjectTo API docTo specTo body;

209.        --  Converts to and from the Gtk_Tree_Sortable interface

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

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

213.           Gtk_Tree_Model_Sort_RecordTo API docTo spec,

214.           Gtk_Tree_Model_SortTo API docTo spec);

215.        function "+"

216.          (Model : access Gtk_Tree_Model_Sort_RecordTo API docTo spec'Class)

217.           return Gtk.Tree_Dnd.Gtk_Tree_Drag_SourceTo API docTo spec

218.           renames Implements_Drag_Source.To_InterfaceTo API docTo specTo body;

219.        function "-"

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

221.           return Gtk_Tree_Model_SortTo API docTo spec

222.           renames Implements_Drag_Source.To_ObjectTo API docTo specTo body;

223.        --  Converts to and from the Gtk_Tree_Drag_Source interface

225.        -------------

226.        -- Signals --

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

229.        --  <signals>

230.        --  The following new signals are defined for this widget:

231.        --

232.        --  </signals>

234.        ----------------

235.        -- Properties --

236.        ----------------

238.        --  <properties>

239.        --  The following properties are defined for this widget. See

240.        --  Glib.Properties for more information on properties.

241.        --

242.        --  Name:  Model_Property

243.        --  Type:  Object

244.        --  Descr: The model for the TreeModelSort to sort

245.        --

246.        --  </properties>

248.        Model_Property : constant Glib.Properties.Property_ObjectTo API docTo spec;

250.     private

251.        Model_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

252.          Glib.Properties.BuildTo API docTo specTo body ("model");

254.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_tree_model_sort_get_type");

255.     end Gtk.Tree_Model_SortTo API docTo specTo body;