## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2001-2009, 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 is the public representation of a text buffer to be used in

31.     --  coordination with Gtk.Text_View.

32.     --  </description>

33.     --  <c_version>2.8.17</c_version>

34.     --  <group>Multiline Text Editor</group>

36.     with Glib.PropertiesTo API docTo specTo body;

37.     with Gdk.PixbufTo API docTo specTo body;

38.     with Gtk.ClipboardTo API docTo specTo body;

39.     with Gtk.Text_ChildTo API docTo specTo body;

40.     with Gtk.Text_IterTo API docTo specTo body;

41.     with Gtk.Text_MarkTo API docTo specTo body;

42.     with Gtk.Text_TagTo API docTo specTo body;

43.     with Gtk.Text_Tag_TableTo API docTo specTo body;

44.     with Gtkada.TypesTo API docTo specTo body;

46.     package Gtk.Text_BufferTo API docTo specTo body is

48.        type Gtk_Text_Buffer_RecordTo API docTo body is new GObject_RecordTo API docTo specTo body with private;

49.        type Gtk_Text_Buffer is access all Gtk_Text_Buffer_RecordTo API docTo specTo body'Class;

51.        procedure Gtk_NewTo API docTo body

52.          (Buffer : out Gtk_Text_BufferTo API docTo spec;

53.           Table  : Gtk.Text_Tag_Table.Gtk_Text_Tag_TableTo API docTo spec := null);

54.        procedure InitializeTo API docTo body

55.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body'Class;

56.           Table  : Gtk.Text_Tag_Table.Gtk_Text_Tag_TableTo API docTo spec := null);

57.        --  Creates or initializes a new text buffer.

58.        --  Create a new table if Table is null.

59.        --  The buffer is created with a reference count of 1, and therefore should

60.        --  be manually unreferenced (Glib.Object.Unref). It is recommended to do

61.        --  that as soon as the buffer has been used to create a

62.        --  Gtk.Text_View.Gtk_Text_View widget.

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

65.        --  Return the internal value associated with a Gtk_Text_Buffer.

67.        function Get_Line_CountTo API docTo body

68.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body) return GintTo API docTo spec;

69.        --  Return the number of lines in the buffer.

70.        --  This value is cached, so the function is very fast.

72.        function Get_Char_CountTo API docTo body

73.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body) return GintTo API docTo spec;

74.        --  Return the number of characters in the buffer.

75.        --  Note that characters and bytes are not the same, you can't e.g. expect

76.        --  the contents of the buffer in string form to be this many bytes long.

77.        --  The character count is cached, so this function is very fast.

79.        ---------------------------

80.        -- Modifiying the buffer --

81.        ---------------------------

83.        procedure Set_ModifiedTo API docTo body

84.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

85.           Setting : Boolean := True);

86.        function Get_ModifiedTo API docTo body

87.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body) return Boolean;

88.        --  Used to keep track of whether the buffer has been modified since the

89.        --  last time it was saved. Whenever the buffer is saved to disk, call

90.        --  Set_Modified (Buffer, False). When the buffer is modified,

91.        --  it will automatically toggled on the modified bit again. When the

92.        --  modified bit flips, the buffer emits a "modified_changed" signal.

94.        procedure Set_TextTo API docTo body

95.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

96.           Text   : UTF8_StringTo API docTo spec);

97.        --  Delete current contents of Buffer, and insert Text instead.

98.        --  If Text doesn't end with a newline, a newline is added;

99.        --  Gtk_Text_Buffer contents must always end with a newline. If Text

100.        --  ends with a newline, the new buffer contents will be exactly Text.

101.        --  Text: UTF-8 format text to insert.

103.        procedure InsertTo API docTo body

104.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

105.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

106.           Text   : UTF8_StringTo API docTo spec);

107.        procedure InsertTo API docTo body

108.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

109.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

110.           Text   : Gtkada.Types.Chars_PtrTo API docTo spec);

111.        --  Insert Text at position Iter.

112.        --  Emit the "insert_text" signal; insertion actually occurs

113.        --  in the default handler for the signal. Iter is invalidated when

114.        --  insertion occurs (because the buffer contents change), but the

115.        --  default signal handler revalidates it to point to the end of the

116.        --  inserted text.

117.        --  Text: UTF-8 format text to insert.

119.        procedure Insert_With_TagsTo API docTo body

120.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

121.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

122.           Text   : UTF8_StringTo API docTo spec;

123.           Tag    : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec);

124.        procedure Insert_With_TagsTo API docTo body

125.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

126.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

127.           Text   : Gtkada.Types.Chars_PtrTo API docTo spec;

128.           Tag    : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec);

129.        --  Same as Insert, but specifies the tag to apply to the range.

131.        procedure Insert_With_Tags_By_NameTo API docTo body

