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. -- -- -- -- -- -- -- -- -- -- -- --
  22. ----------------------------------------------------------------------- 
  23.  
  24. --  <description> 
  25. --  A Gtk_Text_Iter represents a location in the text. It becomes invalid if 
  26. --  the characters/pixmaps/widgets (indexable objects) in the text buffer 
  27. --  are changed. 
  28. --  </description> 
  29. --  <c_version>2.8.17</c_version> 
  30. --  <group>Multiline Text Editor</group> 
  31.  
  32. with Gdk.Pixbuf; 
  33. with Glib.Object; 
  34. with Glib.Values; 
  35. with Gtk.Text_Attributes; 
  36. with Gtk.Text_Child; 
  37. with Gtk.Text_Tag; 
  38. with Interfaces.C.Strings; 
  39. with System; 
  40.  
  41. package Gtk.Text_Iter is 
  42.  
  43.    type Gtk_Text_Iter is limited private; 
  44.    type Gtk_Text_Iter_Access is access all Gtk_Text_Iter; 
  45.  
  46.    function Get_Type return Glib.GType; 
  47.    --  Return the internal type used for a Gtk_Text_Iter 
  48.  
  49.    procedure Copy (Source : Gtk_Text_Iter; Dest : out Gtk_Text_Iter); 
  50.    --  Create a copy of Source. 
  51.  
  52.    -------------------------- 
  53.    -- Characters and bytes -- 
  54.    -------------------------- 
  55.    --  The basic component of a Gtk_Text_Buffer is a character. Since these are 
  56.    --  encoded in Unicode's UTF8, a character can be stored as multiple bytes 
  57.    --  in fact, and gtk+ therefore provides function to either take bytes or 
  58.    --  characters into account. The latter is generally the form that you 
  59.    --  should use in your applications 
  60.  
  61.    procedure Forward_Char (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  62.    --  Move Iter forward by one character offset. 
  63.    --  Note that images embedded in the buffer occupy 1 character slot, so 
  64.    --  Forward_Char may actually move onto an image instead of a character, if 
  65.    --  you have images in your buffer. If Iter is the end iterator or one 
  66.    --  character before it, Iter will now point at the end iterator, and 
  67.    --  Forward_Char returns False for convenience when writing loops. 
  68.  
  69.    procedure Backward_Char (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  70.    --  Move backward by one character offset. 
  71.    --  Return True if movement was possible; if Iter was the first in the 
  72.    --  buffer (character offset 0), return False for convenience when writing 
  73.    --  loops. 
  74.  
  75.    procedure Forward_Chars 
  76.      (Iter   : in out Gtk_Text_Iter; 
  77.       Count  : Gint := 1; 
  78.       Result : out Boolean); 
  79.    --  Move Count characters if possible. 
  80.    --  If Count would move past the start or end of the buffer, move to the 
  81.    --  start or end of the buffer). Result indicates whether the new position 
  82.    --  of Iter is different from its original position, and dereferenceable 
  83.    --  (the last iterator in the buffer is not dereferenceable). If Count 
  84.    --  is 0, this procedure does nothing and returns False. 
  85.  
  86.    procedure Backward_Chars 
  87.      (Iter   : in out Gtk_Text_Iter; 
  88.       Count  : Gint := 1; 
  89.       Result : out Boolean); 
  90.    --  Move Count characters backward, if possible. 
  91.    --  If Count would move past the start or end of the buffer, moves to the 
  92.    --  start or end of the buffer). Result indicates whether the iterator moved 
  93.    --  onto a dereferenceable position; if the iterator didn't move, or moved 
  94.    --  onto the end iterator, then False is returned. If Count is 0, the 
  95.    --  function does nothing and returns False. 
  96.  
  97.    procedure Set_Offset (Iter : in out Gtk_Text_Iter; Char_Offset : Gint); 
  98.    function  Get_Offset (Iter : Gtk_Text_Iter) return Gint; 
  99.    --  Set or return the character offset of an iterator. 
  100.    --  Each character in a Gtk_Text_Buffer has an offset, starting with 0 for 
  101.    --  the first character in the buffer. 
  102.    --  Use Gtk.Text_Buffer.Get_Iter_At_Offset to convert an offset back into an 
  103.    --  iterator. 
  104.  
  105.    ----------- 
  106.    -- Words -- 
  107.    ----------- 
  108.    --  Characters are grouped together into words. Their exact definition 
  109.    --  depends on the current language (see Pango.Language). 
  110.  
  111.    function Starts_Word (Iter : Gtk_Text_Iter) return Boolean; 
  112.    --  Determine whether Iter begins a natural-language word. 
  113.    --  Word breaks are determined by Pango and should be correct for nearly any 
  114.    --  language (if not, the correct fix would be to the Pango word break 
  115.    --  algorithms. 
  116.  
  117.    function Ends_Word (Iter : Gtk_Text_Iter) return Boolean; 
  118.    --  Determine whether Iter ends a natural-language word. 
  119.    --  Word breaks are determined by Pango and should be correct for nearly any 
  120.    --  language (if not, the correct fix would be to the Pango word break 
  121.    --  algorithms). 
  122.  
  123.    function Inside_Word (Iter : Gtk_Text_Iter) return Boolean; 
  124.    --  Determine whether Iter is inside a natural-language word (as opposed to 
  125.    --  say inside some whitespace). Word breaks are determined by Pango and 
  126.    --  should be correct for nearly any language (if not, the correct fix would 
  127.    --  be to the Pango word break algorithms). 
  128.  
  129.    procedure Forward_Word_End 
  130.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  131.    --  Move forward to the next word end. 
  132.    --  If Iter is currently on a word end, move forward to the next one after 
  133.    --  that. Word breaks are determined by Pango and should be correct for 
  134.    --  nearly any language (if not, the correct fix would be to the Pango word 
  135.    --  break algorithms). 
  136.  
  137.    procedure Forward_Word_Ends 
  138.      (Iter   : in out Gtk_Text_Iter; 
  139.       Count  : Gint := 1; 
  140.       Result : out Boolean); 
  141.    --  Call Forward_Word_End up to Count times. 
  142.  
  143.    procedure Forward_Visible_Word_End 
  144.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  145.    --  Moves forward to the next visible word end. (If Iter is currently on 
  146.    --  word end, moves forward to the next one after that.) Word breaks are 
  147.    --  determined by Pango and should be correct for nearly any language (if 
  148.    --  not, the correct fix would be to the Pango word break algorithms). 
  149.  
  150.    procedure Forward_Visible_Word_Ends 
  151.      (Iter   : in out Gtk_Text_Iter; 
  152.       Count  : Gint := 1; 
  153.       Result : out Boolean); 
  154.    --  Calls Forward_Visible_Word_End up to Count times 
  155.  
  156.    procedure Backward_Word_Start 
  157.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  158.    --  Move backward to the next word start. 
  159.    --  If Iter is currently on a word start, move backward to the next one 
  160.    --  after that. 
  161.  
  162.    procedure Backward_Word_Starts 
  163.      (Iter   : in out Gtk_Text_Iter; 
  164.       Count  : Gint := 1; 
  165.       Result : out Boolean); 
  166.    --  Call Backward_Word_Start up to Count times. 
  167.  
  168.    procedure Backward_Visible_Word_Start 
  169.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  170.    --  Moves backward to the previous visible word start. (If Iter is currently 
  171.    --  on a word start, moves backward to the next one after that.) Word breaks 
  172.    --  are determined by Pango and should be correct for nearly any language 
  173.    --  (if not, the correct fix would be to the Pango word break algorithms). 
  174.  
  175.    procedure Backward_Visible_Word_Starts 
  176.      (Iter   : Gtk_Text_Iter; 
  177.       Count  : Gint := 1; 
  178.       Result : in out Boolean); 
  179.    --  Move backward up to Count previous visible word starts. 
  180.  
  181.    --------------- 
  182.    -- Sentences -- 
  183.    --------------- 
  184.    --  Words are then grouped together into sentences. 
  185.  
  186.    function Starts_Sentence (Iter : Gtk_Text_Iter) return Boolean; 
  187.    --  Determine whether Iter begins a sentence. 
  188.    --  Sentence boundaries are determined by Pango and should be correct for 
  189.    --  nearly any language (if not, the correct fix would be to the Pango text 
  190.    --  boundary algorithms). 
  191.  
  192.    function Ends_Sentence (Iter : Gtk_Text_Iter) return Boolean; 
  193.    --  Determine whether Iter ends a sentence. 
  194.    --  Sentence boundaries are determined by Pango and should be correct for 
  195.    --  nearly any language (if not, the correct fix would be to the Pango text 
  196.    --  boundary algorithms). 
  197.  
  198.    function Inside_Sentence (Iter : Gtk_Text_Iter) return Boolean; 
  199.    --  Determine whether Iter is inside a sentence (as opposed to in between 
  200.    --  two sentences, e.g. after a period and before the first letter of the 
  201.    --  next sentence). Sentence boundaries are determined by Pango and should 
  202.    --  be correct for nearly any language (if not, the correct fix would be to 
  203.    --  the Pango text boundary algorithms). 
  204.  
  205.    procedure Forward_Sentence_End 
  206.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  207.    --  Move forward to the next sentence end. 
  208.    --  If Iter is at the end of a sentence, move to the next end of sentence. 
  209.  
  210.    procedure Backward_Sentence_Start 
  211.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  212.    --  Move backward to the next sentence start. 
  213.    --  If Iter is already at the start of a sentence, move backward to the next 
  214.    --  one. 
  215.  
  216.    procedure Forward_Sentence_Ends 
  217.      (Iter   : in out Gtk_Text_Iter; 
  218.       Count  : Gint := 1; 
  219.       Result : out Boolean); 
  220.    --  Call Forward_Sentence_End up to Count times. 
  221.  
  222.    procedure Backward_Sentence_Starts 
  223.      (Iter   : in out Gtk_Text_Iter; 
  224.       Count  : Gint := 1; 
  225.       Result : out Boolean); 
  226.    --  Call Backward_Sentence_Starts up to Count times. 
  227.  
  228.    -------------------------- 
  229.    -- Lines and paragraphs -- 
  230.    -------------------------- 
  231.    --  Sentences are grouped together to form lines and paragraphs. The 
  232.    --  definition of these is language-dependent 
  233.  
  234.    procedure Set_Line (Iter : in out Gtk_Text_Iter; Line_Number : Gint); 
  235.    function  Get_Line (Iter : Gtk_Text_Iter) return Gint; 
  236.    --  Set or return the line number containing the iterator. 
  237.    --  Lines in a Gtk_Text_Buffer are numbered beginning with 0 for the first 
  238.    --  line in the buffer. 
  239.  
  240.    procedure Set_Line_Offset 
  241.      (Iter : in out Gtk_Text_Iter; Char_On_Line : Gint); 
  242.    function Get_Line_Offset (Iter : Gtk_Text_Iter) return Gint; 
  243.    --  Move Iter within a line, to a new character (not byte) offset. 
  244.    --  The given character offset must be less than or equal to the number of 
  245.    --  characters in the line; if equal, Iter moves to the start of the next 
  246.    --  line. See Set_Line_Index if you have a byte index rather than a 
  247.    --  character offset. 
  248.    --  The first character on the line has offset 0. 
  249.  
  250.    procedure Set_Line_Index (Iter : in out Gtk_Text_Iter; Byte_On_Line : Gint); 
  251.    function Get_Line_Index (Iter : Gtk_Text_Iter) return Gint; 
  252.    --  Same as Set_Line_Offset, but work with a byte index. 
  253.    --  The given byte index must be at the start of a character, it can't be in 
  254.    --  the middle of a UTF-8 encoded character. 
  255.    --  Remember that Gtk_Text_Buffer encodes text in UTF-8, and that characters 
  256.    --  can require a variable number of bytes to represent. 
  257.  
  258.    procedure Set_Visible_Line_Offset 
  259.      (Iter : in out Gtk_Text_Iter; Char_On_Line : Gint); 
  260.    function Get_Visible_Line_Offset (Iter : Gtk_Text_Iter) return Gint; 
  261.    --  Sets or returns the offset in characters from the start of the line to 
  262.    --  the given Iter, not counting characters that are invisible due to tags 
  263.    --  with the "invisible" flag toggled on. 
  264.  
  265.    procedure Set_Visible_Line_Index 
  266.      (Iter : in out Gtk_Text_Iter; Byte_On_Line : Gint); 
  267.    function Get_Visible_Line_Index (Iter : Gtk_Text_Iter) return Gint; 
  268.    --  Set or returns the number of bytes from the start of the line to the 
  269.    --  given Iter, not counting bytes that are invisible due to tags with the 
  270.    --  "invisible" flag toggled on. 
  271.  
  272.    function Starts_Line (Iter : Gtk_Text_Iter) return Boolean; 
  273.    --  Return True if Iter begins a paragraph. i.e. if Get_Line_Offset would 
  274.    --  return 0. 
  275.    --  However this function is potentially more efficient than 
  276.    --  Get_Line_Offset because it doesn't have to compute the offset, it just 
  277.    --  has to see whether it's 0. 
  278.  
  279.    function Ends_Line (Iter : Gtk_Text_Iter) return Boolean; 
  280.    --  Return True if Iter points to the start of the paragraph delimiter 
  281.    --  characters for a line (delimiters will be either a newline, a carriage 
  282.    --  return, a carriage return followed by a newline, or a Unicode paragraph 
  283.    --  separator character). Note that an iterator pointing to the ASCII.LF of 
  284.    --  a ASCII.CR & ASCII.LF pair will not be counted as the end of a line, the 
  285.    --  line ends before the ASCII.CR. 
  286.  
  287.    function Get_Chars_In_Line (Iter : Gtk_Text_Iter) return Gint; 
  288.    --  Return the number of characters in the line containing Iter, including 
  289.    --  the paragraph delimiters. 
  290.  
  291.    function Get_Bytes_In_Line (Iter : Gtk_Text_Iter) return Gint; 
  292.    --  Return the number of bytes in the line containing Iter, including the 
  293.    --  paragraph delimiters. 
  294.  
  295.    procedure Forward_Line (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  296.    --  Move Iter to the start of the next line. 
  297.    --  Return True if there was a next line to move to, and False if iter was 
  298.    --  simply moved to the end of the buffer and is now not dereferenceable, or 
  299.    --  if Iter was already at the end of the buffer. 
  300.  
  301.    procedure Forward_Lines 
  302.      (Iter   : in out Gtk_Text_Iter; 
  303.       Count  : Gint := 1; 
  304.       Result : out Boolean); 
  305.    --  Call Forward_Line, up to Count times. 
  306.  
  307.    procedure Forward_Visible_Line 
  308.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  309.    --  Moves Iter to the start of the next visible line. Returns True if there 
  310.    --  was a next line to move to, and False if Iter was simply moved to the 
  311.    --  end of the buffer and is now not dereferenceable, or if Iter was already 
  312.    --  at the end of the buffer. 
  313.  
  314.    procedure Forward_Visible_Lines 
  315.      (Iter   : in out Gtk_Text_Iter; 
  316.       Count  : Gint := 1; 
  317.       Result : out Boolean); 
  318.    --  Moves Count visible lines forward, if possible (if Count would move 
  319.    --  past the start or end of the buffer, moves to the start or end of 
  320.    --  the buffer).  The return value indicates whether the iterator moved 
  321.    --  onto a dereferenceable position; if the iterator didn't move, or 
  322.    --  moved onto the end iterator, then False is returned. If Count is 0, 
  323.    --  the function does nothing and returns False. If Count is negative, 
  324.    --  moves backward by 0 - Count lines. 
  325.  
  326.    procedure Forward_To_Line_End 
  327.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  328.    --  Move the iterator to point to the paragraph delimiter characters, 
  329.    --  which will be either a newline, a carriage return, a carriage 
  330.    --  return/newline in sequence, or the Unicode paragraph separator 
  331.    --  character. If the iterator is already at the paragraph delimiter 
  332.    --  characters, move to the paragraph delimiter characters for the next 
  333.    --  line. 
  334.  
  335.    procedure Backward_Line (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  336.    --  Move Iter to the start of the previous line. 
  337.    --  Return True if Iter could be moved; i.e. if Iter was at character offset 
  338.    --  0, this function returns False. Therefore if Iter was already on line 0, 
  339.    --  but not at the start of the line, Iter is snapped to the start of the 
  340.    --  line and the function returns True. (Note that this implies that in a 
  341.    --  loop calling this function, the line number may not change on every 
  342.    --  iteration, if your first iteration is on line 0) 
  343.  
  344.    procedure Backward_Lines 
  345.      (Iter   : in out Gtk_Text_Iter; 
  346.       Count  : Gint := 1; 
  347.       Result : out Boolean); 
  348.    --  Call Backward_Line, up to Count times. 
  349.  
  350.    procedure Backward_Visible_Line 
  351.      (Iter   : in out Gtk_Text_Iter; Result : out Boolean); 
  352.    --  Moves Iter to the start of the previous visible line. Returns True if 
  353.    --  Iter could be moved; i.e. if Iter was at character offset 0, this 
  354.    --  function returns False. Therefore if Iter was already on line 0, but not 
  355.    --  at the start of the line, Iter is snapped to the start of the line and 
  356.    --  the function returns True. (Note that this implies that in a loop 
  357.    --  calling this function, the line number may not change on every 
  358.    --  iteration, if your first iteration is on line 0.) 
  359.  
  360.    procedure Backward_Visible_Lines 
  361.      (Iter   : in out Gtk_Text_Iter; 
  362.       Count  : Gint := 1; 
  363.       Result : out Boolean); 
  364.    --  Moves Count visible lines backward, if possible (if Count would move 
  365.    --  past the start or end of the buffer, moves to the start or end of the 
  366.    --  buffer). The return value indicates whether the iterator moved onto a 
  367.    --  dereferenceable position; if the iterator didn't move, or moved onto the 
  368.    --  end iterator, then False is returned. If Count is 0, the function does 
  369.    --  nothing and returns False. If Count is negative, moves forward by 0 - 
  370.    --  Count lines. 
  371.  
  372.    ------------ 
  373.    -- Buffer -- 
  374.    ------------ 
  375.    --  When grouped together, lines and paragraph made up the whole buffer. 
  376.  
  377.    function Is_End (Iter : Gtk_Text_Iter) return Boolean; 
  378.    --  Return True if Iter is the end iterator. 
  379.    --  i.e. one past the last dereferenceable iterator in the buffer. 
  380.    --  This is the most efficient way to check whether an iterator is the end 
  381.    --  iterator. 
  382.  
  383.    function Is_Start (Iter : Gtk_Text_Iter) return Boolean; 
  384.    --  Return True if Iter is the first iterator in the buffer, that is 
  385.    --  if Iter has a character offset of 0. 
  386.  
  387.    procedure Forward_To_End (Iter : in out Gtk_Text_Iter); 
  388.    --  Move Iter forward to the "end iterator", which points one past the last 
  389.    --  valid character in the buffer. Get_Char called on the end iterator 
  390.    --  returns 0, which is convenient for writing loops. 
  391.  
  392.    ----------------------------- 
  393.    -- Reading buffer contents -- 
  394.    ----------------------------- 
  395.  
  396.    function Get_Char (Iter : Gtk_Text_Iter) return Gunichar; 
  397.    --  Return the character immediately following Iter. If Iter is at the 
  398.    --  end of the buffer, then return ASCII.NUL. 
  399.  
  400.    function Get_Char (Iter : Gtk_Text_Iter) return Character; 
  401.    --  Return the character immediately following Iter. If Iter is at the 
  402.    --  end of the buffer, then return ASCII.NUL. 
  403.    --  Note that this function assumes that the text is encoded in ASCII 
  404.    --  format. If this is not the case, use the Get_Char function that 
  405.    --  returns a Gunichar instead. 
  406.  
  407.    function Get_Slice 
  408.      (Start   : Gtk_Text_Iter; 
  409.       The_End : Gtk_Text_Iter) return UTF8_String; 
  410.    --  Return the text in the given range. 
  411.    --  A "slice" is an array of characters encoded in UTF-8 format, including 
  412.    --  the Unicode "unknown" character 16#FFFC# for iterable non-character 
  413.    --  elements in the buffer, such as images. Because images are encoded in 
  414.    --  the slice, byte and character offsets in the returned array will 
  415.    --  correspond to byte offsets in the text buffer. Note that 16#FFFC# can 
  416.    --  occur in normal text as well, so it is not a reliable indicator that a 
  417.    --  pixbuf or widget is in the buffer. 
  418.  
  419.    function Get_Slice 
  420.      (Start   : Gtk_Text_Iter; 
  421.       The_End : Gtk_Text_Iter) return Interfaces.C.Strings.chars_ptr; 
  422.    --  Same as above, but returns the row C string. 
  423.    --  The caller is responsible for freeing the string returned. 
  424.  
  425.    function Get_Text 
  426.      (Start   : Gtk_Text_Iter; 
  427.       The_End : Gtk_Text_Iter) return UTF8_String; 
  428.    --  Return text in the given range. 
  429.    --  If the range contains non-text elements such as images, the character 
  430.    --  and byte offsets in the returned string will not correspond to character 
  431.    --  and byte offsets in the buffer. If you want offsets to correspond, see 
  432.    --  Get_Slice. 
  433.  
  434.    function Get_Visible_Slice 
  435.      (Start   : Gtk_Text_Iter; 
  436.       The_End : Gtk_Text_Iter) return UTF8_String; 
  437.    --  Like Get_Slice, but invisible text is not included. 
  438.    --  Invisible text is usually invisible because a Gtk_Text_Tag with the 
  439.    --  "invisible" attribute turned on has been applied to it. 
  440.  
  441.    function Get_Visible_Text 
  442.      (Start   : Gtk_Text_Iter; 
  443.       The_End : Gtk_Text_Iter) return UTF8_String; 
  444.    --  Like Get_Text, but invisible text is not included. 
  445.    --  Invisible text is usually invisible because a Gtk_Text_Tag with the 
  446.    --  "invisible" attribute turned on has been applied to it. 
  447.  
  448.    function Get_Pixbuf (Iter : Gtk_Text_Iter) return Gdk.Pixbuf.Gdk_Pixbuf; 
  449.    --  If the location pointed to by Iter contains a pixbuf, the pixbuf 
  450.    --  is returned (with no new reference count added). Otherwise, null is 
  451.    --  returned. 
  452.  
  453.    ---------- 
  454.    -- Tags -- 
  455.    ---------- 
  456.    --  Iterators can be used to move among tags. These tags are used to 
  457.    --  set some specific attributes on the text. 
  458.  
  459.    function Begins_Tag 
  460.      (Iter : Gtk_Text_Iter; 
  461.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := null) return Boolean; 
  462.    --  Return True if Tag is toggled on at exactly this point. 
  463.    --  If Tag is null, return True if any tag is toggled on at this point. 
  464.    --  Return True if Iter is the start of the tagged range; 
  465.    --  Has_Tag tells you whether an iterator is within a tagged range. 
  466.  
  467.    function Ends_Tag 
  468.      (Iter : Gtk_Text_Iter; 
  469.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := null) return Boolean; 
  470.    --  Return True if Tag is toggled off at exactly this point. 
  471.    --  If Tag is null, return True if any tag is toggled off at this point. 
  472.    --  Note that the Ends_Tag return True if Iter is the end of the tagged 
  473.    --  range; Has_Tag tells you whether an iterator is within a tagged range. 
  474.  
  475.    function Toggles_Tag 
  476.      (Iter : Gtk_Text_Iter; 
  477.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := null) return Boolean; 
  478.    --  Whether a range with Tag applied to it begins or ends at Iter. 
  479.    --  Equivalent to "Begins_Tag (Iter, Tag) or else Ends_Tag (Iter, Tag)". 
  480.  
  481.    function Has_Tag 
  482.      (Iter : Gtk_Text_Iter; 
  483.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := null) return Boolean; 
  484.    --  Return True if Iter is within a range tagged with Tag. 
  485.  
  486.    function Get_Tags 
  487.      (Iter : Gtk_Text_Iter) return Gtk.Text_Tag.Text_Tag_List.GSlist; 
  488.    --  Return a list of tags that apply to Iter, in ascending order of priority 
  489.    --  (highest-priority tags are last). The Gtk_Text_Tag in the list don't 
  490.    --  have a reference added, but you have to free the list itself. 
  491.  
  492.    procedure Forward_To_Tag_Toggle 
  493.      (Iter   : in out Gtk_Text_Iter; 
  494.       Tag    : Gtk.Text_Tag.Gtk_Text_Tag := null; 
  495.       Result : out Boolean); 
  496.    --  Move forward to the next toggle (on or off) of the Gtk_Text_Tag Tag, or 
  497.    --  to the next toggle of any tag if Tag is null. If no matching tag toggles 
  498.    --  are found, return False, otherwise True. Do not return toggles located 
  499.    --  at Iter, only toggles after Iter. Set Iter to the location of the 
  500.    --  toggle, or to the end of the buffer if no toggle is found. 
  501.  
  502.    procedure Backward_To_Tag_Toggle 
  503.      (Iter   : in out Gtk_Text_Iter; 
  504.       Tag    : Gtk.Text_Tag.Gtk_Text_Tag := null; 
  505.       Result : out Boolean); 
  506.    --  Move backward to the next toggle (on or off) of the Gtk_Text_Tag Tag, 
  507.    --  or to the next toggle of any tag if Tag is null. If no matching tag 
  508.    --  toggles are found, return False, otherwise True. Do not return toggles 
  509.    --  located at Iter, only toggles before Iter. Set Iter to the location of 
  510.    --  the toggle, or the start of the buffer if no toggle is found. 
  511.  
  512.    function Get_Toggled_Tags 
  513.      (Iter       : Gtk_Text_Iter; 
  514.       Toggled_On : Boolean) 
  515.       return Glib.Object.Object_List.GSlist; 
  516.    --  Returns a list of #GtkTextTag that are toggled on or off at this point. 
  517.    --  (If Toggled_On is True, the list contains tags that are toggled on.) If 
  518.    --  a tag is toggled on at Iter, then some non-empty range of characters 
  519.    --  following Iter has that tag applied to it. If a tag is toggled off, then 
  520.    --  some non-empty range following Iter does not have the tag applied to it. 
  521.    --  The returned list should be freed by the caller. 
  522.  
  523.    ---------------- 
  524.    -- Attributes -- 
  525.    ---------------- 
  526.    --  The tags are used to change the attributes of parts of the buffer. For 
  527.    --  convenience, a number of wrapper subprograms are provided to make the 
  528.    --  use of tags easier. 
  529.  
  530.    function Editable 
  531.      (Iter            : Gtk_Text_Iter; 
  532.       Default_Setting : Boolean := True) return Boolean; 
  533.    --  Return whether Iter is within an editable region of text. 
  534.    --  Non-editable text is "locked" and can't be changed by the user via 
  535.    --  Gtk_Text_View. This function is simply a convenience wrapper around 
  536.    --  Get_Attributes. If no tags applied to this text affect editability, 
  537.    --  Default_Setting will be returned. 
  538.  
  539.    function Can_Insert 
  540.      (Iter                : Gtk_Text_Iter; 
  541.       Default_Editability : Boolean) return Boolean; 
  542.    --  Return whether text inserted at Iter would be editable. 
  543.    --  Considering the default editability of the buffer, and tags that 
  544.    --  affect editability, determines whether text inserted at Iter would 
  545.    --  be editable. If text inserted at Iter would be editable then the 
  546.    --  user should be allowed to insert text at Iter. 
  547.    --  Gtk.Text_Buffer.Insert_Interactive uses this function to decide 
  548.    --  whether insertions are allowed at a given position. 
  549.  
  550.    function Get_Language (Iter : Gtk_Text_Iter) return UTF8_String; 
  551.    --  A convenience wrapper around Get_Attributes, 
  552.    --  which returns the language in effect at Iter. If no tags affecting 
  553.    --  language apply to Iter, the return value is identical to that of 
  554.    --  Gtk.Get_Default_Language. 
  555.  
  556.    procedure Get_Attributes 
  557.      (Iter     : Gtk_Text_Iter; 
  558.       Values   : in out Gtk.Text_Attributes.Gtk_Text_Attributes; 
  559.       Modified : out Boolean); 
  560.    --  Computes the effect of any tags applied to this spot in the text. The 
  561.    --  Values parameter should be initialized to the default settings you wish 
  562.    --  to use if no tags are in effect. You'd typically obtain the defaults 
  563.    --  from gtk.text_view.get_default_attributes. 
  564.    -- 
  565.    --  Get_Attributes will modify Values, applying the effects of any tags 
  566.    --  present at Iter. If any tags affected Values, the function returns True. 
  567.  
  568.    ------------ 
  569.    -- Cursor -- 
  570.    ------------ 
  571.    --  The cursor is a special position in the buffer that indicates where the 
  572.    --  user will interactively insert new characters. In some languages, you 
  573.    --  can put the cursor between certain chars. Also you can't put the cursor 
  574.    --  between \r and \n on Windows-line ending files. 
  575.  
  576.    function Is_Cursor_Position (Iter : Gtk_Text_Iter) return Boolean; 
  577.    --  Return True if the cursor can be placed at Iter. 
  578.    --  See Forward_Cursor_Position for details on what a cursor position is. 
  579.  
  580.    procedure Forward_Cursor_Position 
  581.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  582.    --  Move Iter forward by a single cursor position. 
  583.    --  Cursor positions are (unsurprisingly) positions where the cursor can 
  584.    --  appear. Perhaps surprisingly, there may not be a cursor position between 
  585.    --  all characters. The most common example for European languages would be 
  586.    --  a carriage return/newline sequence. For some Unicode characters, the 
  587.    --  equivalent of say the letter "a" with an accent mark will be represented 
  588.    --  as two characters, first the letter then a "combining mark" that causes 
  589.    --  the accent to be rendered; so the cursor can't go between those two 
  590.    --  characters. 
  591.  
  592.    procedure Backward_Cursor_Position 
  593.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  594.    --  Like Forward_Cursor_Position, but moves backward. 
  595.  
  596.    procedure Forward_Cursor_Positions 
  597.      (Iter   : in out Gtk_Text_Iter; 
  598.       Count  : Gint := 1; 
  599.       Result : out Boolean); 
  600.    --  Call Forward_Cursor_Position up to Count times. 
  601.  
  602.    procedure Forward_Visible_Cursor_Position 
  603.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  604.    --  Moves Iter forward to the next visible cursor position. Return True if 
  605.    --  the new position is valid 
  606.  
  607.    procedure Forward_Visible_Cursor_Positions 
  608.      (Iter   : in out Gtk_Text_Iter; 
  609.       Count  : Gint := 1; 
  610.       Result : out Boolean); 
  611.    --  Moves up to Count visible cursor positions. See Forward_Cursor_Position 
  612.    --  for details. Return True if the cursor could be moved. 
  613.  
  614.    procedure Backward_Cursor_Positions 
  615.      (Iter   : in out Gtk_Text_Iter; 
  616.       Count  : Gint := 1; 
  617.       Result : out Boolean); 
  618.    --  Call Backward_Cursor_Position up to Count times. 
  619.  
  620.    procedure Backward_Visible_Cursor_Position 
  621.      (Iter : in out Gtk_Text_Iter;  Result : out Boolean); 
  622.    --  Moves Iter backward to the previous visible cursor position. Return 
  623.    --  True if the new position is valid. 
  624.  
  625.    procedure Backward_Visible_Cursor_Positions 
  626.      (Iter   : in out Gtk_Text_Iter; 
  627.       Count  : Gint := 1; 
  628.       Result : out Boolean); 
  629.    --  Moves up to Count visible cursor positions. Return True if the new 
  630.    --  position is valid. 
  631.  
  632.    -------------- 
  633.    -- Children -- 
  634.    -------------- 
  635.    --  The buffer can contain many widgets. They are all attached to specific 
  636.    --  anchors (see Gtk.Text_Child) 
  637.  
  638.    function Get_Child_Anchor 
  639.      (Iter : Gtk_Text_Iter) 
  640.       return Gtk.Text_Child.Gtk_Text_Child_Anchor; 
  641.    --  If the location pointed to by Iter contains a child anchor, the anchor 
  642.    --  is returned (with no new reference count added). Otherwise, null is 
  643.    --  returned. 
  644.  
  645.    function Get_Marks 
  646.      (Iter : Gtk_Text_Iter) return Glib.Object.Object_List.GSlist; 
  647.    --  Returns a list of all Gtk_Text_Mark at this location. Because marks are 
  648.    --  not iterable (they don't take up any "space" in the buffer, they are 
  649.    --  just marks in between iterable locations), multiple marks can exist in 
  650.    --  the same place. The returned list is not in any meaningful order. 
  651.  
  652.    --------------- 
  653.    -- Searching -- 
  654.    --------------- 
  655.  
  656.    type Gtk_Text_Search_Flags is mod 2 ** 8; 
  657.    for Gtk_Text_Search_Flags'Size use Gint'Size; 
  658.  
  659.    Visible_Only : constant Gtk_Text_Search_Flags := 2 ** 0; 
  660.    Text_Only    : constant Gtk_Text_Search_Flags := 2 ** 1; 
  661.  
  662.    procedure Forward_Search 
  663.      (Iter         : Gtk_Text_Iter; 
  664.       Str          : UTF8_String; 
  665.       Flags        : Gtk_Text_Search_Flags; 
  666.       Match_Start  : out Gtk_Text_Iter; 
  667.       Match_End    : out Gtk_Text_Iter; 
  668.       Limit        : Gtk_Text_Iter; 
  669.       Result       : out Boolean); 
  670.    --  Search forward for Str. 
  671.    --  Any match is returned as the range Match_Start, Match_End. If you 
  672.    --  specify Visible_Only or Slice, the match may have invisible text, 
  673.    --  pixbufs, or child widgets interspersed in Str. 
  674.    --  Iter: start of search 
  675.    --  Str: a search string 
  676.    --  Match_Start: return location for start of match, or null 
  677.    --  Match_End: return location for end of match, or null 
  678.    --  Limit: bound for the search, or null for the end of the buffer 
  679.    --  Result: whether a match was found. 
  680.  
  681.    procedure Backward_Search 
  682.      (Iter         : Gtk_Text_Iter; 
  683.       Str          : UTF8_String; 
  684.       Flags        : Gtk_Text_Search_Flags; 
  685.       Match_Start  : out Gtk_Text_Iter; 
  686.       Match_End    : out Gtk_Text_Iter; 
  687.       Limit        : Gtk_Text_Iter; 
  688.       Result       : out Boolean); 
  689.    --  Same as Forward_Search, but move backward. 
  690.  
  691.    generic 
  692.       type Data_Type (<>) is private; 
  693.    package Find_Chars is 
  694.       type Gtk_Text_Char_Predicate is access function 
  695.         (Ch : Gunichar; User_Data : Data_Type) return Boolean; 
  696.  
  697.       function Forward_Find_Char 
  698.         (Iter      : Gtk_Text_Iter; 
  699.          Pred      : Gtk_Text_Char_Predicate; 
  700.          User_Data : Data_Type; 
  701.          Limit     : Gtk_Text_Iter) return Boolean; 
  702.       --  Advances Iter, calling Pred on each character. If Pred returns True, 
  703.       --  returns True and stops scanning. If Pred never returns True, Iter is 
  704.       --  set to Limit if Limit is not Null_Iter, otherwise to the end 
  705.       --  iterator. 
  706.  
  707.       function Backward_Find_Char 
  708.         (Iter      : Gtk_Text_Iter; 
  709.          Pred      : Gtk_Text_Char_Predicate; 
  710.          User_Data : Data_Type; 
  711.          Limit     : Gtk_Text_Iter) return Boolean; 
  712.       --  Same as Forward_Find_Char, but goes backward from Iter 
  713.    end Find_Chars; 
  714.  
  715.    ----------------- 
  716.    -- Comparisons -- 
  717.    ----------------- 
  718.  
  719.    function Equal (Lhs : Gtk_Text_Iter; Rhs : Gtk_Text_Iter) return Boolean; 
  720.    --  Test whether two iterators are equal, using the fastest possible 
  721.    --  mechanism. This function is very fast; you can expect it to perform 
  722.    --  better than e.g. getting the character offset for each iterator and 
  723.    --  comparing the offsets yourself. Also, it's a bit faster than Compare. 
  724.  
  725.    function Compare (Lhs : Gtk_Text_Iter; Rhs : Gtk_Text_Iter) return Gint; 
  726.    --  A quick sort-style function that return negative if Lhs is less than 
  727.    --  Rhs, positive if Lhs is greater than Rhs, and 0 if they're equal. 
  728.    --  Ordering is in character offset order, i.e. the first character in the 
  729.    --  buffer is less than the second character in the buffer. 
  730.  
  731.    function In_Range 
  732.      (Iter    : Gtk_Text_Iter; 
  733.       Start   : Gtk_Text_Iter; 
  734.       The_End : Gtk_Text_Iter) return Boolean; 
  735.    --  Start and End must be in order, unlike most text buffer functions, for 
  736.    --  efficiency reasons. Return True if Iter falls in the range [Start, End) 
  737.  
  738.    procedure Order 
  739.      (First  : in out Gtk_Text_Iter; 
  740.       Second : in out Gtk_Text_Iter); 
  741.    --  Swap the value of First and Second if Second comes before First in the 
  742.    --  buffer. That is, ensures that First and Second are in sequence. Most 
  743.    --  text buffer functions that take a range call this automatically on your 
  744.    --  behalf, so there's no real reason to call it yourself in those cases. 
  745.    --  There are some exceptions, such as In_Range, that expect a pre-sorted 
  746.    --  range. 
  747.  
  748.    ------------------------------- 
  749.    -- Converting to/from GValue -- 
  750.    ------------------------------- 
  751.  
  752.    procedure Set_Text_Iter 
  753.      (Val  : in out Glib.Values.GValue; 
  754.       Iter : Gtk_Text_Iter); 
  755.    --  Set the value of the given GValue to Iter. 
  756.    --  Note that Iter is stored by reference, which means no copy of Iter 
  757.    --  is made. Iter should remain allocated as long as Val is being used. 
  758.  
  759.    procedure Get_Text_Iter 
  760.      (Val  : Glib.Values.GValue; 
  761.       Iter : out Gtk_Text_Iter); 
  762.    --  Extract the iterator from the given GValue. 
  763.    --  Note that the iterator returned is a copy of the iterator referenced 
  764.    --  by the give GValue. Modifying the iterator returned does not modify 
  765.    --  the iterator referenced by the GValue. 
  766.  
  767.    --  function Get_Marks 
  768.    --    (Iter : access Gtk_Text_Iter) 
  769.    --     return Gtk.Text_Mark.Text_Mark_List.GSList; 
  770.    --  Return a list of all Gtk_Text_Mark at this location. 
  771.    --  Because marks are not iterable (they don't take up any "space" in the 
  772.    --  buffer, they are just marks in between iterable locations), multiple 
  773.    --  marks can exist in the same place. The returned list is not in any 
  774.    --  meaningful order. 
  775.    --  ??? 
  776.  
  777.    --  function Get_Toggled_Tags 
  778.    --    (Iter       : access Gtk_Text_Iter; 
  779.    --     Toggled_On : Boolean) return Gtk.Text_Tag.Text_Tag_List.GSList; 
  780.    --  Return a list of Gtk_Text_Tag that are toggled on or off at this point. 
  781.    --  If Toggled_On is True, the list contains tags that are toggled on. If a 
  782.    --  tag is toggled on at Iter, then some non-empty range of characters 
  783.    --  following Iter has that tag applied to it. If a tag is toggled off, then 
  784.    --  some non-empty range following Iter does not have the tag applied to it. 
  785.    --  ??? 
  786.  
  787.    --  function Get_Attributes 
  788.    --    (Iter   : Gtk_Text_Iter; 
  789.    --     Values : access Gtk.Text_Attributes.Gtk_Text_Attributes_Record'Class) 
  790.    --     return Boolean; 
  791.    --  ??? Gtk_Text_Attributes is defined in gtktexttag.h 
  792.    --  Compute the effect of any tags applied to this spot in the text. 
  793.    --  The Values parameter should be initialized to the default settings you 
  794.    --  wish to use if no tags are in effect. Get_Attributes will modify Values, 
  795.    --  applying the effects of any tags present at Iter. If any tags affected 
  796.    --  values, the function returns True. 
  797.  
  798.    ------------------------------ 
  799.    -- Moving around the buffer -- 
  800.    ------------------------------ 
  801.  
  802.    --  function Forward_Find_Char 
  803.    --    (Iter      : access Gtk_Text_Iter; 
  804.    --     Pred      : Gtk_Text_Char_Predicate; 
  805.    --     User_Data : gpointer; 
  806.    --     Limit     : access Gtk_Text_Iter) 
  807.    --     return Boolean; 
  808.    --  ??? Need to be put in a generic package... 
  809.    --  And also needs a binding to gunichar 
  810.  
  811.    --  function Backward_Find_Char 
  812.    --    (Iter      : access Gtk_Text_Iter; 
  813.    --     Pred      : Gtk_Text_Char_Predicate; 
  814.    --     User_Data : gpointer; 
  815.    --     Limit     : access Gtk_Text_Iter) 
  816.    --     return Boolean; 
  817.    --  ??? Need to be put in a generic package. 
  818.    --  And also needs a binding to gunichar. 
  819.  
  820. private 
  821.    function C_Gtk_Text_Iter_Size return Gint; 
  822.    pragma Import (C, C_Gtk_Text_Iter_Size, "ada_c_gtk_text_iter_size"); 
  823.  
  824.    type Gtk_Text_Iter is limited record 
  825.       Dummy1  : System.Address; 
  826.       Dummy2  : System.Address; 
  827.       Dummy3  : Gint; 
  828.       Dummy4  : Gint; 
  829.       Dummy5  : Gint; 
  830.       Dummy6  : Gint; 
  831.       Dummy7  : Gint; 
  832.       Dummy8  : Gint; 
  833.       Dummy9  : System.Address; 
  834.       Dummy10 : System.Address; 
  835.       Dummy11 : Gint; 
  836.       Dummy12 : Gint; 
  837.       Dummy13 : Gint; 
  838.       Dummy14 : System.Address; 
  839.    end record; 
  840.    pragma Convention (C, Gtk_Text_Iter); 
  841.    --  Note that part of the implementation of this package assumes that this 
  842.    --  type is a limited record. If for some reason this can no longer remain 
  843.    --  the case, then it needs to be modified. (See note (2) at the beginning 
  844.    --  of the body of this package). 
  845.    --  Similarly, part of the implementation of the following packages depend 
  846.    --  on this assumption: 
  847.    --    - Gtk.Text_View 
  848.  
  849.    pragma Import (C, Get_Type,        "gtk_text_iter_get_type"); 
  850.    pragma Import (C, Get_Offset,      "gtk_text_iter_get_offset"); 
  851.    pragma Import (C, Get_Line,        "gtk_text_iter_get_line"); 
  852.    pragma Import (C, Get_Line_Offset, "gtk_text_iter_get_line_offset"); 
  853.    pragma Import (C, Get_Line_Index,  "gtk_text_iter_get_line_index"); 
  854.    pragma Import 
  855.      (C, Get_Visible_Line_Offset, "gtk_text_iter_get_visible_line_offset"); 
  856.    pragma Import 
  857.      (C, Get_Visible_Line_Index, "gtk_text_iter_get_visible_line_index"); 
  858.    pragma Import (C, Get_Chars_In_Line, "gtk_text_iter_get_chars_in_line"); 
  859.    pragma Import (C, Get_Bytes_In_Line, "gtk_text_iter_get_bytes_in_line"); 
  860.    pragma Import (C, Forward_To_End,    "gtk_text_iter_forward_to_end"); 
  861.    pragma Import (C, Compare,           "gtk_text_iter_compare"); 
  862.    pragma Import (C, Order,             "gtk_text_iter_order"); 
  863.    pragma Import (C, Set_Text_Iter,     "g_value_set_pointer"); 
  864.    --  External binding: g_value_set_pointer 
  865.  
  866. end Gtk.Text_Iter; 
  867.  
  868. --  No binding: gtk_text_iter_copy 
  869. --  No binding: gtk_text_iter_free 
  870.  
  871. --  Binding is in gtk-text_buffer.ads 
  872. --  No binding: gtk_text_iter_get_buffer