## 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.     --  A Gtk_Text_Iter represents a location in the text. It becomes invalid if

31.     --  the characters/pixmaps/widgets (indexable objects) in the text buffer

32.     --  are changed.

33.     --  </description>

34.     --  <c_version>2.8.17</c_version>

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

37.     with Gdk.PixbufTo API docTo specTo body;

38.     with Glib.ObjectTo API docTo specTo body;

39.     with Glib.ValuesTo API docTo specTo body;

40.     with Gtk.Text_AttributesTo API docTo specTo body;

41.     with Gtk.Text_ChildTo API docTo specTo body;

42.     with Gtk.Text_TagTo API docTo specTo body;

43.     with Interfaces.C.Strings;

44.     with System;

46.     package Gtk.Text_IterTo API docTo specTo body is

48.        type Gtk_Text_IterTo API docTo body is limited private;

49.        type Gtk_Text_Iter_Access is access all Gtk_Text_IterTo API docTo specTo body;

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

52.        --  Return the internal type used for a Gtk_Text_Iter

54.        procedure CopyTo API docTo body (SourceTo API docTo body : Gtk_Text_IterTo API docTo specTo body; DestTo API docTo body : out Gtk_Text_IterTo API docTo specTo body);

55.        --  Create a copy of Source.

57.        --------------------------

58.        -- Characters and bytes --

59.        --------------------------

60.        --  The basic component of a Gtk_Text_Buffer is a character. Since these are

61.        --  encoded in Unicode's UTF8, a character can be stored as multiple bytes

62.        --  in fact, and gtk+ therefore provides function to either take bytes or

63.        --  characters into account. The latter is generally the form that you

64.        --  should use in your applications

66.        procedure Forward_CharTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

67.        --  Move Iter forward by one character offset.

68.        --  Note that images embedded in the buffer occupy 1 character slot, so

69.        --  Forward_Char may actually move onto an image instead of a character, if

70.        --  you have images in your buffer. If Iter is the end iterator or one

71.        --  character before it, Iter will now point at the end iterator, and

72.        --  Forward_Char returns False for convenience when writing loops.

74.        procedure Backward_CharTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

75.        --  Move backward by one character offset.

76.        --  Return True if movement was possible; if Iter was the first in the

77.        --  buffer (character offset 0), return False for convenience when writing

78.        --  loops.

80.        procedure Forward_CharsTo API docTo body

81.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

82.           Count  : GintTo API docTo spec := 1;

83.           Result : out Boolean);

84.        --  Move Count characters if possible.

85.        --  If Count would move past the start or end of the buffer, move to the

86.        --  start or end of the buffer). Result indicates whether the new position

87.        --  of Iter is different from its original position, and dereferenceable

88.        --  (the last iterator in the buffer is not dereferenceable). If Count

89.        --  is 0, this procedure does nothing and returns False.

91.        procedure Backward_CharsTo API docTo body

92.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

93.           Count  : GintTo API docTo spec := 1;

94.           Result : out Boolean);

95.        --  Move Count characters backward, if possible.

96.        --  If Count would move past the start or end of the buffer, moves to the

97.        --  start or end of the buffer). Result indicates whether the iterator moved

98.        --  onto a dereferenceable position; if the iterator didn't move, or moved

99.        --  onto the end iterator, then False is returned. If Count is 0, the

100.        --  function does nothing and returns False.

102.        procedure Set_OffsetTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Char_Offset : GintTo API docTo spec);

103.        function  Get_OffsetTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

104.        --  Set or return the character offset of an iterator.

105.        --  Each character in a Gtk_Text_Buffer has an offset, starting with 0 for

106.        --  the first character in the buffer.

107.        --  Use Gtk.Text_Buffer.Get_Iter_At_Offset to convert an offset back into an

108.        --  iterator.

110.        -----------

111.        -- Words --

112.        -----------

113.        --  Characters are grouped together into words. Their exact definition

114.        --  depends on the current language (see Pango.Language).

116.        function Starts_WordTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

117.        --  Determine whether Iter begins a natural-language word.

118.        --  Word breaks are determined by Pango and should be correct for nearly any

119.        --  language (if not, the correct fix would be to the Pango word break

120.        --  algorithms.

122.        function Ends_WordTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

123.        --  Determine whether Iter ends a natural-language word.

124.        --  Word breaks are determined by Pango and should be correct for nearly any

125.        --  language (if not, the correct fix would be to the Pango word break

126.        --  algorithms).

128.        function Inside_WordTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

129.        --  Determine whether Iter is inside a natural-language word (as opposed to

130.        --  say inside some whitespace). Word breaks are determined by Pango and

131.        --  should be correct for nearly any language (if not, the correct fix would

132.        --  be to the Pango word break algorithms).

134.        procedure Forward_Word_EndTo API docTo body

135.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

136.        --  Move forward to the next word end.

137.        --  If Iter is currently on a word end, move forward to the next one after

138.        --  that. Word breaks are determined by Pango and should be correct for

139.        --  nearly any language (if not, the correct fix would be to the Pango word

140.        --  break algorithms).

142.        procedure Forward_Word_EndsTo API docTo body

143.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

144.           Count  : GintTo API docTo spec := 1;

145.           Result : out Boolean);

