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