## 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-2011, 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.     --  This widget provides completion functionality for Gtk.Gentry.Gtk_Entry.

32.     --

33.     --  "Completion functionality" means that when the user modifies the text in

34.     --  the entry, GtkEntryCompletion checks which rows in the model match the

35.     --  current content of the entry, and displays a list of matches. By default,

36.     --  the matching is done by comparing the entry text case-insensitively against

37.     --  the text column of the model (see Set_Text_Column), but this can be

38.     --  overridden with a custom match function (see Set_Match_Func).

39.     --

40.     --  When the user selects a completion, the content of the entry is updated.

41.     --  By default, the content of the entry is replaced by the text column of the

42.     --  model, but this can be overridden by connecting to the ::match-selected

43.     --  signal and updating the entry in the signal handler. Note that you should

44.     --  return TRUE from the signal handler to suppress the default behaviour.

45.     --

46.     --  To add completion functionality to an entry, use Gtk.Entry.Set_Completion.

47.     --

48.     --  In addition to regular completion matches, which will be inserted into the

49.     --  entry when they are selected, GtkEntryCompletion also allows to display

50.     --  "actions" in the popup window. Their appearance is similar to menuitems, to

51.     --  differentiate them clearly from completion strings. When an action is

52.     --  selected, the ::action-activated signal is emitted.

53.     --

54.     --  </description>

55.     --  <group>Numeric/Text Data Entry</group>

57.     pragma Warnings (Off, "*is already use-visible*");

58.     with GlibTo API docTo specTo body;                 use GlibTo API docTo specTo body;

59.     with Glib.ObjectTo API docTo specTo body;          use Glib.ObjectTo API docTo specTo body;

60.     with Glib.PropertiesTo API docTo specTo body;      use Glib.PropertiesTo API docTo specTo body;

61.     with Glib.TypesTo API docTo specTo body;           use Glib.TypesTo API docTo specTo body;

62.     with Gtk.BuildableTo API docTo specTo body;        use Gtk.BuildableTo API docTo specTo body;

63.     with Gtk.Cell_LayoutTo API docTo specTo body;      use Gtk.Cell_LayoutTo API docTo specTo body;

64.     with Gtk.Tree_ModelTo API docTo specTo body;       use Gtk.Tree_ModelTo API docTo specTo body;

65.     with Gtk.WidgetTo API docTo specTo body;           use Gtk.WidgetTo API docTo specTo body;

66.     with Interfaces.C.Strings; use Interfaces.C.Strings;

68.     package Gtk.Entry_CompletionTo API docTo specTo body is

70.        type Gtk_Entry_Completion_Record is new GObject_RecordTo API docTo specTo body with null record;

71.        type Gtk_Entry_Completion is access all Gtk_Entry_Completion_RecordTo API docTo spec'Class;

73.        type C_Gtk_Entry_Completion_Match_Func is access function

74.          (Completion    : System.Address;

75.           Key           : Interfaces.C.Strings.chars_ptr;

76.           Iter          : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

77.           Data          : System.Address) return Boolean;

78.        pragma Convention (C, C_Gtk_Entry_Completion_Match_FuncTo API docTo spec);

80.        ------------------

81.        -- Constructors --

82.        ------------------

84.        procedure Gtk_NewTo API docTo body (Completion : out Gtk_Entry_CompletionTo API docTo spec);

85.        procedure InitializeTo API docTo body

86.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec'Class);

87.        --  Creates a new Gtk.Entry_Completion.Gtk_Entry_Completion object.

88.        --  Since: gtk+ 2.4

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

91.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_entry_completion_get_type");

93.        -------------

94.        -- Methods --

95.        -------------

97.        procedure CompleteTo API docTo body (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec);

98.        --  Requests a completion operation, or in other words a refiltering of the

99.        --  current list with completions, using the current key. The completion

100.        --  list view will be updated accordingly.

101.        --  Since: gtk+ 2.4

103.        procedure Delete_ActionTo API docTo body

104.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

105.            Index      : GintTo API docTo spec);

106.        --  Deletes the action at Index_ from Completion's action list.