146.        --  Call Forward_Word_End up to Count times.

148.        procedure Forward_Visible_Word_EndTo API docTo body

149.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

150.        --  Moves forward to the next visible word end. (If Iter is currently on

151.        --  word end, moves forward to the next one after that.) Word breaks are

152.        --  determined by Pango and should be correct for nearly any language (if

153.        --  not, the correct fix would be to the Pango word break algorithms).

155.        procedure Forward_Visible_Word_EndsTo API docTo body

156.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

157.           Count  : GintTo API docTo spec := 1;

158.           Result : out Boolean);

159.        --  Calls Forward_Visible_Word_End up to Count times

161.        procedure Backward_Word_StartTo API docTo body

162.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

163.        --  Move backward to the next word start.

164.        --  If Iter is currently on a word start, move backward to the next one

165.        --  after that.

167.        procedure Backward_Word_StartsTo API docTo body

168.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

169.           Count  : GintTo API docTo spec := 1;

170.           Result : out Boolean);

171.        --  Call Backward_Word_Start up to Count times.

173.        procedure Backward_Visible_Word_StartTo API docTo body

174.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

175.        --  Moves backward to the previous visible word start. (If Iter is currently

176.        --  on a word start, moves backward to the next one after that.) Word breaks

177.        --  are determined by Pango and should be correct for nearly any language

178.        --  (if not, the correct fix would be to the Pango word break algorithms).

180.        procedure Backward_Visible_Word_StartsTo API docTo body

181.          (IterTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

182.           Count  : GintTo API docTo spec := 1;

183.           Result : in out Boolean);

184.        --  Move backward up to Count previous visible word starts.

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

187.        -- Sentences --

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

189.        --  Words are then grouped together into sentences.

191.        function Starts_SentenceTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

192.        --  Determine whether Iter begins a sentence.

193.        --  Sentence boundaries are determined by Pango and should be correct for

194.        --  nearly any language (if not, the correct fix would be to the Pango text

195.        --  boundary algorithms).

197.        function Ends_SentenceTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

198.        --  Determine whether Iter ends a sentence.

199.        --  Sentence boundaries are determined by Pango and should be correct for

200.        --  nearly any language (if not, the correct fix would be to the Pango text

201.        --  boundary algorithms).

203.        function Inside_SentenceTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

204.        --  Determine whether Iter is inside a sentence (as opposed to in between

205.        --  two sentences, e.g. after a period and before the first letter of the

206.        --  next sentence). Sentence boundaries are determined by Pango and should

207.        --  be correct for nearly any language (if not, the correct fix would be to

208.        --  the Pango text boundary algorithms).

210.        procedure Forward_Sentence_EndTo API docTo body

211.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

212.        --  Move forward to the next sentence end.

213.        --  If Iter is at the end of a sentence, move to the next end of sentence.

215.        procedure Backward_Sentence_StartTo API docTo body

216.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

217.        --  Move backward to the next sentence start.

218.        --  If Iter is already at the start of a sentence, move backward to the next

219.        --  one.

221.        procedure Forward_Sentence_EndsTo API docTo body

222.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

223.           Count  : GintTo API docTo spec := 1;

224.           Result : out Boolean);

225.        --  Call Forward_Sentence_End up to Count times.

227.        procedure Backward_Sentence_StartsTo API docTo body

228.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

229.           Count  : GintTo API docTo spec := 1;

230.           Result : out Boolean);

231.        --  Call Backward_Sentence_Starts up to Count times.

233.        --------------------------

234.        -- Lines and paragraphs --

235.        --------------------------

236.        --  Sentences are grouped together to form lines and paragraphs. The

237.        --  definition of these is language-dependent

239.        procedure Set_LineTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Line_Number : GintTo API docTo spec);

240.        function  Get_LineTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

241.        --  Set or return the line number containing the iterator.

242.        --  Lines in a Gtk_Text_Buffer are numbered beginning with 0 for the first

243.        --  line in the buffer.

245.        procedure Set_Line_OffsetTo API docTo body

246.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Char_On_Line : GintTo API docTo spec);

247.        function Get_Line_OffsetTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

248.        --  Move Iter within a line, to a new character (not byte) offset.

249.        --  The given character offset must be less than or equal to the number of

250.        --  characters in the line; if equal, Iter moves to the start of the next

251.        --  line. See Set_Line_Index if you have a byte index rather than a

252.        --  character offset.

253.        --  The first character on the line has offset 0.

255.        procedure Set_Line_IndexTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Byte_On_Line : GintTo API docTo spec);

256.        function Get_Line_IndexTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

257.        --  Same as Set_Line_Offset, but work with a byte index.

258.        --  The given byte index must be at the start of a character, it can't be in

259.        --  the middle of a UTF-8 encoded character.

260.        --  Remember that Gtk_Text_Buffer encodes text in UTF-8, and that characters

261.        --  can require a variable number of bytes to represent.

263.        procedure Set_Visible_Line_OffsetTo API docTo body

264.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Char_On_Line : GintTo API docTo spec);

265.        function Get_Visible_Line_OffsetTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

266.        --  Sets or returns the offset in characters from the start of the line to

