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. --  A Gtk.Recent_Filter.Gtk_Recent_Filter can be used to restrict the files 
  26. --  being shown in a Gtk.Recent_Chooser.Gtk_Recent_Chooser. Files can be 
  27. --  filtered based on their name (with Gtk.Recent_Filter.Add_Pattern), on their 
  28. --  mime type (with Gtk.File_Filter.Add_Mime_Type), on the application that has 
  29. --  registered them (with Gtk.Recent_Filter.Add_Application), or by a custom 
  30. --  filter function (with Gtk.Recent_Filter.Add_Custom). 
  31. -- 
  32. --  Filtering by mime type handles aliasing and subclassing of mime types; 
  33. --  e.g. a filter for text/plain also matches a file with mime type 
  34. --  application/rtf, since application/rtf is a subclass of text/plain. Note 
  35. --  that Gtk.Recent_Filter.Gtk_Recent_Filter allows wildcards for the subtype 
  36. --  of a mime type, so you can e.g. filter for image/<!-- -->*. 
  37. -- 
  38. --  Normally, filters are used by adding them to a 
  39. --  Gtk.Recent_Chooser.Gtk_Recent_Chooser, see Gtk.Recent_Chooser.Add_Filter, 
  40. --  but it is also possible to manually use a filter on a file with 
  41. --  Gtk.Recent_Filter.Filter. 
  42. -- 
  43. --  Recently used files are supported since GTK+ 2.10. 
  44. -- 
  45. --  == GtkRecentFilter as GtkBuildable == 
  46. -- 
  47. --  The GtkRecentFilter implementation of the GtkBuildable interface supports 
  48. --  adding rules using the <mime-types>, <patterns> and <applications> elements 
  49. --  and listing the rules within. Specifying a <mime-type>, <pattern> or 
  50. --  <application> is the same as calling Gtk.Recent_Filter.Add_Mime_Type, 
  51. --  Gtk.Recent_Filter.Add_Pattern or Gtk.Recent_Filter.Add_Application. 
  52. -- 
  53. --  == A UI definition fragment specifying GtkRecentFilter rules == 
  54. -- 
  55. --    <object class="GtkRecentFilter"> 
  56. --    <mime-types> 
  57. --    <mime-type>text/plain</mime-type> 
  58. --    <mime-type>image/png</mime-type> 
  59. --    </mime-types> 
  60. --    <patterns> 
  61. --    <pattern>*.txt</pattern> 
  62. --    <pattern>*.png</pattern> 
  63. --    </patterns> 
  64. --    <applications> 
  65. --    <application>gimp</application> 
  66. --    <application>gedit</application> 
  67. --    <application>glade</application> 
  68. --    </applications> 
  69. --    </object> 
  70. --  </description> 
  71. pragma Ada_2005; 
  72.  
  73. pragma Warnings (Off, "*is already use-visible*"); 
  74. with Glib;                    use Glib; 
  75. with Glib.GSlist;             use Glib.GSlist; 
  76. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  77. with Glib.Object;             use Glib.Object; 
  78. with Glib.Types;              use Glib.Types; 
  79. with Gtk.Buildable;           use Gtk.Buildable; 
  80. with Interfaces.C.Strings;    use Interfaces.C.Strings; 
  81.  
  82. package Gtk.Recent_Filter is 
  83.  
  84.    type Gtk_Recent_Filter_Record is new GObject_Record with null record; 
  85.    type Gtk_Recent_Filter is access all Gtk_Recent_Filter_Record'Class; 
  86.  
  87.    type Gtk_Recent_Filter_Flags is mod 2 ** Integer'Size; 
  88.    pragma Convention (C, Gtk_Recent_Filter_Flags); 
  89.    --  These flags indicate what parts of a 
  90.    --  Gtk.Recent_Filter.Gtk_Recent_Filter_Info struct are filled or need to be 
  91.    --  filled. 
  92.  
  93.    Recent_Filter_Uri : constant Gtk_Recent_Filter_Flags := 1; 
  94.    Recent_Filter_Display_Name : constant Gtk_Recent_Filter_Flags := 2; 
  95.    Recent_Filter_Mime_Type : constant Gtk_Recent_Filter_Flags := 4; 
  96.    Recent_Filter_Application : constant Gtk_Recent_Filter_Flags := 8; 
  97.    Recent_Filter_Group : constant Gtk_Recent_Filter_Flags := 16; 
  98.    Recent_Filter_Age : constant Gtk_Recent_Filter_Flags := 32; 
  99.  
  100.    type Gtk_Recent_Filter_Info is record 
  101.       Contains : Gtk_Recent_Filter_Flags; 
  102.       URI : Interfaces.C.Strings.chars_ptr; 
  103.       Display_Name : Interfaces.C.Strings.chars_ptr; 
  104.       Mime_Type : Interfaces.C.Strings.chars_ptr; 
  105.       Applications : Interfaces.C.Strings.char_array_access; 
  106.       Groups : Interfaces.C.Strings.char_array_access; 
  107.       Age : Gint; 
  108.    end record; 
  109.    pragma Convention (C, Gtk_Recent_Filter_Info); 
  110.  
  111.    function From_Object_Free (B : access Gtk_Recent_Filter_Info) return Gtk_Recent_Filter_Info; 
  112.    pragma Inline (From_Object_Free); 
  113.    --  A GtkRecentFilterInfo struct is used to pass information about the 
  114.    --  tested file to Gtk.Recent_Filter.Filter. 
  115.  
  116.    function Convert (R : Gtk.Recent_Filter.Gtk_Recent_Filter) return System.Address; 
  117.    function Convert (R : System.Address) return Gtk.Recent_Filter.Gtk_Recent_Filter; 
  118.    package Gtk_Recent_Filter_List is new Generic_SList (Gtk.Recent_Filter.Gtk_Recent_Filter); 
  119.  
  120.    --------------- 
  121.    -- Callbacks -- 
  122.    --------------- 
  123.  
  124.    type Gtk_Recent_Filter_Func is access function (Filter_Info : Gtk_Recent_Filter_Info) return Boolean; 
  125.    --  The type of function that is used with custom filters, see 
  126.    --  Gtk.Recent_Filter.Add_Custom. 
  127.    --  "filter_info": a Gtk.Recent_Filter.Gtk_Recent_Filter_Info that is 
  128.    --  filled according to the Needed flags passed to 
  129.    --  Gtk.Recent_Filter.Add_Custom 
  130.  
  131.    ---------------------------- 
  132.    -- Enumeration Properties -- 
  133.    ---------------------------- 
  134.  
  135.    package Gtk_Recent_Filter_Flags_Properties is 
  136.       new Generic_Internal_Discrete_Property (Gtk_Recent_Filter_Flags); 
  137.    type Property_Gtk_Recent_Filter_Flags is new Gtk_Recent_Filter_Flags_Properties.Property; 
  138.  
  139.    ------------------ 
  140.    -- Constructors -- 
  141.    ------------------ 
  142.  
  143.    procedure Gtk_New (Filter : out Gtk_Recent_Filter); 
  144.    procedure Initialize 
  145.       (Filter : not null access Gtk_Recent_Filter_Record'Class); 
  146.    --  Creates a new Gtk.Recent_Filter.Gtk_Recent_Filter with no rules added 
  147.    --  to it. Such filter does not accept any recently used resources, so is 
  148.    --  not particularly useful until you add rules with 
  149.    --  Gtk.Recent_Filter.Add_Pattern, Gtk.Recent_Filter.Add_Mime_Type, 
  150.    --  Gtk.Recent_Filter.Add_Application, Gtk.Recent_Filter.Add_Age. To create 
  151.    --  a filter that accepts any recently used resource, use: |[ 
  152.    --  GtkRecentFilter *filter = gtk_recent_filter_new (); 
  153.    --  gtk_recent_filter_add_pattern (filter, "*"); ]| 
  154.    --  Since: gtk+ 2.10 
  155.  
  156.    function Gtk_Recent_Filter_New return Gtk_Recent_Filter; 
  157.    --  Creates a new Gtk.Recent_Filter.Gtk_Recent_Filter with no rules added 
  158.    --  to it. Such filter does not accept any recently used resources, so is 
  159.    --  not particularly useful until you add rules with 
  160.    --  Gtk.Recent_Filter.Add_Pattern, Gtk.Recent_Filter.Add_Mime_Type, 
  161.    --  Gtk.Recent_Filter.Add_Application, Gtk.Recent_Filter.Add_Age. To create 
  162.    --  a filter that accepts any recently used resource, use: |[ 
  163.    --  GtkRecentFilter *filter = gtk_recent_filter_new (); 
  164.    --  gtk_recent_filter_add_pattern (filter, "*"); ]| 
  165.    --  Since: gtk+ 2.10 
  166.  
  167.    function Get_Type return Glib.GType; 
  168.    pragma Import (C, Get_Type, "gtk_recent_filter_get_type"); 
  169.  
  170.    ------------- 
  171.    -- Methods -- 
  172.    ------------- 
  173.  
  174.    procedure Add_Age 
  175.       (Filter : not null access Gtk_Recent_Filter_Record; 
  176.        Days   : Gint); 
  177.    --  Adds a rule that allows resources based on their age - that is, the 
  178.    --  number of days elapsed since they were last modified. 
  179.    --  Since: gtk+ 2.10 
  180.    --  "days": number of days 
  181.  
  182.    procedure Add_Application 
  183.       (Filter      : not null access Gtk_Recent_Filter_Record; 
  184.        Application : UTF8_String); 
  185.    --  Adds a rule that allows resources based on the name of the application 
  186.    --  that has registered them. 
  187.    --  Since: gtk+ 2.10 
  188.    --  "application": an application name 
  189.  
  190.    procedure Add_Custom 
  191.       (Filter       : not null access Gtk_Recent_Filter_Record; 
  192.        Needed       : Gtk_Recent_Filter_Flags; 
  193.        Func         : Gtk_Recent_Filter_Func; 
  194.        Data_Destroy : Glib.G_Destroy_Notify_Address); 
  195.    --  Adds a rule to a filter that allows resources based on a custom 
  196.    --  callback function. The bitfield Needed which is passed in provides 
  197.    --  information about what sorts of information that the filter function 
  198.    --  needs; this allows GTK+ to avoid retrieving expensive information when 
  199.    --  it isn't needed by the filter. 
  200.    --  Since: gtk+ 2.10 
  201.    --  "needed": bitfield of flags indicating the information that the custom 
  202.    --  filter function needs. 
  203.    --  "func": callback function; if the function returns True, then the file 
  204.    --  will be displayed. 
  205.    --  "data_destroy": function to call to free Data when it is no longer 
  206.    --  needed. 
  207.  
  208.    generic 
  209.       type User_Data_Type (<>) is private; 
  210.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  211.    package Add_Custom_User_Data is 
  212.  
  213.       type Gtk_Recent_Filter_Func is access function 
  214.         (Filter_Info : Gtk.Recent_Filter.Gtk_Recent_Filter_Info; 
  215.          User_Data   : User_Data_Type) return Boolean; 
  216.       --  The type of function that is used with custom filters, see 
  217.       --  Gtk.Recent_Filter.Add_Custom. 
  218.       --  "filter_info": a Gtk.Recent_Filter.Gtk_Recent_Filter_Info that is 
  219.       --  filled according to the Needed flags passed to 
  220.       --  Gtk.Recent_Filter.Add_Custom 
  221.       --  "user_data": user data passed to Gtk.Recent_Filter.Add_Custom 
  222.  
  223.       procedure Add_Custom 
  224.          (Filter       : not null access Gtk.Recent_Filter.Gtk_Recent_Filter_Record'Class; 
  225.           Needed       : Gtk.Recent_Filter.Gtk_Recent_Filter_Flags; 
  226.           Func         : Gtk_Recent_Filter_Func; 
  227.           Data         : User_Data_Type; 
  228.           Data_Destroy : Glib.G_Destroy_Notify_Address); 
  229.       --  Adds a rule to a filter that allows resources based on a custom 
  230.       --  callback function. The bitfield Needed which is passed in provides 
  231.       --  information about what sorts of information that the filter function 
  232.       --  needs; this allows GTK+ to avoid retrieving expensive information 
  233.       --  when it isn't needed by the filter. 
  234.       --  Since: gtk+ 2.10 
  235.       --  "needed": bitfield of flags indicating the information that the 
  236.       --  custom filter function needs. 
  237.       --  "func": callback function; if the function returns True, then the 
  238.       --  file will be displayed. 
  239.       --  "data": data to pass to Func 
  240.       --  "data_destroy": function to call to free Data when it is no longer 
  241.       --  needed. 
  242.  
  243.    end Add_Custom_User_Data; 
  244.  
  245.    procedure Add_Group 
  246.       (Filter : not null access Gtk_Recent_Filter_Record; 
  247.        Group  : UTF8_String); 
  248.    --  Adds a rule that allows resources based on the name of the group to 
  249.    --  which they belong 
  250.    --  Since: gtk+ 2.10 
  251.    --  "group": a group name 
  252.  
  253.    procedure Add_Mime_Type 
  254.       (Filter    : not null access Gtk_Recent_Filter_Record; 
  255.        Mime_Type : UTF8_String); 
  256.    --  Adds a rule that allows resources based on their registered MIME type. 
  257.    --  Since: gtk+ 2.10 
  258.    --  "mime_type": a MIME type 
  259.  
  260.    procedure Add_Pattern 
  261.       (Filter  : not null access Gtk_Recent_Filter_Record; 
  262.        Pattern : UTF8_String); 
  263.    --  Adds a rule that allows resources based on a pattern matching their 
  264.    --  display name. 
  265.    --  Since: gtk+ 2.10 
  266.    --  "pattern": a file pattern 
  267.  
  268.    procedure Add_Pixbuf_Formats 
  269.       (Filter : not null access Gtk_Recent_Filter_Record); 
  270.    --  Adds a rule allowing image files in the formats supported by GdkPixbuf. 
  271.    --  Since: gtk+ 2.10 
  272.  
  273.    function Filter 
  274.       (Filter      : not null access Gtk_Recent_Filter_Record; 
  275.        Filter_Info : Gtk_Recent_Filter_Info) return Boolean; 
  276.    --  Tests whether a file should be displayed according to Filter. The 
  277.    --  Gtk.Recent_Filter.Gtk_Recent_Filter_Info structure Filter_Info should 
  278.    --  include the fields returned from Gtk.Recent_Filter.Get_Needed. 
  279.    --  This function will not typically be used by applications; it is 
  280.    --  intended principally for use in the implementation of 
  281.    --  Gtk.Recent_Chooser.Gtk_Recent_Chooser. 
  282.    --  Since: gtk+ 2.10 
  283.    --  "filter_info": a Gtk.Recent_Filter.Gtk_Recent_Filter_Info structure 
  284.    --  containing information about a recently used resource 
  285.  
  286.    function Get_Name 
  287.       (Filter : not null access Gtk_Recent_Filter_Record) return UTF8_String; 
  288.    --  Gets the human-readable name for the filter. See 
  289.    --  Gtk.Recent_Filter.Set_Name. 
  290.    --  Since: gtk+ 2.10 
  291.  
  292.    procedure Set_Name 
  293.       (Filter : not null access Gtk_Recent_Filter_Record; 
  294.        Name   : UTF8_String); 
  295.    --  Sets the human-readable name of the filter; this is the string that 
  296.    --  will be displayed in the recently used resources selector user interface 
  297.    --  if there is a selectable list of filters. 
  298.    --  Since: gtk+ 2.10 
  299.    --  "name": then human readable name of Filter 
  300.  
  301.    function Get_Needed 
  302.       (Filter : not null access Gtk_Recent_Filter_Record) 
  303.        return Gtk_Recent_Filter_Flags; 
  304.    --  Gets the fields that need to be filled in for the structure passed to 
  305.    --  Gtk.Recent_Filter.Filter 
  306.    --  This function will not typically be used by applications; it is 
  307.    --  intended principally for use in the implementation of 
  308.    --  Gtk.Recent_Chooser.Gtk_Recent_Chooser. 
  309.    --  Since: gtk+ 2.10 
  310.  
  311.    ---------------- 
  312.    -- Interfaces -- 
  313.    ---------------- 
  314.    --  This class implements several interfaces. See Glib.Types 
  315.    -- 
  316.    --  - "Buildable" 
  317.  
  318.    package Implements_Gtk_Buildable is new Glib.Types.Implements 
  319.      (Gtk.Buildable.Gtk_Buildable, Gtk_Recent_Filter_Record, Gtk_Recent_Filter); 
  320.    function "+" 
  321.      (Widget : access Gtk_Recent_Filter_Record'Class) 
  322.    return Gtk.Buildable.Gtk_Buildable 
  323.    renames Implements_Gtk_Buildable.To_Interface; 
  324.    function "-" 
  325.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  326.    return Gtk_Recent_Filter 
  327.    renames Implements_Gtk_Buildable.To_Object; 
  328.  
  329. end Gtk.Recent_Filter;