107.        --  Since: gtk+ 2.4

108.        --  "index_": The index of the item to Delete.

110.        function Get_Completion_PrefixTo API docTo body

111.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

112.        --  Get the original text entered by the user that triggered the completion

113.        --  or null if there's no completion ongoing.

114.        --  Since: gtk+ 2.12

116.        function Get_EntryTo API docTo body

117.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec)

118.            return Gtk.Widget.Gtk_WidgetTo API docTo spec;

119.        --  Gets the entry Completion has been attached to.

120.        --  Since: gtk+ 2.4

122.        function Get_Inline_CompletionTo API docTo body

123.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return Boolean;

124.        procedure Set_Inline_CompletionTo API docTo body

125.           (Completion        : access Gtk_Entry_Completion_RecordTo API docTo spec;

126.            Inline_Completion : Boolean);

127.        --  Sets whether the common prefix of the possible completions should be

128.        --  automatically inserted in the entry.

129.        --  Since: gtk+ 2.6

130.        --  "inline_completion": True to do inline completion

132.        function Get_Inline_SelectionTo API docTo body

133.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return Boolean;

134.        procedure Set_Inline_SelectionTo API docTo body

135.           (Completion       : access Gtk_Entry_Completion_RecordTo API docTo spec;

136.            Inline_Selection : Boolean);

137.        --  Sets whether it is possible to cycle through the possible completions

138.        --  inside the entry.

139.        --  Since: gtk+ 2.12

140.        --  "inline_selection": True to do inline selection

142.        function Get_Minimum_Key_LengthTo API docTo body

143.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return GintTo API docTo spec;

144.        procedure Set_Minimum_Key_LengthTo API docTo body

145.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

146.            Length     : GintTo API docTo spec);

147.        --  Requires the length of the search key for Completion to be at least

148.        --  length. This is useful for long lists, where completing using a small

149.        --  key takes a lot of time and will come up with meaningless results anyway

150.        --  (ie, a too large dataset).

151.        --  Since: gtk+ 2.4

152.        --  "length": The minimum length of the key in order to start completing.

154.        function Get_ModelTo API docTo body

155.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec)

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

157.        procedure Set_ModelTo API docTo body

158.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

159.            Model      : access Gtk.Tree_Model.Gtk_Tree_Model_RecordTo API docTo specTo body'Class);

160.        --  Sets the model for a Gtk.Entry_Completion.Gtk_Entry_Completion. If

161.        --  Completion already has a model set, it will remove it before setting the

162.        --  new model. If model is null, then it will unset the model.

163.        --  Since: gtk+ 2.4

164.        --  "model": The Gtk.Tree_Model.Gtk_Tree_Model.

166.        function Get_Popup_CompletionTo API docTo body

167.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return Boolean;

168.        procedure Set_Popup_CompletionTo API docTo body

169.           (Completion       : access Gtk_Entry_Completion_RecordTo API docTo spec;

170.            Popup_Completion : Boolean);

171.        --  Sets whether the completions should be presented in a popup window.

172.        --  Since: gtk+ 2.6

173.        --  "popup_completion": True to do popup completion

175.        function Get_Popup_Set_WidthTo API docTo body

176.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return Boolean;

177.        procedure Set_Popup_Set_WidthTo API docTo body

178.           (Completion      : access Gtk_Entry_Completion_RecordTo API docTo spec;

179.            Popup_Set_Width : Boolean);

180.        --  Sets whether the completion popup window will be resized to be the same

181.        --  width as the entry.

182.        --  Since: gtk+ 2.8

183.        --  "popup_set_width": True to make the width of the popup the same as the

184.        --  entry

186.        function Get_Popup_Single_MatchTo API docTo body

187.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return Boolean;

188.        procedure Set_Popup_Single_MatchTo API docTo body

189.           (Completion         : access Gtk_Entry_Completion_RecordTo API docTo spec;

190.            Popup_Single_Match : Boolean);

191.        --  Sets whether the completion popup window will appear even if there is

192.        --  only a single match. You may want to set this to False if you are using