267.        --  the given Iter, not counting characters that are invisible due to tags

268.        --  with the "invisible" flag toggled on.

270.        procedure Set_Visible_Line_IndexTo API docTo body

271.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Byte_On_Line : GintTo API docTo spec);

272.        function Get_Visible_Line_IndexTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

273.        --  Set or returns the number of bytes from the start of the line to the

274.        --  given Iter, not counting bytes that are invisible due to tags with the

275.        --  "invisible" flag toggled on.

277.        function Starts_LineTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

278.        --  Return True if Iter begins a paragraph. i.e. if Get_Line_Offset would

279.        --  return 0.

280.        --  However this function is potentially more efficient than

281.        --  Get_Line_Offset because it doesn't have to compute the offset, it just

282.        --  has to see whether it's 0.

284.        function Ends_LineTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

285.        --  Return True if Iter points to the start of the paragraph delimiter

286.        --  characters for a line (delimiters will be either a newline, a carriage

287.        --  return, a carriage return followed by a newline, or a Unicode paragraph

288.        --  separator character). Note that an iterator pointing to the ASCII.LF of

289.        --  a ASCII.CR & ASCII.LF pair will not be counted as the end of a line, the

290.        --  line ends before the ASCII.CR.

292.        function Get_Chars_In_LineTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

293.        --  Return the number of characters in the line containing Iter, including

294.        --  the paragraph delimiters.

296.        function Get_Bytes_In_LineTo API docTo body (Iter : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

297.        --  Return the number of bytes in the line containing Iter, including the

298.        --  paragraph delimiters.

300.        procedure Forward_LineTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

301.        --  Move Iter to the start of the next line.

302.        --  Return True if there was a next line to move to, and False if iter was

303.        --  simply moved to the end of the buffer and is now not dereferenceable, or

304.        --  if Iter was already at the end of the buffer.

306.        procedure Forward_LinesTo API docTo body

307.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

308.           Count  : GintTo API docTo spec := 1;

309.           Result : out Boolean);

310.        --  Call Forward_Line, up to Count times.

312.        procedure Forward_Visible_LineTo API docTo body

313.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

314.        --  Moves Iter to the start of the next visible line. Returns True if there

315.        --  was a next line to move to, and False if Iter was simply moved to the

316.        --  end of the buffer and is now not dereferenceable, or if Iter was already

317.        --  at the end of the buffer.

319.        procedure Forward_Visible_LinesTo API docTo body

320.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

321.           Count  : GintTo API docTo spec := 1;

322.           Result : out Boolean);

323.        --  Moves Count visible lines forward, if possible (if Count would move

324.        --  past the start or end of the buffer, moves to the start or end of

325.        --  the buffer).  The return value indicates whether the iterator moved

326.        --  onto a dereferenceable position; if the iterator didn't move, or

327.        --  moved onto the end iterator, then False is returned. If Count is 0,

328.        --  the function does nothing and returns False. If Count is negative,

329.        --  moves backward by 0 - Count lines.

331.        procedure Forward_To_Line_EndTo API docTo body

332.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

333.        --  Move the iterator to point to the paragraph delimiter characters,

334.        --  which will be either a newline, a carriage return, a carriage

335.        --  return/newline in sequence, or the Unicode paragraph separator

336.        --  character. If the iterator is already at the paragraph delimiter

337.        --  characters, move to the paragraph delimiter characters for the next

338.        --  line.

340.        procedure Backward_LineTo API docTo body (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

341.        --  Move Iter to the start of the previous line.

342.        --  Return True if Iter could be moved; i.e. if Iter was at character offset

343.        --  0, this function returns False. Therefore if Iter was already on line 0,

344.        --  but not at the start of the line, Iter is snapped to the start of the

345.        --  line and the function returns True. (Note that this implies that in a

346.        --  loop calling this function, the line number may not change on every

347.        --  iteration, if your first iteration is on line 0)

349.        procedure Backward_LinesTo API docTo body

350.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

351.           Count  : GintTo API docTo spec := 1;

352.           Result : out Boolean);

353.        --  Call Backward_Line, up to Count times.

355.        procedure Backward_Visible_LineTo API docTo body

356.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

357.        --  Moves Iter to the start of the previous visible line. Returns True if

358.        --  Iter could be moved; i.e. if Iter was at character offset 0, this

359.        --  function returns False. Therefore if Iter was already on line 0, but not

360.        --  at the start of the line, Iter is snapped to the start of the line and

361.        --  the function returns True. (Note that this implies that in a loop

362.        --  calling this function, the line number may not change on every

363.        --  iteration, if your first iteration is on line 0.)

365.        procedure Backward_Visible_LinesTo API docTo body

366.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

367.           Count  : GintTo API docTo spec := 1;

368.           Result : out Boolean);

369.        --  Moves Count visible lines backward, if possible (if Count would move

370.        --  past the start or end of the buffer, moves to the start or end of the

371.        --  buffer). The return value indicates whether the iterator moved onto a

372.        --  dereferenceable position; if the iterator didn't move, or moved onto the

373.        --  end iterator, then False is returned. If Count is 0, the function does

374.        --  nothing and returns False. If Count is negative, moves forward by 0 -

