1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  The Gtk.Tree_Selection.Gtk_Tree_Selection object is a helper object to 
  26. --  manage the selection for a Gtk.Tree_View.Gtk_Tree_View widget. The 
  27. --  Gtk.Tree_Selection.Gtk_Tree_Selection object is automatically created when 
  28. --  a new Gtk.Tree_View.Gtk_Tree_View widget is created, and cannot exist 
  29. --  independentally of this widget. The primary reason the 
  30. --  Gtk.Tree_Selection.Gtk_Tree_Selection objects exists is for cleanliness of 
  31. --  code and API. That is, there is no conceptual reason all these functions 
  32. --  could not be methods on the Gtk.Tree_View.Gtk_Tree_View widget instead of a 
  33. --  separate function. 
  34. -- 
  35. --  The Gtk.Tree_Selection.Gtk_Tree_Selection object is gotten from a 
  36. --  Gtk.Tree_View.Gtk_Tree_View by calling Gtk.Tree_View.Get_Selection. It can 
  37. --  be manipulated to check the selection status of the tree, as well as select 
  38. --  and deselect individual rows. Selection is done completely view side. As a 
  39. --  result, multiple views of the same model can have completely different 
  40. --  selections. Additionally, you cannot change the selection of a row on the 
  41. --  model that is not currently displayed by the view without expanding its 
  42. --  parents first. 
  43. -- 
  44. --  One of the important things to remember when monitoring the selection of a 
  45. --  view is that the Gtk.Tree_Selection.Gtk_Tree_Selection::changed signal is 
  46. --  mostly a hint. That is, it may only emit one signal when a range of rows is 
  47. --  selected. Additionally, it may on occasion emit a 
  48. --  Gtk.Tree_Selection.Gtk_Tree_Selection::changed signal when nothing has 
  49. --  happened (mostly as a result of programmers calling select_row on an 
  50. --  already selected row). 
  51. -- 
  52. --  </description> 
  53. pragma Ada_2005; 
  54.  
  55. pragma Warnings (Off, "*is already use-visible*"); 
  56. with Glib;           use Glib; 
  57. with Glib.Object;    use Glib.Object; 
  58. with Gtk.Enums;      use Gtk.Enums; 
  59. with Gtk.Tree_Model; use Gtk.Tree_Model; 
  60. with Gtk.Widget;     use Gtk.Widget; 
  61.  
  62. package Gtk.Tree_Selection is 
  63.  
  64.    type Gtk_Tree_Selection_Record is new GObject_Record with null record; 
  65.    type Gtk_Tree_Selection is access all Gtk_Tree_Selection_Record'Class; 
  66.  
  67.    --------------- 
  68.    -- Callbacks -- 
  69.    --------------- 
  70.  
  71.    type Gtk_Tree_Selection_Foreach_Func is access procedure 
  72.      (Model : Gtk.Tree_Model.Gtk_Tree_Model; 
  73.       Path  : Gtk.Tree_Model.Gtk_Tree_Path; 
  74.       Iter  : Gtk.Tree_Model.Gtk_Tree_Iter); 
  75.    --  A function used by Gtk.Tree_Selection.Selected_Foreach to map all 
  76.    --  selected rows. It will be called on every selected row in the view. 
  77.    --  "model": The Gtk.Tree_Model.Gtk_Tree_Model being viewed 
  78.    --  "path": The Gtk.Tree_Model.Gtk_Tree_Path of a selected row 
  79.    --  "iter": A Gtk.Tree_Model.Gtk_Tree_Iter pointing to a selected row 
  80.  
  81.    type Gtk_Tree_Selection_Func is access function 
  82.      (Selection               : not null access Gtk_Tree_Selection_Record'Class; 
  83.       Model                   : Gtk.Tree_Model.Gtk_Tree_Model; 
  84.       Path                    : Gtk.Tree_Model.Gtk_Tree_Path; 
  85.       Path_Currently_Selected : Boolean) return Boolean; 
  86.    --  A function used by Gtk.Tree_Selection.Set_Select_Function to filter 
  87.    --  whether or not a row may be selected. It is called whenever a row's 
  88.    --  state might change. A return value of True indicates to Selection that 
  89.    --  it is okay to change the selection. 
  90.    --  "selection": A Gtk.Tree_Selection.Gtk_Tree_Selection 
  91.    --  "model": A Gtk.Tree_Model.Gtk_Tree_Model being viewed 
  92.    --  "path": The Gtk.Tree_Model.Gtk_Tree_Path of the row in question 
  93.    --  "path_currently_selected": True, if the path is currently selected 
  94.  
  95.    ------------------ 
  96.    -- Constructors -- 
  97.    ------------------ 
  98.  
  99.    function Get_Type return Glib.GType; 
  100.    pragma Import (C, Get_Type, "gtk_tree_selection_get_type"); 
  101.  
  102.    ------------- 
  103.    -- Methods -- 
  104.    ------------- 
  105.  
  106.    function Count_Selected_Rows 
  107.       (Selection : not null access Gtk_Tree_Selection_Record) return Gint; 
  108.    --  Returns the number of rows that have been selected in Tree. 
  109.    --  Since: gtk+ 2.2 
  110.  
  111.    function Get_Mode 
  112.       (Selection : not null access Gtk_Tree_Selection_Record) 
  113.        return Gtk.Enums.Gtk_Selection_Mode; 
  114.    --  Gets the selection mode for Selection. See Gtk.Tree_Selection.Set_Mode. 
  115.  
  116.    procedure Set_Mode 
  117.       (Selection : not null access Gtk_Tree_Selection_Record; 
  118.        The_Type  : Gtk.Enums.Gtk_Selection_Mode); 
  119.    --  Sets the selection mode of the Selection. If the previous type was 
  120.    --  GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was 
  121.    --  previously selected. 
  122.    --  "type": The selection mode 
  123.  
  124.    procedure Get_Select_Function 
  125.       (Selection : not null access Gtk_Tree_Selection_Record); 
  126.    --  Returns the current selection function. 
  127.    --  Since: gtk+ 2.14 
  128.  
  129.    procedure Set_Select_Function 
  130.       (Selection : not null access Gtk_Tree_Selection_Record; 
  131.        Func      : Gtk_Tree_Selection_Func); 
  132.    --  Sets the selection function. 
  133.    --  If set, this function is called before any node is selected or 
  134.    --  unselected, giving some control over which nodes are selected. The 
  135.    --  select function should return True if the state of the node may be 
  136.    --  toggled, and False if the state of the node should be left unchanged. 
  137.    --  "func": The selection function. May be null 
  138.  
  139.    procedure Get_Selected 
  140.       (Selection : not null access Gtk_Tree_Selection_Record; 
  141.        Model     : out Gtk.Tree_Model.Gtk_Tree_Model; 
  142.        Iter      : out Gtk.Tree_Model.Gtk_Tree_Iter); 
  143.    --  Sets Iter to the currently selected node if Selection is set to 
  144.    --  GTK_SELECTION_SINGLE or GTK_SELECTION_BROWSE. Iter may be NULL if you 
  145.    --  just want to test if Selection has any selected nodes. Model is filled 
  146.    --  with the current model as a convenience. This function will not work if 
  147.    --  you use Selection is GTK_SELECTION_MULTIPLE. 
  148.    --  "model": A pointer to set to the Gtk.Tree_Model.Gtk_Tree_Model, or 
  149.    --  NULL. 
  150.    --  "iter": The Gtk.Tree_Model.Gtk_Tree_Iter, or NULL. 
  151.  
  152.    function Get_Tree_View 
  153.       (Selection : not null access Gtk_Tree_Selection_Record) 
  154.        return Gtk.Widget.Gtk_Widget; 
  155.    --  Returns the tree view associated with Selection. 
  156.  
  157.    function Get_User_Data 
  158.       (Selection : not null access Gtk_Tree_Selection_Record) 
  159.        return System.Address; 
  160.    --  Returns the user data for the selection function. 
  161.  
  162.    function Iter_Is_Selected 
  163.       (Selection : not null access Gtk_Tree_Selection_Record; 
  164.        Iter      : Gtk.Tree_Model.Gtk_Tree_Iter) return Boolean; 
  165.    --  Returns True if the row at Iter is currently selected. 
  166.    --  "iter": A valid Gtk.Tree_Model.Gtk_Tree_Iter 
  167.  
  168.    function Path_Is_Selected 
  169.       (Selection : not null access Gtk_Tree_Selection_Record; 
  170.        Path      : Gtk.Tree_Model.Gtk_Tree_Path) return Boolean; 
  171.    --  Returns True if the row pointed to by Path is currently selected. If 
  172.    --  Path does not point to a valid location, False is returned 
  173.    --  "path": A Gtk.Tree_Model.Gtk_Tree_Path to check selection on. 
  174.  
  175.    procedure Select_All 
  176.       (Selection : not null access Gtk_Tree_Selection_Record); 
  177.    --  Selects all the nodes. Selection must be set to GTK_SELECTION_MULTIPLE 
  178.    --  mode. 
  179.  
  180.    procedure Select_Iter 
  181.       (Selection : not null access Gtk_Tree_Selection_Record; 
  182.        Iter      : Gtk.Tree_Model.Gtk_Tree_Iter); 
  183.    --  Selects the specified iterator. 
  184.    --  "iter": The Gtk.Tree_Model.Gtk_Tree_Iter to be selected. 
  185.  
  186.    procedure Select_Path 
  187.       (Selection : not null access Gtk_Tree_Selection_Record; 
  188.        Path      : Gtk.Tree_Model.Gtk_Tree_Path); 
  189.    --  Select the row at Path. 
  190.    --  "path": The Gtk.Tree_Model.Gtk_Tree_Path to be selected. 
  191.  
  192.    procedure Select_Range 
  193.       (Selection  : not null access Gtk_Tree_Selection_Record; 
  194.        Start_Path : Gtk.Tree_Model.Gtk_Tree_Path; 
  195.        End_Path   : Gtk.Tree_Model.Gtk_Tree_Path); 
  196.    --  Selects a range of nodes, determined by Start_Path and End_Path 
  197.    --  inclusive. Selection must be set to GTK_SELECTION_MULTIPLE mode. 
  198.    --  "start_path": The initial node of the range. 
  199.    --  "end_path": The final node of the range. 
  200.  
  201.    procedure Selected_Foreach 
  202.       (Selection : not null access Gtk_Tree_Selection_Record; 
  203.        Func      : Gtk_Tree_Selection_Foreach_Func); 
  204.    --  Calls a function for each selected node. Note that you cannot modify 
  205.    --  the tree or selection from within this function. As a result, 
  206.    --  gtk_tree_selection_get_selected_rows might be more useful. 
  207.    --  "func": The function to call for each selected node. 
  208.  
  209.    generic 
  210.       type User_Data_Type (<>) is private; 
  211.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  212.    package Selected_Foreach_User_Data is 
  213.  
  214.       type Gtk_Tree_Selection_Foreach_Func is access procedure 
  215.         (Model : Gtk.Tree_Model.Gtk_Tree_Model; 
  216.          Path  : Gtk.Tree_Model.Gtk_Tree_Path; 
  217.          Iter  : Gtk.Tree_Model.Gtk_Tree_Iter; 
  218.          Data  : User_Data_Type); 
  219.       --  A function used by Gtk.Tree_Selection.Selected_Foreach to map all 
  220.       --  selected rows. It will be called on every selected row in the view. 
  221.       --  "model": The Gtk.Tree_Model.Gtk_Tree_Model being viewed 
  222.       --  "path": The Gtk.Tree_Model.Gtk_Tree_Path of a selected row 
  223.       --  "iter": A Gtk.Tree_Model.Gtk_Tree_Iter pointing to a selected row 
  224.       --  "data": user data 
  225.  
  226.       procedure Selected_Foreach 
  227.          (Selection : not null access Gtk.Tree_Selection.Gtk_Tree_Selection_Record'Class; 
  228.           Func      : Gtk_Tree_Selection_Foreach_Func; 
  229.           Data      : User_Data_Type); 
  230.       --  Calls a function for each selected node. Note that you cannot modify 
  231.       --  the tree or selection from within this function. As a result, 
  232.       --  gtk_tree_selection_get_selected_rows might be more useful. 
  233.       --  "func": The function to call for each selected node. 
  234.       --  "data": user data to pass to the function. 
  235.  
  236.    end Selected_Foreach_User_Data; 
  237.  
  238.    generic 
  239.       type User_Data_Type (<>) is private; 
  240.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  241.    package Set_Select_Function_User_Data is 
  242.  
  243.       type Gtk_Tree_Selection_Func is access function 
  244.         (Selection               : not null access Gtk.Tree_Selection.Gtk_Tree_Selection_Record'Class; 
  245.          Model                   : Gtk.Tree_Model.Gtk_Tree_Model; 
  246.          Path                    : Gtk.Tree_Model.Gtk_Tree_Path; 
  247.          Path_Currently_Selected : Boolean; 
  248.          Data                    : User_Data_Type) return Boolean; 
  249.       --  A function used by Gtk.Tree_Selection.Set_Select_Function to filter 
  250.       --  whether or not a row may be selected. It is called whenever a row's 
  251.       --  state might change. A return value of True indicates to Selection that 
  252.       --  it is okay to change the selection. 
  253.       --  "selection": A Gtk.Tree_Selection.Gtk_Tree_Selection 
  254.       --  "model": A Gtk.Tree_Model.Gtk_Tree_Model being viewed 
  255.       --  "path": The Gtk.Tree_Model.Gtk_Tree_Path of the row in question 
  256.       --  "path_currently_selected": True, if the path is currently selected 
  257.       --  "data": user data 
  258.  
  259.       procedure Set_Select_Function 
  260.          (Selection : not null access Gtk.Tree_Selection.Gtk_Tree_Selection_Record'Class; 
  261.           Func      : Gtk_Tree_Selection_Func; 
  262.           Data      : User_Data_Type); 
  263.       --  Sets the selection function. 
  264.       --  If set, this function is called before any node is selected or 
  265.       --  unselected, giving some control over which nodes are selected. The 
  266.       --  select function should return True if the state of the node may be 
  267.       --  toggled, and False if the state of the node should be left unchanged. 
  268.       --  "func": The selection function. May be null 
  269.       --  "data": The selection function's data. May be null 
  270.  
  271.    end Set_Select_Function_User_Data; 
  272.  
  273.    procedure Unselect_All 
  274.       (Selection : not null access Gtk_Tree_Selection_Record); 
  275.    --  Unselects all the nodes. 
  276.  
  277.    procedure Unselect_Iter 
  278.       (Selection : not null access Gtk_Tree_Selection_Record; 
  279.        Iter      : Gtk.Tree_Model.Gtk_Tree_Iter); 
  280.    --  Unselects the specified iterator. 
  281.    --  "iter": The Gtk.Tree_Model.Gtk_Tree_Iter to be unselected. 
  282.  
  283.    procedure Unselect_Path 
  284.       (Selection : not null access Gtk_Tree_Selection_Record; 
  285.        Path      : Gtk.Tree_Model.Gtk_Tree_Path); 
  286.    --  Unselects the row at Path. 
  287.    --  "path": The Gtk.Tree_Model.Gtk_Tree_Path to be unselected. 
  288.  
  289.    procedure Unselect_Range 
  290.       (Selection  : not null access Gtk_Tree_Selection_Record; 
  291.        Start_Path : Gtk.Tree_Model.Gtk_Tree_Path; 
  292.        End_Path   : Gtk.Tree_Model.Gtk_Tree_Path); 
  293.    --  Unselects a range of nodes, determined by Start_Path and End_Path 
  294.    --  inclusive. 
  295.    --  Since: gtk+ 2.2 
  296.    --  "start_path": The initial node of the range. 
  297.    --  "end_path": The initial node of the range. 
  298.  
  299.    ---------------------- 
  300.    -- GtkAda additions -- 
  301.    ---------------------- 
  302.  
  303.    procedure Get_Selected_Rows 
  304.      (Selection : access Gtk_Tree_Selection_Record; 
  305.       Model     : out Gtk.Tree_Model.Gtk_Tree_Model; 
  306.       Path_List : out Gtk.Tree_Model.Gtk_Tree_Path_List.Glist); 
  307.    --  Creates a list of path of all selected rows. Additionally, if you are 
  308.    --  planning on modifying the model after calling this function, you may 
  309.    --  want to convert the returned list into a list of Gtk_Tree_Row_Reference. 
  310.    -- 
  311.    --  You must free the resulting list by calling Path_Free on each item, and 
  312.    --  then freeing the list itself. 
  313.  
  314.    ---------------- 
  315.    -- Properties -- 
  316.    ---------------- 
  317.    --  The following properties are defined for this widget. See 
  318.    --  Glib.Properties for more information on properties) 
  319.  
  320.    Mode_Property : constant Gtk.Enums.Property_Gtk_Selection_Mode; 
  321.    --  Selection mode. See Gtk.Tree_Selection.Set_Mode for more information on 
  322.    --  this property. 
  323.  
  324.    ------------- 
  325.    -- Signals -- 
  326.    ------------- 
  327.  
  328.    type Cb_Gtk_Tree_Selection_Void is not null access procedure 
  329.      (Self : access Gtk_Tree_Selection_Record'Class); 
  330.  
  331.    type Cb_GObject_Void is not null access procedure 
  332.      (Self : access Glib.Object.GObject_Record'Class); 
  333.  
  334.    Signal_Changed : constant Glib.Signal_Name := "changed"; 
  335.    procedure On_Changed 
  336.       (Self  : not null access Gtk_Tree_Selection_Record; 
  337.        Call  : Cb_Gtk_Tree_Selection_Void; 
  338.        After : Boolean := False); 
  339.    procedure On_Changed 
  340.       (Self  : not null access Gtk_Tree_Selection_Record; 
  341.        Call  : Cb_GObject_Void; 
  342.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  343.        After : Boolean := False); 
  344.    --  Emitted whenever the selection has (possibly) changed. Please note that 
  345.    --  this signal is mostly a hint. It may only be emitted once when a range 
  346.    --  of rows are selected, and it may occasionally be emitted when nothing 
  347.    --  has happened. 
  348.  
  349. private 
  350.    Mode_Property : constant Gtk.Enums.Property_Gtk_Selection_Mode := 
  351.      Gtk.Enums.Build ("mode"); 
  352. end Gtk.Tree_Selection;