193.        --  <link linkend="GtkEntryCompletion--inline-completion">inline

194.        --  completion</link>.

195.        --  Since: gtk+ 2.8

196.        --  "popup_single_match": True if the popup should appear even for a single

197.        --  match

199.        function Get_Text_ColumnTo API docTo body

200.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec) return GintTo API docTo spec;

201.        procedure Set_Text_ColumnTo API docTo body

202.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

203.            Column     : GintTo API docTo spec);

204.        --  completion list with just strings. This function will set up Completion

205.        --  to have a list displaying all (and just) strings in the completion list,

206.        --  and to get those strings from Column in the model of Completion. This

207.        --  functions creates and adds a Gtk.Cellrenderertext.Gtk_Cellrenderertext

208.        --  for the selected column. If you need to set the text column, but don't

209.        --  want the cell renderer, use g_object_set to set the ::text_column

210.        --  property directly.

211.        --  Since: gtk+ 2.4

212.        --  "column": The column in the model of Completion to get strings from.

214.        procedure Insert_Action_MarkupTo API docTo body

215.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

216.            Index      : GintTo API docTo spec;

217.            Markup     : UTF8_StringTo API docTo spec);

218.        --  Inserts an action in Completion's action item list at position Index_

219.        --  with markup Markup.

220.        --  Since: gtk+ 2.4

221.        --  "index_": The index of the item to insert.

222.        --  "markup": Markup of the item to insert.

224.        procedure Insert_Action_TextTo API docTo body

225.           (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec;

226.            Index      : GintTo API docTo spec;

227.            Text       : UTF8_StringTo API docTo spec);

228.        --  Inserts an action in Completion's action item list at position Index_

229.        --  with text Text. If you want the action item to have markup, use

230.        --  Gtk.Entry_Completion.Insert_Action_Markup.

231.        --  Since: gtk+ 2.4

232.        --  "index_": The index of the item to insert.

233.        --  "text": Text of the item to insert.

235.        procedure Insert_PrefixTo API docTo body (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec);

236.        --  Requests a prefix insertion.

237.        --  Since: gtk+ 2.6

239.        procedure Set_Match_FuncTo API docTo body

240.           (Completion  : access Gtk_Entry_Completion_RecordTo API docTo spec;

241.            Func        : C_Gtk_Entry_Completion_Match_FuncTo API docTo spec;

242.            Func_Data   : System.Address;

243.            Func_Notify : Glib.G_Destroy_Notify_AddressTo API docTo spec);

244.        --  Sets the match function for Completion to be Func. The match function

245.        --  is used to determine if a row should or should not be in the completion

246.        --  list.

247.        --  Since: gtk+ 2.4

248.        --  "func": The C_Gtk_Entry_Completion_Match_Func to use.

249.        --  "func_data": The user data for Func.

250.        --  "func_notify": Destroy notifier for Func_Data.

252.        ----------------------

253.        -- GtkAda additions --

254.        ----------------------

256.        generic

257.        type Data_Type (<>) is private;

258.        package Match_FunctionsTo API docTo body is

259.           type Gtk_Entry_Completion_Match_Func is access

260.           function (Completion : access Gtk_Entry_Completion_RecordTo API docTo spec'Class;

261.              Key        : String;

262.              Iter       : Gtk.Tree_Model.Gtk_Tree_IterTo API docTo specTo body;

263.              User_Data  : Data_TypeTo API docTo spec) return Boolean;

265.           type Destroy_Notify is access procedure (Data : in out Data_TypeTo API docTo spec);

267.           procedure Set_Match_FuncTo API docTo body

268.             (Completion  : access Gtk_Entry_Completion_RecordTo API docTo spec;

269.              Func        : Gtk_Entry_Completion_Match_FuncTo API docTo spec;

270.              Func_Data   : Data_TypeTo API docTo spec;

271.              Func_Notify : Destroy_NotifyTo API docTo spec);

272.           --  Sets the match function for completion to be Func. The match function

273.           --  is used to determine if a row should or should not be in the

274.           --  completion list.