132.          (Buffer   : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

133.           IterTo API docTo body     : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

134.           Text     : UTF8_StringTo API docTo spec;

135.           Tag_Name : String);

136.        --  Same as Insert_With_Tags, but the tag is specified by its name

138.        procedure Insert_At_CursorTo API docTo body

139.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

140.           Text   : UTF8_StringTo API docTo spec);

141.        --  Call Buffer_Insert, using the current cursor position

142.        --  as the insertion point.

143.        --  Text: UTF-8 format text to insert.

145.        procedure Insert_At_CursorTo API docTo body

146.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

147.           Text   : Gtkada.Types.Chars_PtrTo API docTo spec;

148.           Len    : GintTo API docTo spec := -1);

149.        --  Call Buffer_Insert, using the current cursor position

150.        --  as the insertion point.

151.        --  Text: UTF-8 format C string to insert.

153.        procedure Insert_InteractiveTo API docTo body

154.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

155.           IterTo API docTo body             : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

156.           Text             : UTF8_StringTo API docTo spec;

157.           Default_Editable : Boolean;

158.           Result           : out Boolean);

159.        --  Like Insert, but the insertion will not occur if Iter is at a

160.        --  non-editable location in the buffer. Usually you

161.        --  want to prevent insertions at ineditable locations if the insertion

162.        --  results from a user action (is interactive).

163.        --

164.        --  Default_Editable indicates the editability of text that doesn't

165.        --  have a tag affecting editability applied to it. Typically the

166.        --  result of Gtk.Text_View.Get_Editable is appropriate here.

167.        --  Text: UTF-8 format text to insert.

168.        --  Result: whether text was actually inserted.

170.        function Insert_Interactive_At_CursorTo API docTo body

171.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

172.           Text             : UTF8_StringTo API docTo spec;

173.           Default_Editable : Boolean) return Boolean;

174.        --  Call Insert_Interactive at the cursor position.

175.        --  Text: UTF-8 format text to insert.

176.        --  Return value: whether text was actually inserted.

178.        procedure Insert_RangeTo API docTo body

179.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

180.           IterTo API docTo body    : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

181.           StartTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

182.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

183.        --  Copy text, tags, and pixbufs between Start and End.

184.        --  The order of Start and End doesn't matter.

185.        --  Also insert the copy at Iter.

186.        --  Used instead of simply getting/inserting text because it preserves

187.        --  images and tags. If Start and End are in a different buffer from

188.        --  Buffer, the two buffers must share the same tag table.

189.        --  Implemented via emissions of the insert_text and apply_tag signals,

190.        --  so expect those.

192.        procedure Insert_Range_InteractiveTo API docTo body

193.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

194.           IterTo API docTo body             : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

195.           StartTo API docTo body            : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

196.           The_EndTo API docTo body          : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

197.           Default_Editable : Boolean;

198.           Result           : out Boolean);

199.        --  Like Insert_Range, does nothing if the insertion point isn't editable.

200.        --  The Default_Editable parameter indicates whether the text is editable at

201.        --  Iter if no tags enclosing Iter affect editability. Typically the result

202.        --  of Gtk.Text_View.Get_Editable is appropriate here.

203.        --  Result: whether an insertion was possible at Iter

205.        procedure Insert_PixbufTo API docTo body

206.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

207.           IterTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

208.           Pixbuf : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec);

209.        --  Insert an image into the text buffer at Iter.

210.        --  The image will be counted as one character in character counts, and when

211.        --  obtaining the buffer contents as a string, will be represented by the

212.        --  Unicode "object replacement character" 16#FFFC#. Note that the "slice"

213.        --  variants for obtaining portions of the buffer as a string include

214.        --  this character for pixbufs, but the "text" variants do not. e.g. see

215.        --  Get_Slice and Get_Text.

217.        procedure DeleteTo API docTo body

218.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

219.           StartTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

220.           The_EndTo API docTo body : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

221.        --  Delete text between Start and End.

222.        --  The order of Start and End is not actually relevant;

223.        --  Delete will reorder them. This function actually emits the

224.        --  "delete_range" signal, and the default handler of that signal deletes

225.        --  the text. Because the buffer is modified, all outstanding iterators

226.        --  become invalid after calling this function; however, the Start and End

227.        --  will be re-initialized to point to the location where text was deleted.

228.        --

229.        --  Note that the final newline in the buffer may not be deleted; a

230.        --  Gtk_Text_Buffer always contains at least one newline. You can

231.        --  safely include the final newline in the range [Start,End) but it

232.        --  won't be affected by the deletion.

234.        procedure Delete_InteractiveTo API docTo body

235.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

236.           Start_IterTo API docTo body       : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

237.           End_IterTo API docTo body         : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