375.        --  Count lines.

377.        ------------

378.        -- Buffer --

379.        ------------

380.        --  When grouped together, lines and paragraph made up the whole buffer.

382.        function Is_EndTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

383.        --  Return True if Iter is the end iterator.

384.        --  i.e. one past the last dereferenceable iterator in the buffer.

385.        --  This is the most efficient way to check whether an iterator is the end

386.        --  iterator.

388.        function Is_StartTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

389.        --  Return True if Iter is the first iterator in the buffer, that is

390.        --  if Iter has a character offset of 0.

392.        procedure Forward_To_EndTo API docTo body (Iter : in out Gtk_Text_IterTo API docTo specTo body);

393.        --  Move Iter forward to the "end iterator", which points one past the last

394.        --  valid character in the buffer. Get_Char called on the end iterator

395.        --  returns 0, which is convenient for writing loops.

397.        -----------------------------

398.        -- Reading buffer contents --

399.        -----------------------------

401.        function Get_CharTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return GunicharTo API docTo spec;

402.        --  Return the character immediately following Iter. If Iter is at the

403.        --  end of the buffer, then return ASCII.NUL.

405.        function Get_CharTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Character;

406.        --  Return the character immediately following Iter. If Iter is at the

407.        --  end of the buffer, then return ASCII.NUL.

408.        --  Note that this function assumes that the text is encoded in ASCII

409.        --  format. If this is not the case, use the Get_Char function that

410.        --  returns a Gunichar instead.

412.        function Get_SliceTo API docTo body

413.          (StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

414.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return UTF8_StringTo API docTo spec;

415.        --  Return the text in the given range.

416.        --  A "slice" is an array of characters encoded in UTF-8 format, including

417.        --  the Unicode "unknown" character 16#FFFC# for iterable non-character

418.        --  elements in the buffer, such as images. Because images are encoded in

419.        --  the slice, byte and character offsets in the returned array will

420.        --  correspond to byte offsets in the text buffer. Note that 16#FFFC# can

421.        --  occur in normal text as well, so it is not a reliable indicator that a

422.        --  pixbuf or widget is in the buffer.

424.        function Get_SliceTo API docTo body

425.          (StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

426.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Interfaces.C.Strings.chars_ptr;

427.        --  Same as above, but returns the row C string.

428.        --  The caller is responsible for freeing the string returned.

430.        function Get_TextTo API docTo body

431.          (StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

432.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return UTF8_StringTo API docTo spec;

433.        --  Return text in the given range.

434.        --  If the range contains non-text elements such as images, the character

435.        --  and byte offsets in the returned string will not correspond to character

436.        --  and byte offsets in the buffer. If you want offsets to correspond, see

437.        --  Get_Slice.

439.        function Get_Visible_SliceTo API docTo body

440.          (StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

441.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return UTF8_StringTo API docTo spec;

442.        --  Like Get_Slice, but invisible text is not included.

443.        --  Invisible text is usually invisible because a Gtk_Text_Tag with the

444.        --  "invisible" attribute turned on has been applied to it.

446.        function Get_Visible_TextTo API docTo body

447.          (StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

448.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return UTF8_StringTo API docTo spec;

449.        --  Like Get_Text, but invisible text is not included.

450.        --  Invisible text is usually invisible because a Gtk_Text_Tag with the

451.        --  "invisible" attribute turned on has been applied to it.

453.        function Get_PixbufTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

454.        --  If the location pointed to by Iter contains a pixbuf, the pixbuf

455.        --  is returned (with no new reference count added). Otherwise, null is

456.        --  returned.

458.        ----------

459.        -- Tags --

460.        ----------

461.        --  Iterators can be used to move among tags. These tags are used to

462.        --  set some specific attributes on the text.

464.        function Begins_TagTo API docTo body

465.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body;

466.           Tag  : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null) return Boolean;

467.        --  Return True if Tag is toggled on at exactly this point.

468.        --  If Tag is null, return True if any tag is toggled on at this point.

469.        --  Return True if Iter is the start of the tagged range;

470.        --  Has_Tag tells you whether an iterator is within a tagged range.

472.        function Ends_TagTo API docTo body

473.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body;

474.           Tag  : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null) return Boolean;

475.        --  Return True if Tag is toggled off at exactly this point.

476.        --  If Tag is null, return True if any tag is toggled off at this point.

477.        --  Note that the Ends_Tag return True if Iter is the end of the tagged

478.        --  range; Has_Tag tells you whether an iterator is within a tagged range.

480.        function Toggles_TagTo API docTo body

481.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body;

482.           Tag  : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null) return Boolean;

483.        --  Whether a range with Tag applied to it begins or ends at Iter.

484.        --  Equivalent to "Begins_Tag (Iter, Tag) or else Ends_Tag (Iter, Tag)".

486.        function Has_TagTo API docTo body

487.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body;

488.           Tag  : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null) return Boolean;

489.        --  Return True if Iter is within a range tagged with Tag.

491.        function Get_TagsTo API docTo body

492.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Gtk.Text_Tag.Text_Tag_List.GSlistTo API docTo specTo body;

493.        --  Return a list of tags that apply to Iter, in ascending order of priority

494.        --  (highest-priority tags are last). The Gtk_Text_Tag in the list don't

495.        --  have a reference added, but you have to free the list itself.

497.        procedure Forward_To_Tag_ToggleTo API docTo body

498.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

499.           Tag    : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null;

500.           Result : out Boolean);

