1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  5. --                     Copyright (C) 1998-2014, AdaCore                     -- 
  6. --                                                                          -- 
  7. -- This library is free software;  you can redistribute it and/or modify it -- 
  8. -- under terms of the  GNU General Public License  as published by the Free -- 
  9. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  10. -- version. This library is distributed in the hope that it will be useful, -- 
  11. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  12. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  13. --                                                                          -- 
  14. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  15. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  16. -- version 3.1, as published by the Free Software Foundation.               -- 
  17. --                                                                          -- 
  18. -- You should have received a copy of the GNU General Public License and    -- 
  19. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  20. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  21. -- <http://www.gnu.org/licenses/>.                                          -- 
  22. --                                                                          -- 
  23. ------------------------------------------------------------------------------ 
  24.  
  25. --  <description> 
  26. -- 
  27. --  This package implements a generic double-linked list. 
  28. --  Such lists are used throughout GtkAda to contain lists of widgets 
  29. --  (for the children of containers, or for the list of selected widgets 
  30. --  in a Gtk_Clist for instance), list of strings (for Gtk_Combo_Box),... 
  31. -- 
  32. --  They provide a common interface to traverse these lists. 
  33. -- 
  34. --  One useful note: you should only Free the lists that you have allocated 
  35. --  yourself, and not the lists that are returned by the subprograms in 
  36. --  GtkAda and should be left under GtkAda's control. 
  37. -- 
  38. --  See the example below for an example on how to traverse a list. 
  39. -- 
  40. --  Instantiating the package Generic_List requires two functions to convert 
  41. --  back and forth between your data type and a System.Address which is the 
  42. --  type stored at the C level. 
  43. --  Note that the lists used in GtkAda already have associated packages, like 
  44. --  Gtk.Enums.Gint_List, Gtk.Enums.String_List or Gtk.Widget.Widget_List. 
  45. -- 
  46. --  </description> 
  47. --  <c_version>1.2.6</c_version> 
  48. --  <group>Glib, the general-purpose library</group> 
  49.  
  50. with System; 
  51.  
  52. package Glib.Glist is 
  53.  
  54.    generic 
  55.       --  <doc_ignore> 
  56.  
  57.       type Gpointer (<>) is private; 
  58.       with function Convert (P : Gpointer) return System.Address is <>; 
  59.       with function Convert (S : System.Address) return Gpointer is <>; 
  60.  
  61.       --  </doc_ignore> 
  62.  
  63.    package Generic_List is 
  64.  
  65.       type Glist is private; 
  66.       --  This type is both a list and an item in the list. 
  67.       --  Each item points to its successor. 
  68.  
  69.       Null_List : constant Glist; 
  70.  
  71.       procedure Alloc (List : out Glist); 
  72.       --  Allocate a new item in the list. 
  73.       --  This item isn't associated with any data. 
  74.       --  You probably don't have to use this subprogram, since Append, 
  75.       --  Insert, Prepend, etc. already handle the allocation for you and 
  76.       --  give a new value to the item. 
  77.  
  78.       procedure Append (List : in out Glist; Data : Gpointer); 
  79.       --  Add a new item at the end of the list, and stores the new list 
  80.       --  directly back in List. 
  81.       --  The complexity of this operation is O(n) 
  82.  
  83.       function Concat (List1 : Glist; List2 : Glist) return Glist; 
  84.       --  Concatenate two lists, and return the result. 
  85.       --  List2 is added at the end of List1. 
  86.       --  The complexity is O(n1) (depends on the size of List1). 
  87.  
  88.       procedure Insert 
  89.         (List     : in out Glist; 
  90.          Data     : Gpointer; 
  91.          Position : Gint); 
  92.       --  Insert an item in the middle of a list. 
  93.       --  If Position is 0, the item is added at the beginning of the list, if 
  94.       --  it is negative the item is added at the end. 
  95.       --  The complexity is O(Position). 
  96.  
  97.       function Find (List : Glist; Data : Gpointer) return Glist; 
  98.       --  Find a value in the list, and return the first item that contains it. 
  99.       --  Note that this function will not work if the function Convert does 
  100.       --  not return the same value for two identical values. 
  101.  
  102.       function First (List : Glist) return Glist; 
  103.       --  Return the first item in the list. 
  104.       --  Note that if List is in fact an item of a larger list, the return 
  105.       --  value is the first item in the larger list itself. 
  106.  
  107.       procedure Free (List : in out Glist); 
  108.       --  Free the list (but does not free the data in each of its elements). 
  109.       --  This only frees the memory associated with the list itself. 
  110.       --  You should only use this function on the lists that 
  111.       --  you have created yourself, not on the list that are returned by some 
  112.       --  functions in GtkAda (like Gtk.Clist.Get_Selection). These functions 
  113.       --  return directly the list managed by the underlying C widget, and you 
  114.       --  should never free the result yourself. 
  115.       -- 
  116.       --  Note also that the memory might not be actually freed. For efficiency 
  117.       --  reasons, GtkAda will keep the memory allocated and try to reuse it as 
  118.       --  much as possible. 
  119.  
  120.       function Get_Data (List : Glist) return Gpointer; 
  121.       --  Return the value pointed to by List. 
  122.       --  The System.Address container in the C list is converted to a Gpointer 
  123.       --  through a call to Convert. 
  124.  
  125.       function Get_Data_Address (List : Glist) return System.Address; 
  126.       --  Return directly the System.Address contained in the C list. 
  127.       --  This is used mainly internally in GtkAda to implement String lists, 
  128.       --  and you should not have to use this subprogram yourself. 
  129.  
  130.       --  <doc_ignore> 
  131.       function Get_Gpointer (List : Glist) return Gpointer; 
  132.       --  Sometimes, the data is not stored in the "data" field 
  133.       --  of each cell, but rather at each cell. In such cases, 
  134.       --  to retrieve the address of the data, we need to return 
  135.       --  the address of the cell itself, insted of the address 
  136.       --  pointed to by data. 
  137.       -- 
  138.       --  Ex: the Gtk_Ctree row_list. 
  139.       --  </doc_ignore> 
  140.  
  141.       function Index (List : Glist; Data : Gpointer) return Gint; 
  142.       --  Return the index of the first element in List that contains Data. 
  143.       --  Note that this function is irrelevant if Convert does not return the 
  144.       --  same value for two identical data. 
  145.  
  146.       function Last (List : Glist) return Glist; 
  147.       --  Return the last element in the list. 
  148.  
  149.       function Length (List : Glist) return Guint; 
  150.       --  Return the number of elements in the list. 
  151.       --  The last item's index is Length - 1. 
  152.  
  153.       procedure List_Reverse (List : in out Glist); 
  154.       --  Reverse the order of the list (the last item becomes the first, etc.) 
  155.  
  156.       function Next (List : Glist) return Glist; 
  157.       --  Returns the Item following List in the global list that contains 
  158.       --  both. 
  159.       --  If there is no such item, return Null_List. This is how you 
  160.       --  stop iterating over a list. 
  161.  
  162.       function Nth (List : Glist; N : Guint) return Glist; 
  163.       --  Give the nth item following LIST in the global list that 
  164.       --  contains both. 
  165.       --  If there is no such item, return Null_List. 
  166.  
  167.       function Nth_Data (List : Glist; N : Guint) return Gpointer; 
  168.       --  Return the Data contained in the N-th item of List. 
  169.       --  The result is undefined if there is no such item in the list. 
  170.       --  The actual result in that case is the result of 
  171.       --      Convert (System.Null_Address); 
  172.       --  which might not mean anything. 
  173.  
  174.       function Position (List : Glist; Link : Glist) return Gint; 
  175.       --  Return the position of Link in the List. 
  176.       --  If Link is not contained in the list, -1 is returned. 
  177.  
  178.       procedure Prepend (List : in out Glist; Data : Gpointer); 
  179.       --  Add an item at the beginning of the list. 
  180.       --  This operation always succeed. 
  181.  
  182.       function Prev (List : Glist) return Glist; 
  183.       --  Return the item before List in the global list that contains both. 
  184.       --  Return Null_List if there is no such item. 
  185.  
  186.       procedure Remove (List : in out Glist; Data : Gpointer); 
  187.       --  Remove the first item in List that contains Data. 
  188.       --  Note that this operation can succeed only if Convert always return 
  189.       --  the same address for a given value. 
  190.  
  191.       procedure Remove_Link (List : in out Glist; Link : Glist); 
  192.       --  Remove Link from the list to which it belongs. 
  193.       --  If that list is not List, no error is returned, but Link is removed 
  194.       --  anyway. 
  195.  
  196.       function Is_Created (List : Glist) return Boolean; 
  197.       --  Return True if there is a C widget associated with List. 
  198.  
  199.       ------------------------ 
  200.       -- Internal functions -- 
  201.       ------------------------ 
  202.       --  Please do not use the following functions. They are used internally 
  203.       --  by GtkAda. 
  204.       --  <doc_ignore> 
  205.  
  206.       function Get_Object (Obj : Glist) return System.Address; 
  207.       --  Returns the C object contained in Obj. 
  208.       pragma Inline (Get_Object); 
  209.  
  210.       procedure Set_Object (Obj : in out Glist; Value : System.Address); 
  211.       --  Modifies the C object contained in Obj. 
  212.       pragma Inline (Set_Object); 
  213.  
  214.       --  </doc_ignore> 
  215.  
  216.    private 
  217.  
  218.       type Glist is record 
  219.          Ptr : System.Address := System.Null_Address; 
  220.       end record; 
  221.  
  222.       Null_List : constant Glist := (Ptr => System.Null_Address); 
  223.    end Generic_List; 
  224.  
  225. end Glib.Glist; 
  226.  
  227. --  <example> 
  228. --  <include>../examples/documentation/glist_traverse.adb</include> 
  229. --  </example>