238.           Default_Editable : Boolean;

239.           Result           : out Boolean);

240.        --  Delete all editable text in the given range.

241.        --  Call Delete for each editable sub-range of [Start,End). Start and End

242.        --  are revalidated to point to the location of the last deleted range, or

243.        --  left untouched if no text was deleted.

244.        --  Result: whether some text was actually deleted

246.        function BackspaceTo API docTo body

247.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

248.           IterTo API docTo body             : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

249.           Interactive      : Boolean;

250.           Default_Editable : Boolean)

251.           return Boolean;

252.        --  Performs the appropriate action as if the user hit the delete key with

253.        --  the cursor at the position specified by Iter. In the normal case a

254.        --  single character will be deleted, but when combining accents are

255.        --  involved, more than one character can be deleted, and when precomposed

256.        --  character and accent combinations are involved, less than one character

257.        --  will be deleted.

258.        --  Because the buffer is modified, all outstanding iterators become invalid

259.        --  after calling this function; however, Iter will be re-initialized to

260.        --  point to the location where text was deleted.

261.        --  Interactive should be true if the deletion is caused by user

262.        --  interaction.

263.        --  Default_Editable: Whether the buffer is editable by default.

264.        --  Returns True if the buffer was modified.

266.        ---------------------------------

267.        -- Reading the buffer contents --

268.        ---------------------------------

270.        function Get_TextTo API docTo body

271.          (Buffer               : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

272.           StartTo API docTo body                : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

273.           The_EndTo API docTo body              : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

274.           Include_Hidden_Chars : Boolean := False) return UTF8_StringTo API docTo spec;

275.        --  Return the text in the range [Start,End).

276.        --  Exclude undisplayed text (text marked with tags that set the

277.        --  invisibility attribute) if Include_Hidden_Chars is False. Does not

278.        --  include characters representing embedded images, so byte and character

279.        --  indexes into the returned string do not correspond to byte and character

280.        --  indexes into the buffer. Contrast with Get_Slice.

281.        --  Return value: an allocated UTF-8 string

283.        function Get_TextTo API docTo body

284.          (Buffer               : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

285.           StartTo API docTo body                : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

286.           The_EndTo API docTo body              : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

287.           Include_Hidden_Chars : Boolean := False) return Gtkada.Types.Chars_PtrTo API docTo spec;

288.        --  Same as Get_Text above, but return a pointer to a C string, for

289.        --  efficiency.

290.        --  The caller is responsible for freeing (using Gtkada.Types.g_free) the

291.        --  returned pointer.

293.        function Get_SliceTo API docTo body

294.          (Buffer               : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

295.           StartTo API docTo body                : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

296.           The_EndTo API docTo body              : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

297.           Include_Hidden_Chars : Boolean := False) return UTF8_StringTo API docTo spec;

298.        --  Return the text in the range [Start,End).

299.        --  Exclude undisplayed text (text marked with tags that set the

300.        --  invisibility attribute) if Include_Hidden_Chars is False. The returned

301.        --  string includes a 16#FFFC# character whenever the buffer contains

302.        --  embedded images, so byte and character indexes into

303.        --  the returned string do correspond to byte and character indexes into

304.        --  the buffer. Contrast with Get_Text. Note that 16#FFFC# can occur in

305.        --  normal text as well, so it is not a reliable indicator that a pixbuf or

306.        --  widget is in the buffer.

307.        --  Return value: an allocated UTF-8 string

309.        function Get_SliceTo API docTo body

310.          (Buffer               : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

311.           StartTo API docTo body                : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

312.           The_EndTo API docTo body              : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

313.           Include_Hidden_Chars : Boolean := False) return Gtkada.Types.Chars_PtrTo API docTo spec;

314.        --  Same as Get_Slice above, but return a pointer to a C string, for

315.        --  efficiency.

316.        --  The caller is responsible for freeing (using Gtkada.Types.g_free) the

317.        --  returned pointer.

319.        -----------

320.        -- Marks --

321.        -----------

322.        --  See Gtk.Text_Mark

324.        function Create_MarkTo API docTo body

325.          (Buffer       : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

326.           Mark_Name    : String := "";

327.           WhereTo API docTo body        : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

328.           Left_Gravity : Boolean := True) return Gtk.Text_Mark.Gtk_Text_MarkTo API docTo spec;

329.        --  Create a mark at position Where.

330.        --  If Mark_Name is null, the mark is anonymous; otherwise, the mark can be

331.        --  retrieved by name using Get_Mark. If a mark has left gravity, and text

332.        --  is inserted at the mark's current location, the mark will be moved to

333.        --  the left of the newly-inserted text. If the mark has right gravity

334.        --  (Left_Gravity = False), the mark will end up on the right of

335.        --  newly-inserted text. The standard left-to-right cursor is a mark