501.        --  Move forward to the next toggle (on or off) of the Gtk_Text_Tag Tag, or

502.        --  to the next toggle of any tag if Tag is null. If no matching tag toggles

503.        --  are found, return False, otherwise True. Do not return toggles located

504.        --  at Iter, only toggles after Iter. Set Iter to the location of the

505.        --  toggle, or to the end of the buffer if no toggle is found.

507.        procedure Backward_To_Tag_ToggleTo API docTo body

508.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

509.           Tag    : Gtk.Text_Tag.Gtk_Text_TagTo API docTo spec := null;

510.           Result : out Boolean);

511.        --  Move backward to the next toggle (on or off) of the Gtk_Text_Tag Tag,

512.        --  or to the next toggle of any tag if Tag is null. If no matching tag

513.        --  toggles are found, return False, otherwise True. Do not return toggles

514.        --  located at Iter, only toggles before Iter. Set Iter to the location of

515.        --  the toggle, or the start of the buffer if no toggle is found.

517.        function Get_Toggled_TagsTo API docTo body

518.          (IterTo API docTo body       : Gtk_Text_IterTo API docTo specTo body;

519.           Toggled_On : Boolean)

520.           return Glib.Object.Object_List.GSlistTo API docTo specTo body;

521.        --  Returns a list of #GtkTextTag that are toggled on or off at this point.

522.        --  (If Toggled_On is True, the list contains tags that are toggled on.) If

523.        --  a tag is toggled on at Iter, then some non-empty range of characters

524.        --  following Iter has that tag applied to it. If a tag is toggled off, then

525.        --  some non-empty range following Iter does not have the tag applied to it.

526.        --  The returned list should be freed by the caller.

528.        ----------------

529.        -- Attributes --

530.        ----------------

531.        --  The tags are used to change the attributes of parts of the buffer. For

532.        --  convenience, a number of wrapper subprograms are provided to make the

533.        --  use of tags easier.

535.        function EditableTo API docTo body

536.          (IterTo API docTo body            : Gtk_Text_IterTo API docTo specTo body;

537.           Default_Setting : Boolean := True) return Boolean;

538.        --  Return whether Iter is within an editable region of text.

539.        --  Non-editable text is "locked" and can't be changed by the user via

540.        --  Gtk_Text_View. This function is simply a convenience wrapper around

541.        --  Get_Attributes. If no tags applied to this text affect editability,

542.        --  Default_Setting will be returned.

544.        function Can_InsertTo API docTo body

545.          (IterTo API docTo body                : Gtk_Text_IterTo API docTo specTo body;

546.           Default_Editability : Boolean) return Boolean;

547.        --  Return whether text inserted at Iter would be editable.

548.        --  Considering the default editability of the buffer, and tags that

549.        --  affect editability, determines whether text inserted at Iter would

550.        --  be editable. If text inserted at Iter would be editable then the

551.        --  user should be allowed to insert text at Iter.

552.        --  Gtk.Text_Buffer.Insert_Interactive uses this function to decide

553.        --  whether insertions are allowed at a given position.

555.        function Get_LanguageTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return UTF8_StringTo API docTo spec;

556.        --  A convenience wrapper around Get_Attributes,

557.        --  which returns the language in effect at Iter. If no tags affecting

558.        --  language apply to Iter, the return value is identical to that of

559.        --  Gtk.Get_Default_Language.

561.        procedure Get_AttributesTo API docTo body

562.          (IterTo API docTo body     : Gtk_Text_IterTo API docTo specTo body;

563.           Values   : in out Gtk.Text_Attributes.Gtk_Text_AttributesTo API docTo spec;

564.           Modified : out Boolean);

565.        --  Computes the effect of any tags applied to this spot in the text. The

566.        --  Values parameter should be initialized to the default settings you wish

567.        --  to use if no tags are in effect. You'd typically obtain the defaults

568.        --  from gtk.text_view.get_default_attributes.

569.        --

570.        --  Get_Attributes will modify Values, applying the effects of any tags

571.        --  present at Iter. If any tags affected Values, the function returns True.

573.        ------------

574.        -- Cursor --

575.        ------------

576.        --  The cursor is a special position in the buffer that indicates where the

577.        --  user will interactively insert new characters. In some languages, you

578.        --  can put the cursor between certain chars. Also you can't put the cursor

579.        --  between \r and \n on Windows-line ending files.

