1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2006 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_Tree_Model_Filter is a tree model which wraps another tree model, and 
  26. --  can do the following things: 
  27. -- 
  28. --  - Filter specific rows, based on data from a "visible column", a column 
  29. --    storing booleans indicating whether the row should be filtered or not, or 
  30. --    based on the return value of a "visible function", which gets a model, 
  31. --    iter and user_data and returns a boolean indicating whether the row 
  32. --    should be filtered or not. 
  33. -- 
  34. --  - Modify the "appearance" of the model, using a modify function. This is 
  35. --    extremely powerful and allows for just changing some values and also for 
  36. --    creating a completely different model based on the given child model. 
  37. -- 
  38. --  - Set a different root node, also known as a "virtual root". You can pass 
  39. --    in a Gtk_Tree_Path indicating the root node for the filter at 
  40. --    construction time. 
  41. --  </description> 
  42. --  <c_version>2.8.17</c_version> 
  43. --  <group>Trees and Lists</group> 
  44. --  <testgtk>create_tree_filter.adb</testgtk> 
  45.  
  46. with Glib.Types; 
  47. with Glib.Values; 
  48. with Gtk.Tree_Dnd; 
  49. with Gtk.Tree_Model; 
  50.  
  51. package Gtk.Tree_Model_Filter is 
  52.    type Gtk_Tree_Model_Filter_Record is 
  53.      new Gtk.Tree_Model.Gtk_Tree_Model_Record with null record; 
  54.    type Gtk_Tree_Model_Filter is access all Gtk_Tree_Model_Filter_Record'Class; 
  55.  
  56.    procedure Gtk_New 
  57.      (Model       : out Gtk_Tree_Model_Filter; 
  58.       Child_Model : access Gtk.Tree_Model.Gtk_Tree_Model_Record'Class; 
  59.       Root        : Gtk.Tree_Model.Gtk_Tree_Path := null); 
  60.    procedure Initialize 
  61.      (Model       : access Gtk_Tree_Model_Filter_Record'Class; 
  62.       Child_Model : access Gtk.Tree_Model.Gtk_Tree_Model_Record'Class; 
  63.       Root        : Gtk.Tree_Model.Gtk_Tree_Path := null); 
  64.    --  Creates a new tree model, with Child_Model as the child_model 
  65.    --  and Root as the virtual root (or the same root as Child_Model by 
  66.    --  default). 
  67.  
  68.    function Get_Type return Glib.GType; 
  69.    --  Returns the internal type used for a Gtk_Tree_Model_Filter 
  70.  
  71.    ----------------- 
  72.    -- Child model -- 
  73.    ----------------- 
  74.    --  The tree model filter wraps another model, and offers functions to 
  75.    --  convert from one to the other. Generally speaking, you can change data 
  76.    --  on either of the two models, and these changes will be reflected 
  77.    --  graphically automatically. 
  78.  
  79.    function Get_Model 
  80.      (Filter : access Gtk_Tree_Model_Filter_Record) 
  81.       return Gtk.Tree_Model.Gtk_Tree_Model; 
  82.    --  Returns a pointer to the child model of Filter. 
  83.  
  84.    procedure Convert_Child_Iter_To_Iter 
  85.      (Filter      : access Gtk_Tree_Model_Filter_Record; 
  86.       Filter_Iter : out Gtk.Tree_Model.Gtk_Tree_Iter; 
  87.       Child_Iter  : Gtk.Tree_Model.Gtk_Tree_Iter); 
  88.    --  Sets Filter_Iter to point to the row in Filter that corresponds to the 
  89.    --  row pointed at by Child_Iter. 
  90.  
  91.    function Convert_Child_Path_To_Path 
  92.      (Filter     : access Gtk_Tree_Model_Filter_Record; 
  93.       Child_Path : Gtk.Tree_Model.Gtk_Tree_Path) 
  94.       return Gtk.Tree_Model.Gtk_Tree_Path; 
  95.    --  Converts Child_Path to a path relative to Filter. That is, Child_Path 
  96.    --  points to a path in the child model. The returned path will point to the 
  97.    --  same row in the filtered model. If Child_Path isn't a valid path on the 
  98.    --  child model, then null is returned. 
  99.    --  The returned value must be freed with Path_Free. 
  100.  
  101.    procedure Convert_Iter_To_Child_Iter 
  102.      (Filter      : access Gtk_Tree_Model_Filter_Record; 
  103.       Child_Iter  : out Gtk.Tree_Model.Gtk_Tree_Iter; 
  104.       Filter_Iter : Gtk.Tree_Model.Gtk_Tree_Iter); 
  105.    --  Sets Child_Iter to point to the row pointed to by Filter_Iter. 
  106.  
  107.    function Convert_Path_To_Child_Path 
  108.      (Filter      : access Gtk_Tree_Model_Filter_Record; 
  109.       Filter_Path : Gtk.Tree_Model.Gtk_Tree_Path) 
  110.       return Gtk.Tree_Model.Gtk_Tree_Path; 
  111.    --  Converts Filter_Path to a path on the child model of Filter. That is, 
  112.    --  Filter_Path points to a location in Filter. The returned path will point 
  113.    --  to the same location in the model not being filtered. If Filter_Path 
  114.    --  does not point to a location in the child model, null is returned. 
  115.    --  The returned value must be freed with Path_Free. 
  116.  
  117.    -------------------------- 
  118.    --  Changing visibility -- 
  119.    -------------------------- 
  120.    --  One of the capabilities of a Gtk_Tree_Model_Filter is to hide some of 
  121.    --  the rows of its child model, so that they are not visible on the screen. 
  122.  
  123.    procedure Set_Visible_Column 
  124.      (Filter : access Gtk_Tree_Model_Filter_Record; Column : Gint); 
  125.    --  Sets Column of the child_model to be the column where Filter should 
  126.    --  look for visibility information. Columns should be a column of type 
  127.    --  GType_Boolean, where True means that a row is visible, and False 
  128.    --  if not. 
  129.  
  130.    type Gtk_Tree_Model_Filter_Visible_Func is access function 
  131.      (Model : access Gtk.Tree_Model.Gtk_Tree_Model_Record'Class; 
  132.       Iter  : Gtk.Tree_Model.Gtk_Tree_Iter) return Boolean; 
  133.    --  Called for each row in the model to decide whether or not it should be 
  134.    --  visible. True indicates the row should be made visible. 
  135.    --  Model is the child model, and Iter points into it. 
  136.  
  137.    procedure Set_Visible_Func 
  138.      (Filter  : access Gtk_Tree_Model_Filter_Record; 
  139.       Func    : Gtk_Tree_Model_Filter_Visible_Func); 
  140.    --  Sets the visible function used when filtering the Filter to be Func. The 
  141.    --  function should return True if the given row should be visible and False 
  142.    --  otherwise. 
  143.    --  If the condition calculated by the function changes over time (e.g. 
  144.    --  because it depends on some global parameters), you must call Refilter to 
  145.    --  keep the visibility information of the model uptodate. 
  146.  
  147.    generic 
  148.       type Data_Type (<>) is private; 
  149.    package Visible_Funcs is 
  150.       type Gtk_Tree_Model_Filter_Visible_Func is access function 
  151.         (Model : access Gtk.Tree_Model.Gtk_Tree_Model_Record'Class; 
  152.          Iter  : Gtk.Tree_Model.Gtk_Tree_Iter; 
  153.          Data  : Data_Type) return Boolean; 
  154.  
  155.       type Destroy_Notify is access procedure (Data : in out Data_Type); 
  156.       --  Destroys the memory allocated for Data 
  157.  
  158.       procedure Set_Visible_Func 
  159.         (Filter  : access Gtk_Tree_Model_Filter_Record'Class; 
  160.          Func    : Gtk_Tree_Model_Filter_Visible_Func; 
  161.          Data    : Data_Type; 
  162.          Destroy : Destroy_Notify := null); 
  163.       --  Same as above, but the application can pass addition data to the 
  164.       --  function 
  165.  
  166.    private 
  167.       --  <doc_ignore> 
  168.       type Data_Type_Access is access Data_Type; 
  169.       type Data_Type_Record is record 
  170.          Func    : Gtk_Tree_Model_Filter_Visible_Func; 
  171.          Destroy : Destroy_Notify; 
  172.          Data    : Data_Type_Access; 
  173.       end record; 
  174.       type Data_Type_Record_Access is access Data_Type_Record; 
  175.       pragma Convention (C, Data_Type_Record_Access); 
  176.  
  177.       procedure Internal_Destroy_Notify (Data : Data_Type_Record_Access); 
  178.       pragma Convention (C, Internal_Destroy_Notify); 
  179.  
  180.       function Internal_Filter_Visible_Func 
  181.         (Model : System.Address; 
  182.          Iter  : System.Address; 
  183.          Data  : Data_Type_Record_Access) return Gboolean; 
  184.       pragma Convention (C, Internal_Filter_Visible_Func); 
  185.  
  186.       --  </doc_ignore> 
  187.    end Visible_Funcs; 
  188.  
  189.    procedure Refilter (Filter : access Gtk_Tree_Model_Filter_Record); 
  190.    --  Emits row_changed for each row in the child model, which causes 
  191.    --  the filter to re-evaluate whether a row is visible or not. 
  192.  
  193.    -------------------------------- 
  194.    -- Modifying displayed values -- 
  195.    -------------------------------- 
  196.    --  The other capability of a Gtk_Tree_Model_Filter is to modify on the fly 
  197.    --  the displayed value (ie we do not display directly what is in the child 
  198.    --  model, but change the value in memory, not in the model, on the fly) 
  199.  
  200.    type Gtk_Tree_Model_Filter_Modify_Func is access procedure 
  201.      (Model  : access Gtk_Tree_Model_Filter_Record'Class; 
  202.       Iter   : Gtk.Tree_Model.Gtk_Tree_Iter; 
  203.       Value  : out Glib.Values.GValue; 
  204.       Column : Gint); 
  205.    --  A function which calculates display values from raw values in the model. 
  206.    --  It must fill value with the display value for the column column in the 
  207.    --  row indicated by iter. 
  208.    --  Since this function is called for each data access, it's not a 
  209.    --  particularly efficient operation. 
  210.    --  Value has already been initializes to the right type (ie the one defined 
  211.    --  in Set_Modify_Func for this column). Iter references the filter model, 
  212.    --  not the child model. When implementating this procedure, make sure you 
  213.    --  do not call Get_String, Get_Int,... on Model itself, since that would 
  214.    --  create a recursion. You must apply all operations to Get_Model (Model), 
  215.    --  after converting Iter to a Child_Iter through Convert_Iter_To_Child_Iter 
  216.  
  217.    procedure Set_Modify_Func 
  218.      (Filter    : access Gtk_Tree_Model_Filter_Record; 
  219.       Types     : Glib.GType_Array; 
  220.       Func      : Gtk_Tree_Model_Filter_Modify_Func); 
  221.    --  Types can be used to override the column types that will be made visible 
  222.    --  to the parent model/view. 
  223.    --  Func is used to specify the modify function. The modify function will 
  224.    --  get called for *each* data access, the goal of the modify function is to 
  225.    --  return the data which should be displayed at the location specified 
  226.    --  using the parameters of the modify function. 
  227.  
  228.    generic 
  229.       type Data_Type (<>) is private; 
  230.    package Modify_Funcs is 
  231.       type Gtk_Tree_Model_Filter_Modify_Func is access procedure 
  232.         (Model     : access Gtk_Tree_Model_Filter_Record'Class; 
  233.          Iter      : Gtk.Tree_Model.Gtk_Tree_Iter; 
  234.          Value     : out Glib.Values.GValue; 
  235.          Column    : Gint; 
  236.          User_Data : Data_Type); 
  237.  
  238.       type Destroy_Notify is access procedure (Data : in out Data_Type); 
  239.       --  Destroys the memory allocated for Data 
  240.  
  241.       procedure Set_Modify_Func 
  242.         (Filter    : access Gtk_Tree_Model_Filter_Record'Class; 
  243.          Types     : Glib.GType_Array; 
  244.          Func      : Gtk_Tree_Model_Filter_Modify_Func; 
  245.          Data      : Data_Type; 
  246.          Destroy   : Destroy_Notify := null); 
  247.       --  Same as above, but the application can pass extra data to the 
  248.       --  function. 
  249.  
  250.    private 
  251.       --  <doc_ignore> 
  252.       type Data_Type_Access is access Data_Type; 
  253.       type Data_Type_Record is record 
  254.          Func    : Gtk_Tree_Model_Filter_Modify_Func; 
  255.          Destroy : Destroy_Notify; 
  256.          Data    : Data_Type_Access; 
  257.       end record; 
  258.       type Data_Type_Record_Access is access Data_Type_Record; 
  259.       pragma Convention (C, Data_Type_Record_Access); 
  260.  
  261.       procedure Internal_Destroy_Notify (Data : Data_Type_Record_Access); 
  262.       pragma Convention (C, Internal_Destroy_Notify); 
  263.  
  264.       procedure Internal_Filter_Modify_Func 
  265.         (Model  : System.Address; 
  266.          Iter   : System.Address; 
  267.          Value  : out Glib.Values.GValue; 
  268.          Column : Gint; 
  269.          Data   : Data_Type_Record_Access); 
  270.       pragma Convention (C, Internal_Filter_Modify_Func); 
  271.       --  </doc_ignore> 
  272.    end Modify_Funcs; 
  273.  
  274.    ---------- 
  275.    -- Misc -- 
  276.    ---------- 
  277.  
  278.    procedure Clear_Cache (Filter : access Gtk_Tree_Model_Filter_Record); 
  279.    --  This function should almost never be called. It clears the Filter of any 
  280.    --  cached iterators that haven't been reffed with Gtk.Tree_Model.Ref_Node. 
  281.    --  This might be useful if the child model being filtered is static (and 
  282.    --  doesn't change often) and there has been a lot of unreffed access to 
  283.    --  nodes. As a side effect of this function, all unrefed iters will be 
  284.    --  invalid. 
  285.  
  286.    ---------------- 
  287.    -- Interfaces -- 
  288.    ---------------- 
  289.    --  This class implements several interfaces. See Glib.Types 
  290.    -- 
  291.    --  - "Gtk_Tree_Drag_Source" 
  292.    --    This interface allows this widget to act as a dnd source 
  293.  
  294.    package Implements_Drag_Source is new Glib.Types.Implements 
  295.      (Gtk.Tree_Dnd.Gtk_Tree_Drag_Source, 
  296.       Gtk_Tree_Model_Filter_Record, 
  297.       Gtk_Tree_Model_Filter); 
  298.    function "+" 
  299.      (Model : access Gtk_Tree_Model_Filter_Record'Class) 
  300.       return Gtk.Tree_Dnd.Gtk_Tree_Drag_Source 
  301.       renames Implements_Drag_Source.To_Interface; 
  302.    function "-" 
  303.      (Drag_Source : Gtk.Tree_Dnd.Gtk_Tree_Drag_Source) 
  304.       return Gtk_Tree_Model_Filter 
  305.       renames Implements_Drag_Source.To_Object; 
  306.    --  Converts to and from the Gtk_Tree_Drag_Source interface 
  307.  
  308. private 
  309.    pragma Import (C, Get_Type, "gtk_tree_model_filter_get_type"); 
  310. end Gtk.Tree_Model_Filter;