336.        --  with right gravity (when you type, the cursor stays on the right

337.        --  side of the text you're typing).

338.        --

339.        --  The caller of this function does not own a reference to the returned

340.        --  Gtk_Text_Mark, so you can ignore the return value if you like. Marks are

341.        --  owned by the buffer and go away when the buffer does.

342.        --  Emit the "mark_set" signal as notification of the mark's initial

343.        --  placement.

344.        --

345.        --  Return value: the new Gtk_Text_Mark object.

347.        procedure Move_MarkTo API docTo body

348.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

349.           Mark   : access Gtk.Text_Mark.Gtk_Text_Mark_RecordTo API docTo specTo body'Class;

350.           WhereTo API docTo body  : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

351.        --  Move Mark to the new location Where.

352.        --  Emit the "mark_set" signal as notification of the move.

354.        procedure Delete_MarkTo API docTo body

355.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

356.           Mark   : access Gtk.Text_Mark.Gtk_Text_Mark_RecordTo API docTo specTo body'Class);

357.        --  Delete Mark, so that it's no longer located anywhere in the

358.        --  buffer. Remove the reference the buffer holds to the mark, so if

359.        --  you haven't called Ref on the mark, it will be freed. Even

360.        --  if the mark isn't freed, most operations on Mark become

361.        --  invalid. There is no way to undelete a mark.

362.        --  Gtk.Text_Mark.Get_Deleted will return True after this

363.        --  function has been called on a mark; Gtk.Text_Mark.Get_Deleted

364.        --  indicates that a mark no longer belongs to a buffer. The "mark_deleted"

365.        --  signal will be emitted as notification after the mark is deleted.

367.        function Get_MarkTo API docTo body

368.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

369.           Name   : String) return Gtk.Text_Mark.Gtk_Text_MarkTo API docTo spec;

370.        --  Return the mark named Name in Buffer

371.        --  or null if no such mark exists in the buffer.

373.        procedure Move_Mark_By_NameTo API docTo body

374.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

375.           Name   : String;

376.           WhereTo API docTo body  : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

377.        --  Move the mark named Name (which must exist) to location Where.

378.        --  See Move_Mark for details.

380.        procedure Delete_Mark_By_NameTo API docTo body

381.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

382.           Name   : String);

383.        --  Delete the mark named Name

384.        --  The mark must exist. See Delete_Mark for details.

386.        function Get_InsertTo API docTo body

387.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body)

388.           return Gtk.Text_Mark.Gtk_Text_MarkTo API docTo spec;

389.        --  Return the mark that represents the cursor (insertion point).

390.        --  Equivalent to calling Get_Mark to get the mark name "insert", but

391.        --  slightly more efficient, and involves less typing.

393.        function Get_Selection_BoundTo API docTo body

394.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body)

395.           return Gtk.Text_Mark.Gtk_Text_MarkTo API docTo spec;

396.        --  Return the mark that represents the selection bound.

397.        --  Equivalent to calling Get_Mark to get the mark name "selection_bound",

398.        --  but very slightly more efficient, and involves less typing.

399.        --

400.        --  The currently-selected text in Buffer is the region between the

401.        --  "selection_bound" and "insert" marks. If "selection_bound" and

402.        --  "insert" are in the same place, then there is no current selection.

403.        --  Get_Selection_Bounds is another convenient function for handling the

404.        --  selection, if you just want to know whether there's a selection and what

405.        --  its bounds are.

407.        function Get_BufferTo API docTo body

408.          (Mark : Gtk.Text_Mark.Gtk_Text_MarkTo API docTo spec) return Gtk_Text_BufferTo API docTo spec;

409.        --  Return the buffer associated to the given mark

411.        ------------

412.        -- Cursor --

413.        ------------

414.        --  The cursor is a special mark in the buffer

416.        procedure Place_CursorTo API docTo body

417.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

418.           WhereTo API docTo body  : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

419.        --  Move the "insert" and "selection_bound" marks simultaneously.

420.        --  If you move them to the same place in two steps with Move_Mark, you will

421.        --  temporarily select a region in between their old and new locations,

422.        --  which can be pretty inefficient since the temporarily-selected region

423.        --  will force stuff to be recomputed. This function moves them as a unit,

424.        --  which can be optimized.

425.        --

426.        --  If you want to get the position of the cursor, the simplest way is

427.        --      Get_Iter_At_Mark (Buffer, Iter, Get_Insert (Buffer));

429.        --  gtk_text_buffer_create_tag not bound: variable number of arguments

430.        --  ??? Discuss this with the Gtk+ team.

431.        --  equivalent to Gtk_New + Gtk.Text_Tag_Table.Add

433.        ----------

434.        -- Tags --

435.        ----------

436.        --  Tags can be applied to change the properties of a range of text