581.        function Is_Cursor_PositionTo API docTo body (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

582.        --  Return True if the cursor can be placed at Iter.

583.        --  See Forward_Cursor_Position for details on what a cursor position is.

585.        procedure Forward_Cursor_PositionTo API docTo body

586.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

587.        --  Move Iter forward by a single cursor position.

588.        --  Cursor positions are (unsurprisingly) positions where the cursor can

589.        --  appear. Perhaps surprisingly, there may not be a cursor position between

590.        --  all characters. The most common example for European languages would be

591.        --  a carriage return/newline sequence. For some Unicode characters, the

592.        --  equivalent of say the letter "a" with an accent mark will be represented

593.        --  as two characters, first the letter then a "combining mark" that causes

594.        --  the accent to be rendered; so the cursor can't go between those two

595.        --  characters.

597.        procedure Backward_Cursor_PositionTo API docTo body

598.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

599.        --  Like Forward_Cursor_Position, but moves backward.

601.        procedure Forward_Cursor_PositionsTo API docTo body

602.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

603.           Count  : GintTo API docTo spec := 1;

604.           Result : out Boolean);

605.        --  Call Forward_Cursor_Position up to Count times.

607.        procedure Forward_Visible_Cursor_PositionTo API docTo body

608.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body; Result : out Boolean);

609.        --  Moves Iter forward to the next visible cursor position. Return True if

610.        --  the new position is valid

612.        procedure Forward_Visible_Cursor_PositionsTo API docTo body

613.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

614.           Count  : GintTo API docTo spec := 1;

615.           Result : out Boolean);

616.        --  Moves up to Count visible cursor positions. See Forward_Cursor_Position

617.        --  for details. Return True if the cursor could be moved.

619.        procedure Backward_Cursor_PositionsTo API docTo body

620.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

621.           Count  : GintTo API docTo spec := 1;

622.           Result : out Boolean);

623.        --  Call Backward_Cursor_Position up to Count times.

625.        procedure Backward_Visible_Cursor_PositionTo API docTo body

626.          (IterTo API docTo body : in out Gtk_Text_IterTo API docTo specTo body;  Result : out Boolean);

627.        --  Moves Iter backward to the previous visible cursor position. Return

628.        --  True if the new position is valid.

630.        procedure Backward_Visible_Cursor_PositionsTo API docTo body

631.          (IterTo API docTo body   : in out Gtk_Text_IterTo API docTo specTo body;

632.           Count  : GintTo API docTo spec := 1;

633.           Result : out Boolean);

634.        --  Moves up to Count visible cursor positions. Return True if the new

635.        --  position is valid.

637.        --------------

638.        -- Children --

639.        --------------

640.        --  The buffer can contain many widgets. They are all attached to specific

641.        --  anchors (see Gtk.Text_Child)

643.        function Get_Child_AnchorTo API docTo body

644.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body)

645.           return Gtk.Text_Child.Gtk_Text_Child_AnchorTo API docTo spec;

646.        --  If the location pointed to by Iter contains a child anchor, the anchor

647.        --  is returned (with no new reference count added). Otherwise, null is

648.        --  returned.

650.        function Get_MarksTo API docTo body

