1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2001-2013, 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. ----------------------------------------------------------------------- 
  28.  
  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> 
  36.  
  37. with Gdk.Pixbuf; 
  38. with Glib.Object; 
  39. with Glib.Values; 
  40. with Gtk.Text_Attributes; 
  41. with Gtk.Text_Child; 
  42. with Gtk.Text_Tag; 
  43. with Interfaces.C.Strings; 
  44. with System; 
  45.  
  46. package Gtk.Text_Iter is 
  47.  
  48.    type Gtk_Text_Iter is limited private; 
  49.    type Gtk_Text_Iter_Access is access all Gtk_Text_Iter; 
  50.  
  51.    function Get_Type return Glib.GType; 
  52.    --  Return the internal type used for a Gtk_Text_Iter 
  53.  
  54.    procedure Copy (Source : Gtk_Text_Iter; Dest : out Gtk_Text_Iter); 
  55.    --  Create a copy of Source. 
  56.  
  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 
  65.  
  66.    procedure Forward_Char (Iter : in out Gtk_Text_Iter; 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. 
  73.  
  74.    procedure Backward_Char (Iter : in out Gtk_Text_Iter; 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. 
  79.  
  80.    procedure Forward_Chars 
  81.      (Iter   : in out Gtk_Text_Iter; 
  82.       Count  : Gint := 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. 
  90.  
  91.    procedure Backward_Chars 
  92.      (Iter   : in out Gtk_Text_Iter; 
  93.       Count  : Gint := 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. 
  101.  
  102.    procedure Set_Offset (Iter : in out Gtk_Text_Iter; Char_Offset : Gint); 
  103.    function  Get_Offset (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  109.  
  110.    ----------- 
  111.    -- Words -- 
  112.    ----------- 
  113.    --  Characters are grouped together into words. Their exact definition 
  114.    --  depends on the current language (see Pango.Language). 
  115.  
  116.    function Starts_Word (Iter : Gtk_Text_Iter) 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. 
  121.  
  122.    function Ends_Word (Iter : Gtk_Text_Iter) 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). 
  127.  
  128.    function Inside_Word (Iter : Gtk_Text_Iter) 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). 
  133.  
  134.    procedure Forward_Word_End 
  135.      (Iter : in out Gtk_Text_Iter; 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). 
  141.  
  142.    procedure Forward_Word_Ends 
  143.      (Iter   : in out Gtk_Text_Iter; 
  144.       Count  : Gint := 1; 
  145.       Result : out Boolean); 
  146.    --  Call Forward_Word_End up to Count times. 
  147.  
  148.    procedure Forward_Visible_Word_End 
  149.      (Iter : in out Gtk_Text_Iter; 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). 
  154.  
  155.    procedure Forward_Visible_Word_Ends 
  156.      (Iter   : in out Gtk_Text_Iter; 
  157.       Count  : Gint := 1; 
  158.       Result : out Boolean); 
  159.    --  Calls Forward_Visible_Word_End up to Count times 
  160.  
  161.    procedure Backward_Word_Start 
  162.      (Iter : in out Gtk_Text_Iter; 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. 
  166.  
  167.    procedure Backward_Word_Starts 
  168.      (Iter   : in out Gtk_Text_Iter; 
  169.       Count  : Gint := 1; 
  170.       Result : out Boolean); 
  171.    --  Call Backward_Word_Start up to Count times. 
  172.  
  173.    procedure Backward_Visible_Word_Start 
  174.      (Iter : in out Gtk_Text_Iter; 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). 
  179.  
  180.    procedure Backward_Visible_Word_Starts 
  181.      (Iter   : Gtk_Text_Iter; 
  182.       Count  : Gint := 1; 
  183.       Result : in out Boolean); 
  184.    --  Move backward up to Count previous visible word starts. 
  185.  
  186.    --------------- 
  187.    -- Sentences -- 
  188.    --------------- 
  189.    --  Words are then grouped together into sentences. 
  190.  
  191.    function Starts_Sentence (Iter : Gtk_Text_Iter) 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). 
  196.  
  197.    function Ends_Sentence (Iter : Gtk_Text_Iter) 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). 
  202.  
  203.    function Inside_Sentence (Iter : Gtk_Text_Iter) 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). 
  209.  
  210.    procedure Forward_Sentence_End 
  211.      (Iter : in out Gtk_Text_Iter; 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. 
  214.  
  215.    procedure Backward_Sentence_Start 
  216.      (Iter : in out Gtk_Text_Iter; 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. 
  220.  
  221.    procedure Forward_Sentence_Ends 
  222.      (Iter   : in out Gtk_Text_Iter; 
  223.       Count  : Gint := 1; 
  224.       Result : out Boolean); 
  225.    --  Call Forward_Sentence_End up to Count times. 
  226.  
  227.    procedure Backward_Sentence_Starts 
  228.      (Iter   : in out Gtk_Text_Iter; 
  229.       Count  : Gint := 1; 
  230.       Result : out Boolean); 
  231.    --  Call Backward_Sentence_Starts up to Count times. 
  232.  
  233.    -------------------------- 
  234.    -- Lines and paragraphs -- 
  235.    -------------------------- 
  236.    --  Sentences are grouped together to form lines and paragraphs. The 
  237.    --  definition of these is language-dependent 
  238.  
  239.    procedure Set_Line (Iter : in out Gtk_Text_Iter; Line_Number : Gint); 
  240.    function  Get_Line (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  244.  
  245.    procedure Set_Line_Offset 
  246.      (Iter : in out Gtk_Text_Iter; Char_On_Line : Gint); 
  247.    function Get_Line_Offset (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  254.  
  255.    procedure Set_Line_Index (Iter : in out Gtk_Text_Iter; Byte_On_Line : Gint); 
  256.    function Get_Line_Index (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  262.  
  263.    procedure Set_Visible_Line_Offset 
  264.      (Iter : in out Gtk_Text_Iter; Char_On_Line : Gint); 
  265.    function Get_Visible_Line_Offset (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  269.  
  270.    procedure Set_Visible_Line_Index 
  271.      (Iter : in out Gtk_Text_Iter; Byte_On_Line : Gint); 
  272.    function Get_Visible_Line_Index (Iter : Gtk_Text_Iter) return Gint; 
  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. 
  276.  
  277.    function Starts_Line (Iter : Gtk_Text_Iter) 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. 
  283.  
  284.    function Ends_Line (Iter : Gtk_Text_Iter) 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. 
  291.  
  292.    function Get_Chars_In_Line (Iter : Gtk_Text_Iter) return Gint; 
  293.    --  Return the number of characters in the line containing Iter, including 
  294.    --  the paragraph delimiters. 
  295.  
  296.    function Get_Bytes_In_Line (Iter : Gtk_Text_Iter) return Gint; 
  297.    --  Return the number of bytes in the line containing Iter, including the 
  298.    --  paragraph delimiters. 
  299.  
  300.    procedure Forward_Line (Iter : in out Gtk_Text_Iter; 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. 
  305.  
  306.    procedure Forward_Lines 
  307.      (Iter   : in out Gtk_Text_Iter; 
  308.       Count  : Gint := 1; 
  309.       Result : out Boolean); 
  310.    --  Call Forward_Line, up to Count times. 
  311.  
  312.    procedure Forward_Visible_Line 
  313.      (Iter : in out Gtk_Text_Iter; 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. 
  318.  
  319.    procedure Forward_Visible_Lines 
  320.      (Iter   : in out Gtk_Text_Iter; 
  321.       Count  : Gint := 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. 
  330.  
  331.    procedure Forward_To_Line_End 
  332.      (Iter : in out Gtk_Text_Iter; 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. 
  339.  
  340.    procedure Backward_Line (Iter : in out Gtk_Text_Iter; 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) 
  348.  
  349.    procedure Backward_Lines 
  350.      (Iter   : in out Gtk_Text_Iter; 
  351.       Count  : Gint := 1; 
  352.       Result : out Boolean); 
  353.    --  Call Backward_Line, up to Count times. 
  354.  
  355.    procedure Backward_Visible_Line 
  356.      (Iter   : in out Gtk_Text_Iter; 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.) 
  364.  
  365.    procedure Backward_Visible_Lines 
  366.      (Iter   : in out Gtk_Text_Iter; 
  367.       Count  : Gint := 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. 
  376.  
  377.    ------------ 
  378.    -- Buffer -- 
  379.    ------------ 
  380.    --  When grouped together, lines and paragraph made up the whole buffer. 
  381.  
  382.    function Is_End (Iter : Gtk_Text_Iter) 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. 
  387.  
  388.    function Is_Start (Iter : Gtk_Text_Iter) 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. 
  391.  
  392.    procedure Forward_To_End (Iter : in out Gtk_Text_Iter); 
  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. 
  396.  
  397.    ----------------------------- 
  398.    -- Reading buffer contents -- 
  399.    ----------------------------- 
  400.  
  401.    function Get_Char (Iter : Gtk_Text_Iter) return Gunichar; 
  402.    --  Return the character immediately following Iter. If Iter is at the 
  403.    --  end of the buffer, then return ASCII.NUL. 
  404.  
  405.    function Get_Char (Iter : Gtk_Text_Iter) 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. 
  411.  
  412.    function Get_Slice 
  413.      (Start   : Gtk_Text_Iter; 
  414.       The_End : Gtk_Text_Iter) return UTF8_String; 
  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. 
  423.  
  424.    function Get_Slice 
  425.      (Start   : Gtk_Text_Iter; 
  426.       The_End : Gtk_Text_Iter) 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. 
  429.  
  430.    function Get_Text 
  431.      (Start   : Gtk_Text_Iter; 
  432.       The_End : Gtk_Text_Iter) return UTF8_String; 
  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. 
  438.  
  439.    function Get_Visible_Slice 
  440.      (Start   : Gtk_Text_Iter; 
  441.       The_End : Gtk_Text_Iter) return UTF8_String; 
  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. 
  445.  
  446.    function Get_Visible_Text 
  447.      (Start   : Gtk_Text_Iter; 
  448.       The_End : Gtk_Text_Iter) return UTF8_String; 
  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. 
  452.  
  453.    function Get_Pixbuf (Iter : Gtk_Text_Iter) return Gdk.Pixbuf.Gdk_Pixbuf; 
  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. 
  457.  
  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. 
  463.  
  464.    function Begins_Tag 
  465.      (Iter : Gtk_Text_Iter; 
  466.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := 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. 
  471.  
  472.    function Ends_Tag 
  473.      (Iter : Gtk_Text_Iter; 
  474.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := 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. 
  479.  
  480.    function Toggles_Tag 
  481.      (Iter : Gtk_Text_Iter; 
  482.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := 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)". 
  485.  
  486.    function Has_Tag 
  487.      (Iter : Gtk_Text_Iter; 
  488.       Tag  : Gtk.Text_Tag.Gtk_Text_Tag := null) return Boolean; 
  489.    --  Return True if Iter is within a range tagged with Tag. 
  490.  
  491.    function Get_Tags 
  492.      (Iter : Gtk_Text_Iter) return Gtk.Text_Tag.Text_Tag_List.GSlist; 
  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. 
  496.  
  497.    procedure Forward_To_Tag_Toggle 
  498.      (Iter   : in out Gtk_Text_Iter; 
  499.       Tag    : Gtk.Text_Tag.Gtk_Text_Tag := 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. 
  506.  
  507.    procedure Backward_To_Tag_Toggle 
  508.      (Iter   : in out Gtk_Text_Iter; 
  509.       Tag    : Gtk.Text_Tag.Gtk_Text_Tag := 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. 
  516.  
  517.    function Get_Toggled_Tags 
  518.      (Iter       : Gtk_Text_Iter; 
  519.       Toggled_On : Boolean) 
  520.       return Glib.Object.Object_List.GSlist; 
  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. 
  527.  
  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. 
  534.  
  535.    function Editable 
  536.      (Iter            : Gtk_Text_Iter; 
  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. 
  543.  
  544.    function Can_Insert 
  545.      (Iter                : Gtk_Text_Iter; 
  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. 
  554.  
  555.    function Get_Language (Iter : Gtk_Text_Iter) return UTF8_String; 
  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. 
  560.  
  561.    procedure Get_Attributes 
  562.      (Iter     : Gtk_Text_Iter; 
  563.       Values   : in out Gtk.Text_Attributes.Gtk_Text_Attributes; 
  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. 
  572.  
  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. 
  580.  
  581.    function Is_Cursor_Position (Iter : Gtk_Text_Iter) 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. 
  584.  
  585.    procedure Forward_Cursor_Position 
  586.      (Iter : in out Gtk_Text_Iter; 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. 
  596.  
  597.    procedure Backward_Cursor_Position 
  598.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  599.    --  Like Forward_Cursor_Position, but moves backward. 
  600.  
  601.    procedure Forward_Cursor_Positions 
  602.      (Iter   : in out Gtk_Text_Iter; 
  603.       Count  : Gint := 1; 
  604.       Result : out Boolean); 
  605.    --  Call Forward_Cursor_Position up to Count times. 
  606.  
  607.    procedure Forward_Visible_Cursor_Position 
  608.      (Iter : in out Gtk_Text_Iter; Result : out Boolean); 
  609.    --  Moves Iter forward to the next visible cursor position. Return True if 
  610.    --  the new position is valid 
  611.  
  612.    procedure Forward_Visible_Cursor_Positions 
  613.      (Iter   : in out Gtk_Text_Iter; 
  614.       Count  : Gint := 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. 
  618.  
  619.    procedure Backward_Cursor_Positions 
  620.      (Iter   : in out Gtk_Text_Iter; 
  621.       Count  : Gint := 1; 
  622.       Result : out Boolean); 
  623.    --  Call Backward_Cursor_Position up to Count times. 
  624.  
  625.    procedure Backward_Visible_Cursor_Position 
  626.      (Iter : in out Gtk_Text_Iter;  Result : out Boolean); 
  627.    --  Moves Iter backward to the previous visible cursor position. Return 
  628.    --  True if the new position is valid. 
  629.  
  630.    procedure Backward_Visible_Cursor_Positions 
  631.      (Iter   : in out Gtk_Text_Iter; 
  632.       Count  : Gint := 1; 
  633.       Result : out Boolean); 
  634.    --  Moves up to Count visible cursor positions. Return True if the new 
  635.    --  position is valid. 
  636.  
  637.    -------------- 
  638.    -- Children -- 
  639.    -------------- 
  640.    --  The buffer can contain many widgets. They are all attached to specific 
  641.    --  anchors (see Gtk.Text_Child) 
  642.  
  643.    function Get_Child_Anchor 
  644.      (Iter : Gtk_Text_Iter) 
  645.       return Gtk.Text_Child.Gtk_Text_Child_Anchor; 
  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. 
  649.  
  650.    function Get_Marks 
  651.      (Iter : Gtk_Text_Iter) return Glib.Object.Object_List.GSlist; 
  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. 
  656.  
  657.    --------------- 
  658.    -- Searching -- 
  659.    --------------- 
  660.  
  661.    type Gtk_Text_Search_Flags is mod 2 ** 8; 
  662.    for Gtk_Text_Search_Flags'Size use Gint'Size; 
  663.  
  664.    Visible_Only : constant Gtk_Text_Search_Flags := 2 ** 0; 
  665.    Text_Only    : constant Gtk_Text_Search_Flags := 2 ** 1; 
  666.  
  667.    procedure Forward_Search 
  668.      (Iter         : Gtk_Text_Iter; 
  669.       Str          : UTF8_String; 
  670.       Flags        : Gtk_Text_Search_Flags; 
  671.       Match_Start  : out Gtk_Text_Iter; 
  672.       Match_End    : out Gtk_Text_Iter; 
  673.       Limit        : Gtk_Text_Iter; 
  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. 
  685.  
  686.    procedure Backward_Search 
  687.      (Iter         : Gtk_Text_Iter; 
  688.       Str          : UTF8_String; 
  689.       Flags        : Gtk_Text_Search_Flags; 
  690.       Match_Start  : out Gtk_Text_Iter; 
  691.       Match_End    : out Gtk_Text_Iter; 
  692.       Limit        : Gtk_Text_Iter; 
  693.       Result       : out Boolean); 
  694.    --  Same as Forward_Search, but move backward. 
  695.  
  696.    generic 
  697.       type Data_Type (<>) is private; 
  698.    package Find_Chars is 
  699.       type Gtk_Text_Char_Predicate is access function 
  700.         (Ch : Gunichar; User_Data : Data_Type) return Boolean; 
  701.  
  702.       function Forward_Find_Char 
  703.         (Iter      : Gtk_Text_Iter; 
  704.          Pred      : Gtk_Text_Char_Predicate; 
  705.          User_Data : Data_Type; 
  706.          Limit     : Gtk_Text_Iter) 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. 
  711.  
  712.       function Backward_Find_Char 
  713.         (Iter      : Gtk_Text_Iter; 
  714.          Pred      : Gtk_Text_Char_Predicate; 
  715.          User_Data : Data_Type; 
  716.          Limit     : Gtk_Text_Iter) return Boolean; 
  717.       --  Same as Forward_Find_Char, but goes backward from Iter 
  718.    end Find_Chars; 
  719.  
  720.    ----------------- 
  721.    -- Comparisons -- 
  722.    ----------------- 
  723.  
  724.    function Equal (Lhs : Gtk_Text_Iter; Rhs : Gtk_Text_Iter) 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. 
  729.  
  730.    function Compare (Lhs : Gtk_Text_Iter; Rhs : Gtk_Text_Iter) return Gint; 
  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. 
  735.  
  736.    function In_Range 
  737.      (Iter    : Gtk_Text_Iter; 
  738.       Start   : Gtk_Text_Iter; 
  739.       The_End : Gtk_Text_Iter) 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) 
  742.  
  743.    procedure Order 
  744.      (First  : in out Gtk_Text_Iter; 
  745.       Second : in out Gtk_Text_Iter); 
  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. 
  752.  
  753.    ------------------------------- 
  754.    -- Converting to/from GValue -- 
  755.    ------------------------------- 
  756.  
  757.    procedure Set_Text_Iter 
  758.      (Val  : in out Glib.Values.GValue; 
  759.       Iter : Gtk_Text_Iter); 
  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. 
  763.  
  764.    procedure Get_Text_Iter 
  765.      (Val  : Glib.Values.GValue; 
  766.       Iter : out Gtk_Text_Iter); 
  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. 
  771.  
  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.    --  ??? 
  781.  
  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.    --  ??? 
  791.  
  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. 
  802.  
  803.    ------------------------------ 
  804.    -- Moving around the buffer -- 
  805.    ------------------------------ 
  806.  
  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 
  815.  
  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. 
  824.  
  825. private 
  826.    function C_Gtk_Text_Iter_Size return Gint; 
  827.    pragma Import (C, C_Gtk_Text_Iter_Size, "ada_c_gtk_text_iter_size"); 
  828.  
  829.    type Gtk_Text_Iter is limited record 
  830.       Dummy1  : System.Address; 
  831.       Dummy2  : System.Address; 
  832.       Dummy3  : Gint; 
  833.       Dummy4  : Gint; 
  834.       Dummy5  : Gint; 
  835.       Dummy6  : Gint; 
  836.       Dummy7  : Gint; 
  837.       Dummy8  : Gint; 
  838.       Dummy9  : System.Address; 
  839.       Dummy10 : System.Address; 
  840.       Dummy11 : Gint; 
  841.       Dummy12 : Gint; 
  842.       Dummy13 : Gint; 
  843.       Dummy14 : System.Address; 
  844.    end record; 
  845.    pragma Convention (C, Gtk_Text_Iter); 
  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 
  853.  
  854.    pragma Import (C, Get_Type,        "gtk_text_iter_get_type"); 
  855.    pragma Import (C, Get_Offset,      "gtk_text_iter_get_offset"); 
  856.    pragma Import (C, Get_Line,        "gtk_text_iter_get_line"); 
  857.    pragma Import (C, Get_Line_Offset, "gtk_text_iter_get_line_offset"); 
  858.    pragma Import (C, Get_Line_Index,  "gtk_text_iter_get_line_index"); 
  859.    pragma Import 
  860.      (C, Get_Visible_Line_Offset, "gtk_text_iter_get_visible_line_offset"); 
  861.    pragma Import 
  862.      (C, Get_Visible_Line_Index, "gtk_text_iter_get_visible_line_index"); 
  863.    pragma Import (C, Get_Chars_In_Line, "gtk_text_iter_get_chars_in_line"); 
  864.    pragma Import (C, Get_Bytes_In_Line, "gtk_text_iter_get_bytes_in_line"); 
  865.    pragma Import (C, Forward_To_End,    "gtk_text_iter_forward_to_end"); 
  866.    pragma Import (C, Compare,           "gtk_text_iter_compare"); 
  867.    pragma Import (C, Order,             "gtk_text_iter_order"); 
  868.    pragma Import (C, Set_Text_Iter,     "g_value_set_pointer"); 
  869.    --  External binding: g_value_set_pointer 
  870.  
  871. end Gtk.Text_Iter; 
  872.  
  873. --  No binding: gtk_text_iter_copy 
  874. --  No binding: gtk_text_iter_free 
  875.  
  876. --  Binding is in gtk-text_buffer.ads 
  877. --  No binding: gtk_text_iter_get_buffer