438.        function Create_TagTo API docTo body

439.          (Buffer              : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

440.           Tag_Name            : String := "")

441.           return Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec;

442.        --  Creates a tag and adds it to the tag table for Buffer. Equivalent to

443.        --  calling gtk.text_tag.gtk_new and then adding the tag to the buffer's tag

444.        --  table. The returned tag is owned by the buffer's tag table, so the ref

445.        --  count will be equal to one.

446.        --

447.        --  If Tag_Name is NULL, the tag is anonymous, otherwise a tag called

448.        --  Tag_Name must not already exist in the tag table for this buffer.

450.        function Get_Tag_TableTo API docTo body

451.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body)

452.           return Gtk.Text_Tag_Table.Gtk_Text_Tag_TableTo API docTo spec;

453.        --  Get the Gtk_Text_Tag_Table associated with this buffer.

455.        procedure Apply_TagTo API docTo body

456.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

457.           Tag     : access Gtk.Text_Tag.Gtk_Text_Tag_RecordTo API docTo specTo body'Class;

458.           StartTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

459.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

460.        --  Emit the "apply_tag" signal on Buffer.

461.        --  The default handler for the signal applies Tag to the given range.

462.        --  Start and End do not have to be in order.

464.        procedure Remove_TagTo API docTo body

465.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

466.           Tag     : access Gtk.Text_Tag.Gtk_Text_Tag_RecordTo API docTo specTo body'Class;

467.           StartTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

468.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

469.        --  Emit the "remove_tag" signal.

470.        --  The default handler for the signal removes all occurrences of Tag from

471.        --  the given range. Start and End don't have to be in order.

473.        procedure Remove_All_TagsTo API docTo body

474.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

475.           StartTo API docTo body    : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

476.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

477.        --  Remove all tags in the range between Start and End.

478.        --  Note that this procedure should be used carefully, as it might be

479.        --  removing tags that were added from another section of the code.

481.        procedure Apply_Tag_By_NameTo API docTo body

482.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

483.           Name    : String;

484.           StartTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

485.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

486.        --  Call Gtk.Text_Tag_Table.Lookup on the buffer's tag table to

487.        --  get a Gtk_Text_Tag, then call Apply_Tag.

489.        procedure Remove_Tag_By_NameTo API docTo body

490.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

491.           Name    : String;

492.           StartTo API docTo body   : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

493.           The_EndTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

494.        --  Call Gtk.Text_Tag_Table.Lookup on the buffer's tag table to

495.        --  get a Gtk_Text_Tag, then call Remove_Tag.

497.        ---------------

498.        -- Iterators --

499.        ---------------

501.        procedure Get_Iter_At_Line_OffsetTo API docTo body

502.          (Buffer      : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

503.           IterTo API docTo body        : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

504.           Line_Number : GintTo API docTo spec;

505.           Char_Offset : GintTo API docTo spec := 0);

506.        --  Obtain an iterator pointing to Char_Offset within the given line. The

507.        --  Char_Offset must exist, offsets off the end of the line are not allowed.

508.        --  Note characters, not bytes; UTF-8 may encode one character as multiple

509.        --  bytes.

510.        --  If the Line_Number is an existing line but the Char_Offset is past the

511.        --  last offset, the iter pointing at the beginning of the line is returned.

512.        --  If the Line_Number is not valid, the behavior is undetermined.

514.        procedure Get_Iter_At_Line_IndexTo API docTo body

515.          (Buffer      : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

516.           IterTo API docTo body        : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

517.           Line_Number : GintTo API docTo spec;

518.           Byte_Index  : GintTo API docTo spec := 0);

519.        --  Obtain an iterator pointing to Byte_Index within the given line.

520.        --  Byte_Index must be the start of a UTF-8 character, and must not be

521.        --  beyond the end of the line. Note bytes, not characters; UTF-8 may encode

522.        --  one character as multiple bytes.

524.        procedure Get_Iter_At_OffsetTo API docTo body

525.          (Buffer      : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

526.           IterTo API docTo body        : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

527.           Char_Offset : GintTo API docTo spec);

528.        --  Initialize Iter to a position Char_Offset chars from the start of the

529.        --  entire buffer.

530.        --  Char_Offset: char offset from start of buffer, counting from 0.

532.        procedure Get_Iter_At_LineTo API docTo body

533.          (Buffer      : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

534.           IterTo API docTo body        : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

535.           Line_Number : GintTo API docTo spec);

536.        --  Initialize Iter to the start of the given line.

537.        --  Line_Number: line number counting from 0.

539.        procedure Get_Start_IterTo API docTo body

540.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

541.           IterTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

542.        --  Initialize Iter with the first position in the text buffer. This is the

543.        --  same as using Get_Iter_At_Offset with Offset set to 0.