275.        end Match_FunctionsTo API docTo specTo body;

277.        ----------------

278.        -- Interfaces --

279.        ----------------

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

281.        --

282.        --  - "Buildable"

283.        --

284.        --  - "CellLayout"

286.        package Implements_Buildable is new Glib.Types.ImplementsTo API docTo specTo body

287.          (Gtk.Buildable.Gtk_BuildableTo API docTo spec, Gtk_Entry_Completion_RecordTo API docTo spec, Gtk_Entry_CompletionTo API docTo spec);

288.        function "+"

289.          (Widget : access Gtk_Entry_Completion_RecordTo API docTo spec'Class)

290.        return Gtk.Buildable.Gtk_BuildableTo API docTo spec

291.        renames Implements_Buildable.To_InterfaceTo API docTo specTo body;

292.        function "-"

293.          (Interf : Gtk.Buildable.Gtk_BuildableTo API docTo spec)

294.        return Gtk_Entry_CompletionTo API docTo spec

295.        renames Implements_Buildable.To_ObjectTo API docTo specTo body;

297.        package Implements_CellLayout is new Glib.Types.ImplementsTo API docTo specTo body

298.          (Gtk.Cell_Layout.Gtk_Cell_LayoutTo API docTo spec, Gtk_Entry_Completion_RecordTo API docTo spec, Gtk_Entry_CompletionTo API docTo spec);

299.        function "+"

300.          (Widget : access Gtk_Entry_Completion_RecordTo API docTo spec'Class)

301.        return Gtk.Cell_Layout.Gtk_Cell_LayoutTo API docTo spec

302.        renames Implements_CellLayout.To_InterfaceTo API docTo specTo body;

303.        function "-"

304.          (Interf : Gtk.Cell_Layout.Gtk_Cell_LayoutTo API docTo spec)

305.        return Gtk_Entry_CompletionTo API docTo spec

306.        renames Implements_CellLayout.To_ObjectTo API docTo specTo body;

308.        ----------------

309.        -- Properties --

310.        ----------------

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

312.        --  Glib.Properties for more information on properties)

313.        --

314.        --  Name: Inline_Completion_Property

315.        --  Type: Boolean

316.        --  Flags: read-write

317.        --  Determines whether the common prefix of the possible completions should

318.        --  be inserted automatically in the entry. Note that this requires

319.        --  text-column to be set, even if you are using a custom match function.

320.        --

321.        --  Name: Inline_Selection_Property

322.        --  Type: Boolean

323.        --  Flags: read-write

324.        --  Determines whether the possible completions on the popup will appear in

325.        --  the entry as you navigate through them.

326.        --

327.        --  Name: Minimum_Key_Length_Property

328.        --  Type: Gint

329.        --  Flags: read-write

330.        --

331.        --  Name: Model_Property

332.        --  Type: Gtk.Tree_Model.Gtk_Tree_Model

333.        --  Flags: read-write

334.        --

335.        --  Name: Popup_Completion_Property

336.        --  Type: Boolean

337.        --  Flags: read-write

338.        --  Determines whether the possible completions should be shown in a popup

339.        --  window.

340.        --

341.        --  Name: Popup_Set_Width_Property

342.        --  Type: Boolean

343.        --  Flags: read-write

344.        --  Determines whether the completions popup window will be resized to the

345.        --  width of the entry.

346.        --

347.        --  Name: Popup_Single_Match_Property

348.        --  Type: Boolean

349.        --  Flags: read-write

350.        --  Determines whether the completions popup window will shown for a single

351.        --  possible completion. You probably want to set this to False if you are

352.        --  using <link linkend="GtkEntryCompletion--inline-completion">inline

353.        --  completion</link>.

354.        --

355.        --  Name: Text_Column_Property

356.        --  Type: Gint

357.        --  Flags: read-write

358.        --  The column of the model containing the strings. Note that the strings

359.        --  must be UTF-8.

361.        Inline_Completion_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

362.        Inline_Selection_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

363.        Minimum_Key_Length_Property : constant Glib.Properties.Property_IntTo API docTo spec;

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

365.        Popup_Completion_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

366.        Popup_Set_Width_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

367.        Popup_Single_Match_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

368.        Text_Column_Property : constant Glib.Properties.Property_IntTo API docTo spec;

370.        -------------

371.        -- Signals --

372.        -------------

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

374.        --

375.        --  "action-activated"

376.        --     procedure Handler

377.        --       (Self  : access Gtk_Entry_Completion_Record'Class;

378.        --        Index : Gint);

379.        --    --  "index": the index of the activated action

380.        --  Gets emitted when an action is activated.

381.        --

382.        --  "cursor-on-match"

383.        --     function Handler

384.        --       (Self  : access Gtk_Entry_Completion_Record'Class;

385.        --        Model : Gtk.Tree_Model.Gtk_Tree_Model;

386.        --        Iter  : TreeIter) return Boolean;

387.        --    --  "model": the Gtk.Tree_Model.Gtk_Tree_Model containing the matches

388.        --    --  "iter": a GtkTreeIter positioned at the selected match

389.        --  Gets emitted when a match from the cursor is on a match of the list.The

390.        --  default behaviour is to replace the contents of the entry with the

391.        --  contents of the text column in the row pointed to by Iter.

392.        --  Returns True if the signal has been handled

393.        --

394.        --  "insert-prefix"

395.        --     function Handler

396.        --       (Self   : access Gtk_Entry_Completion_Record'Class;

397.        --        Prefix : UTF8_String) return Boolean;

398.        --    --  "prefix": the common prefix of all possible completions

399.        --  Gets emitted when the inline autocompletion is triggered. The default

400.        --  behaviour is to make the entry display the whole prefix and select the

401.        --  newly inserted part. Applications may connect to this signal in order to

402.        --  insert only a smaller part of the Prefix into the entry - e.g. the entry

403.        --  used in the Gtk.File_Chooser.Gtk_File_Chooser inserts only the part of

404.        --  the prefix up to the next '/'.

405.        --  Returns True if the signal has been handled

406.        --

407.        --  "match-selected"

408.        --     function Handler

409.        --       (Self  : access Gtk_Entry_Completion_Record'Class;

410.        --        Model : Gtk.Tree_Model.Gtk_Tree_Model;

411.        --        Iter  : TreeIter) return Boolean;

412.        --    --  "model": the Gtk.Tree_Model.Gtk_Tree_Model containing the matches

413.        --    --  "iter": a GtkTreeIter positioned at the selected match

414.        --  Gets emitted when a match from the list is selected. The default

415.        --  behaviour is to replace the contents of the entry with the contents of

416.        --  the text column in the row pointed to by Iter.

417.        --  Returns True if the signal has been handled

419.        Signal_Action_Activated : constant Glib.Signal_NameTo API docTo spec := "action-activated";

420.        Signal_Cursor_On_Match : constant Glib.Signal_NameTo API docTo spec := "cursor-on-match";

421.        Signal_Insert_Prefix : constant Glib.Signal_NameTo API docTo spec := "insert-prefix";

422.        Signal_Match_Selected : constant Glib.Signal_NameTo API docTo spec := "match-selected";

424.     private

425.        Inline_Completion_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

426.          Glib.Properties.BuildTo API docTo specTo body ("inline-completion");

427.        Inline_Selection_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

428.          Glib.Properties.BuildTo API docTo specTo body ("inline-selection");

429.        Minimum_Key_Length_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

430.          Glib.Properties.BuildTo API docTo specTo body ("minimum-key-length");

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

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

433.        Popup_Completion_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

434.          Glib.Properties.BuildTo API docTo specTo body ("popup-completion");

435.        Popup_Set_Width_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

436.          Glib.Properties.BuildTo API docTo specTo body ("popup-set-width");

437.        Popup_Single_Match_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

438.          Glib.Properties.BuildTo API docTo specTo body ("popup-single-match");

439.        Text_Column_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

440.          Glib.Properties.BuildTo API docTo specTo body ("text-column");

441.     end Gtk.Entry_CompletionTo API docTo specTo body;