651.          (IterTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Glib.Object.Object_List.GSlistTo API docTo specTo body;

652.        --  Returns a list of all Gtk_Text_Mark at this location. Because marks are

653.        --  not iterable (they don't take up any "space" in the buffer, they are

654.        --  just marks in between iterable locations), multiple marks can exist in

655.        --  the same place. The returned list is not in any meaningful order.

657.        ---------------

658.        -- Searching --

659.        ---------------

661.        type Gtk_Text_Search_Flags is mod 2 ** 8;

662.        for Gtk_Text_Search_FlagsTo API docTo spec'Size use GintTo API docTo spec'Size;

664.        Visible_Only : constant Gtk_Text_Search_FlagsTo API docTo spec := 2 ** 0;

665.        Text_Only    : constant Gtk_Text_Search_FlagsTo API docTo spec := 2 ** 1;

667.        procedure Forward_SearchTo API docTo body

668.          (IterTo API docTo body         : Gtk_Text_IterTo API docTo specTo body;

669.           Str          : UTF8_StringTo API docTo spec;

670.           Flags        : Gtk_Text_Search_FlagsTo API docTo spec;

671.           Match_StartTo API docTo body  : out Gtk_Text_IterTo API docTo specTo body;

672.           Match_EndTo API docTo body    : out Gtk_Text_IterTo API docTo specTo body;

673.           LimitTo API docTo body        : Gtk_Text_IterTo API docTo specTo body;

674.           Result       : out Boolean);

675.        --  Search forward for Str.

676.        --  Any match is returned as the range Match_Start, Match_End. If you

677.        --  specify Visible_Only or Slice, the match may have invisible text,

678.        --  pixbufs, or child widgets interspersed in Str.

679.        --  Iter: start of search

680.        --  Str: a search string

681.        --  Match_Start: return location for start of match, or null

682.        --  Match_End: return location for end of match, or null

683.        --  Limit: bound for the search, or null for the end of the buffer

684.        --  Result: whether a match was found.

686.        procedure Backward_SearchTo API docTo body

687.          (IterTo API docTo body         : Gtk_Text_IterTo API docTo specTo body;

688.           Str          : UTF8_StringTo API docTo spec;

689.           Flags        : Gtk_Text_Search_FlagsTo API docTo spec;

690.           Match_StartTo API docTo body  : out Gtk_Text_IterTo API docTo specTo body;

691.           Match_EndTo API docTo body    : out Gtk_Text_IterTo API docTo specTo body;

692.           LimitTo API docTo body        : Gtk_Text_IterTo API docTo specTo body;

693.           Result       : out Boolean);

694.        --  Same as Forward_Search, but move backward.

696.        generic

697.           type Data_Type (<>) is private;

698.        package Find_CharsTo API docTo body is

699.           type Gtk_Text_Char_Predicate is access function

700.             (Ch : GunicharTo API docTo spec; User_Data : Data_TypeTo API docTo spec) return Boolean;

702.           function Forward_Find_CharTo API docTo body

703.             (IterTo API docTo body      : Gtk_Text_IterTo API docTo specTo body;

704.              Pred      : Gtk_Text_Char_PredicateTo API docTo spec;

705.              User_Data : Data_TypeTo API docTo spec;

706.              LimitTo API docTo body     : Gtk_Text_IterTo API docTo specTo body) return Boolean;

707.           --  Advances Iter, calling Pred on each character. If Pred returns True,

708.           --  returns True and stops scanning. If Pred never returns True, Iter is

709.           --  set to Limit if Limit is not Null_Iter, otherwise to the end

710.           --  iterator.

712.           function Backward_Find_CharTo API docTo body

713.             (IterTo API docTo body      : Gtk_Text_IterTo API docTo specTo body;

714.              Pred      : Gtk_Text_Char_PredicateTo API docTo spec;

715.              User_Data : Data_TypeTo API docTo spec;

716.              LimitTo API docTo body     : Gtk_Text_IterTo API docTo specTo body) return Boolean;

717.           --  Same as Forward_Find_Char, but goes backward from Iter

718.        end Find_CharsTo API docTo specTo body;

720.        -----------------

721.        -- Comparisons --

722.        -----------------

724.        function EqualTo API docTo body (LhsTo API docTo body : Gtk_Text_IterTo API docTo specTo body; RhsTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

725.        --  Test whether two iterators are equal, using the fastest possible

726.        --  mechanism. This function is very fast; you can expect it to perform

727.        --  better than e.g. getting the character offset for each iterator and

728.        --  comparing the offsets yourself. Also, it's a bit faster than Compare.

730.        function CompareTo API docTo body (Lhs : Gtk_Text_IterTo API docTo specTo body; Rhs : Gtk_Text_IterTo API docTo specTo body) return GintTo API docTo spec;

731.        --  A quick sort-style function that return negative if Lhs is less than

732.        --  Rhs, positive if Lhs is greater than Rhs, and 0 if they're equal.

733.        --  Ordering is in character offset order, i.e. the first character in the

734.        --  buffer is less than the second character in the buffer.

736.        function In_RangeTo API docTo body

737.          (IterTo API docTo body    : Gtk_Text_IterTo API docTo specTo body;

738.           StartTo API docTo body   : Gtk_Text_IterTo API docTo specTo body;

739.           The_EndTo API docTo body : Gtk_Text_IterTo API docTo specTo body) return Boolean;

740.        --  Start and End must be in order, unlike most text buffer functions, for

741.        --  efficiency reasons. Return True if Iter falls in the range [Start, End)

743.        procedure OrderTo API docTo body

744.          (First  : in out Gtk_Text_IterTo API docTo specTo body;

745.           Second : in out Gtk_Text_IterTo API docTo specTo body);

746.        --  Swap the value of First and Second if Second comes before First in the

747.        --  buffer. That is, ensures that First and Second are in sequence. Most

748.        --  text buffer functions that take a range call this automatically on your

749.        --  behalf, so there's no real reason to call it yourself in those cases.

750.        --  There are some exceptions, such as In_Range, that expect a pre-sorted

751.        --  range.

753.        -------------------------------

754.        -- Converting to/from GValue --

755.        -------------------------------

757.        procedure Set_Text_IterTo API docTo body

758.          (Val  : in out Glib.Values.GValueTo API docTo specTo body;

759.           Iter : Gtk_Text_IterTo API docTo specTo body);

760.        --  Set the value of the given GValue to Iter.

761.        --  Note that Iter is stored by reference, which means no copy of Iter

762.        --  is made. Iter should remain allocated as long as Val is being used.

764.        procedure Get_Text_IterTo API docTo body

765.          (ValTo API docTo body  : Glib.Values.GValueTo API docTo specTo body;

766.           IterTo API docTo body : out Gtk_Text_IterTo API docTo specTo body);

767.        --  Extract the iterator from the given GValue.

768.        --  Note that the iterator returned is a copy of the iterator referenced

769.        --  by the give GValue. Modifying the iterator returned does not modify

770.        --  the iterator referenced by the GValue.

772.        --  function Get_Marks

773.        --    (Iter : access Gtk_Text_Iter)

774.        --     return Gtk.Text_Mark.Text_Mark_List.GSList;

775.        --  Return a list of all Gtk_Text_Mark at this location.

776.        --  Because marks are not iterable (they don't take up any "space" in the

777.        --  buffer, they are just marks in between iterable locations), multiple

778.        --  marks can exist in the same place. The returned list is not in any

779.        --  meaningful order.

780.        --  ???

782.        --  function Get_Toggled_Tags

783.        --    (Iter       : access Gtk_Text_Iter;

784.        --     Toggled_On : Boolean) return Gtk.Text_Tag.Text_Tag_List.GSList;

785.        --  Return a list of Gtk_Text_Tag that are toggled on or off at this point.

786.        --  If Toggled_On is True, the list contains tags that are toggled on. If a

787.        --  tag is toggled on at Iter, then some non-empty range of characters

788.        --  following Iter has that tag applied to it. If a tag is toggled off, then

789.        --  some non-empty range following Iter does not have the tag applied to it.

790.        --  ???

792.        --  function Get_Attributes

793.        --    (Iter   : Gtk_Text_Iter;

794.        --     Values : access Gtk.Text_Attributes.Gtk_Text_Attributes_Record'Class)

795.        --     return Boolean;

796.        --  ??? Gtk_Text_Attributes is defined in gtktexttag.h

797.        --  Compute the effect of any tags applied to this spot in the text.

798.        --  The Values parameter should be initialized to the default settings you

799.        --  wish to use if no tags are in effect. Get_Attributes will modify Values,

800.        --  applying the effects of any tags present at Iter. If any tags affected

801.        --  values, the function returns True.

803.        ------------------------------

804.        -- Moving around the buffer --

805.        ------------------------------

807.        --  function Forward_Find_Char

808.        --    (Iter      : access Gtk_Text_Iter;

809.        --     Pred      : Gtk_Text_Char_Predicate;

810.        --     User_Data : gpointer;

811.        --     Limit     : access Gtk_Text_Iter)

812.        --     return Boolean;

813.        --  ??? Need to be put in a generic package...

814.        --  And also needs a binding to gunichar

816.        --  function Backward_Find_Char

817.        --    (Iter      : access Gtk_Text_Iter;

818.        --     Pred      : Gtk_Text_Char_Predicate;

819.        --     User_Data : gpointer;

820.        --     Limit     : access Gtk_Text_Iter)

821.        --     return Boolean;

822.        --  ??? Need to be put in a generic package.

823.        --  And also needs a binding to gunichar.

825.     private

826.        function C_Gtk_Text_Iter_Size return GintTo API docTo spec;

827.        pragma Import (C, C_Gtk_Text_Iter_Size, "ada_c_gtk_text_iter_size");

829.        type Gtk_Text_IterTo API docTo spec is limited record

830.           Dummy1  : System.Address;

831.           Dummy2  : System.Address;

832.           Dummy3  : GintTo API docTo spec;

833.           Dummy4  : GintTo API docTo spec;

834.           Dummy5  : GintTo API docTo spec;

835.           Dummy6  : GintTo API docTo spec;

836.           Dummy7  : GintTo API docTo spec;

837.           Dummy8  : GintTo API docTo spec;

838.           Dummy9  : System.Address;

839.           Dummy10 : System.Address;

840.           Dummy11 : GintTo API docTo spec;

841.           Dummy12 : GintTo API docTo spec;

842.           Dummy13 : GintTo API docTo spec;

843.           Dummy14 : System.Address;

844.        end record;

845.        pragma Convention (C, Gtk_Text_IterTo API docTo specTo body);

846.        --  Note that part of the implementation of this package assumes that this

847.        --  type is a limited record. If for some reason this can no longer remain

848.        --  the case, then it needs to be modified. (See note (2) at the beginning

849.        --  of the body of this package).

850.        --  Similarly, part of the implementation of the following packages depend

851.        --  on this assumption:

852.        --    - Gtk.Text_View

854.        pragma Import (C, Get_TypeTo API docTo spec,        "gtk_text_iter_get_type");

855.        pragma Import (C, Get_OffsetTo API docTo spec,      "gtk_text_iter_get_offset");

856.        pragma Import (C, Get_LineTo API docTo spec,        "gtk_text_iter_get_line");

857.        pragma Import (C, Get_Line_OffsetTo API docTo spec, "gtk_text_iter_get_line_offset");

858.        pragma Import (C, Get_Line_IndexTo API docTo spec,  "gtk_text_iter_get_line_index");

859.        pragma Import

860.          (C, Get_Visible_Line_OffsetTo API docTo spec, "gtk_text_iter_get_visible_line_offset");

861.        pragma Import

862.          (C, Get_Visible_Line_IndexTo API docTo spec, "gtk_text_iter_get_visible_line_index");

863.        pragma Import (C, Get_Chars_In_LineTo API docTo spec, "gtk_text_iter_get_chars_in_line");

864.        pragma Import (C, Get_Bytes_In_LineTo API docTo spec, "gtk_text_iter_get_bytes_in_line");

865.        pragma Import (C, Forward_To_EndTo API docTo spec,    "gtk_text_iter_forward_to_end");

866.        pragma Import (C, CompareTo API docTo spec,           "gtk_text_iter_compare");

867.        pragma Import (C, OrderTo API docTo spec,             "gtk_text_iter_order");

868.        pragma Import (C, Set_Text_IterTo API docTo spec,     "g_value_set_pointer");

869.        --  External binding: g_value_set_pointer

871.     end Gtk.Text_IterTo API docTo specTo body;

873.     --  No binding: gtk_text_iter_copy

874.     --  No binding: gtk_text_iter_free

876.     --  Binding is in gtk-text_buffer.ads

877.     --  No binding: gtk_text_iter_get_buffer