545.        procedure Get_End_IterTo API docTo body

546.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

547.           IterTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

548.        --  Initialize Iter with the "end iterator", one past the last valid

549.        --  character in the text buffer. If dereferenced with

550.        --  Gtk.Text_Iter.Get_Char, the end iterator has a character value of 0.

551.        --  The entire buffer lies in the range from the first position in the

552.        --  buffer (call Get_Iter_At_Offset to get character position 0) to the end

553.        --  iterator.

555.        procedure Get_BoundsTo API docTo body

556.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

557.           StartTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

558.           The_EndTo API docTo body : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

559.        --  Retrieve the first and last iterators in the buffer.

560.        --  The entire buffer lies within the range [Start,End).

562.        procedure Get_Iter_At_MarkTo API docTo body

563.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

564.           IterTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

565.           Mark   : access Gtk.Text_Mark.Gtk_Text_Mark_RecordTo API docTo specTo body'Class);

566.        --  Initialize Iter with the current position of Mark.

568.        function Get_BufferTo API docTo body

569.          (IterTo API docTo body : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body) return Gtk_Text_BufferTo API docTo spec;

570.        --  Return the buffer associated to the given Gtk_Text_Iterator.

572.        -------------

573.        -- Widgets --

574.        -------------

575.        --  Widgets can be put in the buffer at specific places. See

576.        --  Gtk.Text_Child

578.        procedure Get_Iter_At_Child_AnchorTo API docTo body

579.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

580.           IterTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

581.           Anchor : access Gtk.Text_Child.Gtk_Text_Child_Anchor_RecordTo API docTo specTo body'Class);

582.        --  Obtains the location of Anchor within Buffer.

584.        procedure Insert_Child_AnchorTo API docTo body

585.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

586.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

587.           Anchor : access Gtk.Text_Child.Gtk_Text_Child_Anchor_RecordTo API docTo specTo body'Class);

588.        --  Insert a child widget anchor into the text buffer at Iter.

589.        --  The anchor will be counted as one character in character counts, and

590.        --  when obtaining the buffer contents as a string, will be represented

591.        --  by the Unicode "object replacement character" 16#FFFC#. Note that the

592.        --  "slice" variants for obtaining portions of the buffer as a string

593.        --  include this character for pixbufs, but the "text" variants do

594.        --  not. e.g. see Get_Slice and Get_Text. Consider Create_Child_Anchor as a

595.        --  more convenient alternative to this function. The buffer will add a

596.        --  reference to the anchor, so you can unref it after insertion.

598.        procedure Create_Child_AnchorTo API docTo body

599.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

600.           IterTo API docTo body   : in out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

601.           Result : out Gtk.Text_Child.Gtk_Text_Child_AnchorTo API docTo spec);

602.        --  Convenience function which simply creates a child anchor with

603.        --  Gtk.Text_Child.Gtk_New and inserts it into the buffer with

604.        --  Insert_Child_Anchor.

605.        --  Result: the created child anchor.

607.        -----------------------------

608.        -- Clipboard and selection --

609.        -----------------------------

611.        procedure Add_Selection_ClipboardTo API docTo body

612.          (Buffer    : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

613.           Clipboard : Gtk.Clipboard.Gtk_ClipboardTo API docTo spec);

614.        --  Adds Clipboard to the list of clipboards in which the selection contents

615.        --  of Buffer are available. In most cases, Clipboard will be the clipboard

616.        --  corresponding to SELECTION_PRIMARY.

617.        --  You generally do not have to call this procedure yourself unless you are

618.        --  creating your own clipboards.

620.        procedure Remove_Selection_ClipboardTo API docTo body

621.          (Buffer    : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

622.           Clipboard : Gtk.Clipboard.Gtk_ClipboardTo API docTo spec);

623.        --  Removes a Clipboard added with Add_Selection_Clipboard

625.        procedure Cut_ClipboardTo API docTo body

626.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

627.           Clipboard        : Gtk.Clipboard.Gtk_ClipboardTo API docTo spec;

628.           Default_Editable : Boolean := True);

629.        --  Copy the currently-selected text to the clipboard, then delete

630.        --  it if editable.

631.        --  Default_Editable: default editability of the buffer.

633.        procedure Copy_ClipboardTo API docTo body

634.          (Buffer     : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

635.           Clipboard  : Gtk.Clipboard.Gtk_ClipboardTo API docTo spec);

636.        --  Copy the currently-selected text to the clipboard.

638.        procedure Paste_ClipboardTo API docTo body

639.          (Buffer            : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

640.           Clipboard         : Gtk.Clipboard.Gtk_ClipboardTo API docTo spec;

641.           Override_Location : Gtk.Text_Iter.Gtk_Text_Iter_AccessTo API docTo spec := null;

642.           Default_Editable  : Boolean := True);

643.        --  Paste the clipboard contents at the insertion point,

644.        --  or at Override_Location if this parameter is not null.

645.        --  (Note: pasting is asynchronous, that is, we'll ask for the paste data

646.        --  and return, and at some point later after the main loop runs, the paste

647.        --  data will be inserted.)

649.        function Selection_ExistsTo API docTo body

650.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body) return Boolean;

651.        --  Return True if some text in the buffer is currently selected.

653.        procedure Select_RangeTo API docTo body

654.          (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

655.           InsTo API docTo body    : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

656.           BoundTo API docTo body  : Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body);

657.        --  This function moves the "insert" and "selection_bound" marks

658.        --  simultaneously. If you move them in two steps with Move_Mark, you will

659.        --  temporarily select region in between their old and new locations, which

660.        --  can be pretty inefficient since the temporarily-selected region will

661.        --  force stuff to be recalculated. This function moves them as a unit,

662.        --  which can be optimized.

664.        procedure Get_Selection_BoundsTo API docTo body

665.          (Buffer  : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

666.           StartTo API docTo body   : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

667.           The_EndTo API docTo body : out Gtk.Text_Iter.Gtk_Text_IterTo API docTo specTo body;

668.           Result  : out Boolean);

669.        --  Place the bounds of the selection in Start and End. If the selection

670.        --  has length 0, then Start and End are filled in with the same value.

671.        --  Start and End will be in ascending order. Result: whether the selection

672.        --  has nonzero length.

674.        function Delete_SelectionTo API docTo body

675.          (Buffer           : access Gtk_Text_Buffer_RecordTo API docTo specTo body;

676.           Interactive      : Boolean;

677.           Default_Editable : Boolean) return Boolean;

678.        --  Delete the range between the "insert" and "selection_bound" marks,

679.        --  that is, the currently-selected text. If Interactive is True,

680.        --  the editability of the selection will be considered (users can't delete

681.        --  uneditable text).

682.        --  Return value: whether there was a non-empty selection to delete.

684.        ------------------

685.        -- User actions --

686.        ------------------

688.        procedure Begin_User_ActionTo API docTo body (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body);

689.        --  Called to indicate that the buffer operations between here and a

690.        --  call to End_User_Action are part of a single user-visible operation.

691.        --  The operations between Begin_User_Action and End_User_Action can then be

692.        --  grouped when creating an undo stack. Gtk_Text_Buffer maintains a count

693.        --  of calls to Begin_User_Action that have not been closed with a call to

694.        --  End_User_Action, and emits the "begin_user_action" and "end_user_action"

695.        --  signals only for the outermost pair of calls.

696.        --  This allows you to build user actions from other user actions.

697.        --

698.        --  The "interactive" buffer mutation functions, such as Insert_Interactive,

699.        --  automatically call begin/end user action around the buffer operations

700.        --  they perform, so there's no need to add extra calls if your user action

701.        --  consists solely of a single call to one of those functions.

703.        procedure End_User_ActionTo API docTo body (Buffer : access Gtk_Text_Buffer_RecordTo API docTo specTo body);

704.        --  Should be paired with a call to Begin_User_Action.

705.        --  See that function for a full explanation.

707.        ----------------

708.        -- Properties --

709.        ----------------

710.        --  <properties>

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

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

713.        --

714.        --  Name:  Tag_Table_Property

715.        --  Type:  Object

716.        --  Descr: Text Tag Table

717.        --

718.        --  Name:  Text_Property

719.        --  Type:  String

720.        --  Descr: Current text of the buffer

721.        --

722.        --  </properties>

724.        Tag_Table_Property : constant Glib.Properties.Property_ObjectTo API docTo spec;

725.        Text_Property      : constant Glib.Properties.Property_StringTo API docTo spec;

727.        -------------

728.        -- Signals --

729.        -------------

730.        --  <signals>

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

732.        --

733.        --  - "insert_text"

734.        --    procedure Handler

735.        --      (Widget : access Gtk_Text_Buffer_Record'Class;

736.        --       Pos    : Gtk.Text_Iter.Gtk_Text_Iter;

737.        --       Text   : UTF8_String;

738.        --       Length : Gint);

739.        --

740.        --  - "insert_pixbuf"

741.        --    procedure Handler

742.        --      (Widget : access Gtk_Text_Buffer_Record'Class;

743.        --       Pos    : Gtk.Text_Iter.Gtk_Text_Iter;

744.        --       Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf);

745.        --

746.        --  - "insert_child_anchor"

747.        --    procedure Handler

748.        --      (Widget : access Gtk_Text_Buffer_Record'Class;

749.        --       Pos    : Gtk.Text_Iter.Gtk_Text_Iter;

750.        --       Anchor : access Gtk.Text_Child.Gtk_Text_Child_Anchor_Record'Class);

751.        --

752.        --  - "delete_range"

753.        --    procedure Handler

754.        --      (Widget  : access Gtk_Text_Buffer_Record'Class;

755.        --       Start   : Gtk.Text_Iter.Gtk_Text_Iter;

756.        --       The_End : Gtk.Text_Iter.Gtk_Text_Iter);

757.        --

758.        --  - "changed"

759.        --    procedure Handler (Widget : access Gtk_Text_Buffer_Record'Class);

760.        --

761.        --  - "modified_changed"

762.        --    procedure Handler (Widget : access Gtk_Text_Buffer_Record'Class);

763.        --

764.        --  - "mark_set"

765.        --    procedure Handler

766.        --      (Widget   : access Gtk_Text_Buffer_Record'Class;

767.        --       Location : Gtk.Text_Iter.Gtk_Text_Iter;

768.        --       Mark     : access Gtk.Text_Mark.Gtk_Text_Mark_Record'Class);

769.        --

770.        --  - "mark_deleted"

771.        --    procedure Handler

772.        --      (Widget : access Gtk_Text_Buffer_Record'Class;

773.        --       Mark   : access Gtk.Text_Mark.Gtk_Text_Mark_Record'Class);

774.        --

775.        --  - "apply_tag"

776.        --    procedure Handler

777.        --      (Widget     : access Gtk_Text_Buffer_Record'Class;

778.        --       Tag        : access Gtk.Text_Tag.Gtk_Text_Tag_Record'Class;

779.        --       Start_Char : Gtk.Text_Iter.Gtk_Text_Iter;

780.        --       End_Char   : Gtk.Text_Iter.Gtk_Text_Iter);

781.        --

782.        --  - "remove_tag"

783.        --    procedure Handler

784.        --      (Widget     : access Gtk_Text_Buffer_Record'Class;

785.        --       Tag        : access Gtk.Text_Tag.Gtk_Text_Tag_Record'Class;

786.        --       Start_Char : Gtk.Text_Iter.Gtk_Text_Iter;

787.        --       End_Char   : Gtk.Text_Iter.Gtk_Text_Iter);

788.        --

789.        --  - "begin_user_action"

790.        --    procedure Handler (Widget : access Gtk_Text_Buffer_Record'Class);

791.        --

792.        --  - "end_user_action"

793.        --    procedure Handler (Widget : access Gtk_Text_Buffer_Record'Class);

794.        --

795.        --  </signals>

797.        Signal_Apply_Tag           : constant Glib.Signal_NameTo API docTo spec :=

798.                                       "apply_tag";

799.        Signal_Begin_User_Action   : constant Glib.Signal_NameTo API docTo spec :=

800.                                       "begin_user_action";

801.        Signal_Changed             : constant Glib.Signal_NameTo API docTo spec :=

802.                                       "changed";

803.        Signal_Delete_Range        : constant Glib.Signal_NameTo API docTo spec :=

804.                                       "delete_range";

805.        Signal_End_User_Action     : constant Glib.Signal_NameTo API docTo spec :=

806.                                       "end_user_action";

807.        Signal_Insert_Child_Anchor : constant Glib.Signal_NameTo API docTo spec :=

808.                                       "insert_child_anchor";

809.        Signal_Insert_Pixbuf       : constant Glib.Signal_NameTo API docTo spec :=

810.                                       "insert_pixbuf";

811.        Signal_Insert_Text         : constant Glib.Signal_NameTo API docTo spec :=

812.                                       "insert_text";

813.        Signal_Mark_Deleted        : constant Glib.Signal_NameTo API docTo spec :=

814.                                       "mark_deleted";

815.        Signal_Mark_Set            : constant Glib.Signal_NameTo API docTo spec :=

816.                                       "mark_set";

817.        Signal_Modified_Changed    : constant Glib.Signal_NameTo API docTo spec :=

818.                                       "modified_changed";

819.        Signal_Remove_Tag          : constant Glib.Signal_NameTo API docTo spec :=

820.                                       "remove_tag";

822.     private

823.        type Gtk_Text_Buffer_RecordTo API docTo spec is new GObject_RecordTo API docTo specTo body with null record;

825.        Tag_Table_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

826.          Glib.Properties.BuildTo API docTo specTo body ("tag-table");

827.        Text_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

828.          Glib.Properties.BuildTo API docTo specTo body ("text");

830.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_text_buffer_get_type");

831.     end Gtk.Text_BufferTo API docTo specTo body;

833.     --  No binding: gtk_text_buffer_create_tag

834.     --  No binding: gtk_text_buffer_insert_with_tags

835.     --  No binding: gtk_text_buffer_insert_with_tags_by_name