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 GtkFileFilter can be used to restrict the files being shown in a 
  26. --  Gtk.File_Chooser.Gtk_File_Chooser. Files can be filtered based on their 
  27. --  name (with Gtk.File_Filter.Add_Pattern), on their mime type (with 
  28. --  Gtk.File_Filter.Add_Mime_Type), or by a custom filter function (with 
  29. --  Gtk.File_Filter.Add_Custom). 
  30. -- 
  31. --  Filtering by mime types handles aliasing and subclassing of mime types; 
  32. --  e.g. a filter for text/plain also matches a file with mime type 
  33. --  application/rtf, since application/rtf is a subclass of text/plain. Note 
  34. --  that Gtk.File_Filter.Gtk_File_Filter allows wildcards for the subtype of a 
  35. --  mime type, so you can e.g. filter for image/*. 
  36. -- 
  37. --  Normally, filters are used by adding them to a 
  38. --  Gtk.File_Chooser.Gtk_File_Chooser, see Gtk.File_Chooser.Add_Filter, but it 
  39. --  is also possible to manually use a filter on a file with 
  40. --  Gtk.File_Filter.Filter. 
  41. -- 
  42. --  == GtkFileFilter as GtkBuildable == 
  43. -- 
  44. --  The GtkFileFilter implementation of the GtkBuildable interface supports 
  45. --  adding rules using the <mime-types>, <patterns> and <applications> elements 
  46. --  and listing the rules within. Specifying a <mime-type> or <pattern> is the 
  47. --  same as calling Gtk.Recent_Filter.Add_Mime_Type or 
  48. --  Gtk.Recent_Filter.Add_Pattern 
  49. -- 
  50. --  == A UI definition fragment specifying GtkFileFilter rules == 
  51. -- 
  52. --    <object class="GtkFileFilter"> 
  53. --    <mime-types> 
  54. --    <mime-type>text/plain</mime-type> 
  55. --    <mime-type>image/*</mime-type> 
  56. --    </mime-types> 
  57. --    <patterns> 
  58. --    <pattern>*.txt</pattern> 
  59. --    <pattern>*.png</pattern> 
  60. --    </patterns> 
  61. --    </object> 
  62. --  </description> 
  63. pragma Ada_2005; 
  64.  
  65. pragma Warnings (Off, "*is already use-visible*"); 
  66. with Glib;                    use Glib; 
  67. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  68. with Glib.Object;             use Glib.Object; 
  69. with Glib.Types;              use Glib.Types; 
  70. with Gtk.Buildable;           use Gtk.Buildable; 
  71. with Interfaces.C.Strings;    use Interfaces.C.Strings; 
  72.  
  73. package Gtk.File_Filter is 
  74.  
  75.    type Gtk_File_Filter_Record is new GObject_Record with null record; 
  76.    type Gtk_File_Filter is access all Gtk_File_Filter_Record'Class; 
  77.  
  78.    type Gtk_File_Filter_Flags is mod 2 ** Integer'Size; 
  79.    pragma Convention (C, Gtk_File_Filter_Flags); 
  80.    --  These flags indicate what parts of a 
  81.    --  Gtk.File_Filter.Gtk_File_Filter_Info struct are filled or need to be 
  82.    --  filled. 
  83.  
  84.    File_Filter_Filename : constant Gtk_File_Filter_Flags := 1; 
  85.    File_Filter_Uri : constant Gtk_File_Filter_Flags := 2; 
  86.    File_Filter_Display_Name : constant Gtk_File_Filter_Flags := 4; 
  87.    File_Filter_Mime_Type : constant Gtk_File_Filter_Flags := 8; 
  88.  
  89.    type Gtk_File_Filter_Info is record 
  90.       Contains : Gtk_File_Filter_Flags; 
  91.       Filename : Interfaces.C.Strings.chars_ptr; 
  92.       URI : Interfaces.C.Strings.chars_ptr; 
  93.       Display_Name : Interfaces.C.Strings.chars_ptr; 
  94.       Mime_Type : Interfaces.C.Strings.chars_ptr; 
  95.    end record; 
  96.    pragma Convention (C, Gtk_File_Filter_Info); 
  97.  
  98.    function From_Object_Free (B : access Gtk_File_Filter_Info) return Gtk_File_Filter_Info; 
  99.    pragma Inline (From_Object_Free); 
  100.    --  A Gtk.File_Filter.Gtk_File_Filter_Info struct is used to pass 
  101.    --  information about the tested file to Gtk.File_Filter.Filter. 
  102.  
  103.    --------------- 
  104.    -- Callbacks -- 
  105.    --------------- 
  106.  
  107.    type Gtk_File_Filter_Func is access function (Filter_Info : Gtk_File_Filter_Info) return Boolean; 
  108.    --  The type of function that is used with custom filters, see 
  109.    --  Gtk.File_Filter.Add_Custom. 
  110.    --  "filter_info": a Gtk.File_Filter.Gtk_File_Filter_Info that is filled 
  111.    --  according to the Needed flags passed to Gtk.File_Filter.Add_Custom 
  112.  
  113.    ---------------------------- 
  114.    -- Enumeration Properties -- 
  115.    ---------------------------- 
  116.  
  117.    package Gtk_File_Filter_Flags_Properties is 
  118.       new Generic_Internal_Discrete_Property (Gtk_File_Filter_Flags); 
  119.    type Property_Gtk_File_Filter_Flags is new Gtk_File_Filter_Flags_Properties.Property; 
  120.  
  121.    ------------------ 
  122.    -- Constructors -- 
  123.    ------------------ 
  124.  
  125.    procedure Gtk_New (Self : out Gtk_File_Filter); 
  126.    procedure Initialize 
  127.       (Self : not null access Gtk_File_Filter_Record'Class); 
  128.    --  Creates a new Gtk.File_Filter.Gtk_File_Filter with no rules added to 
  129.    --  it. Such a filter doesn't accept any files, so is not particularly 
  130.    --  useful until you add rules with Gtk.File_Filter.Add_Mime_Type, 
  131.    --  Gtk.File_Filter.Add_Pattern, or Gtk.File_Filter.Add_Custom. To create a 
  132.    --  filter that accepts any file, use: |[ GtkFileFilter *filter = 
  133.    --  gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ]| 
  134.    --  Since: gtk+ 2.4 
  135.  
  136.    function Gtk_File_Filter_New return Gtk_File_Filter; 
  137.    --  Creates a new Gtk.File_Filter.Gtk_File_Filter with no rules added to 
  138.    --  it. Such a filter doesn't accept any files, so is not particularly 
  139.    --  useful until you add rules with Gtk.File_Filter.Add_Mime_Type, 
  140.    --  Gtk.File_Filter.Add_Pattern, or Gtk.File_Filter.Add_Custom. To create a 
  141.    --  filter that accepts any file, use: |[ GtkFileFilter *filter = 
  142.    --  gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ]| 
  143.    --  Since: gtk+ 2.4 
  144.  
  145.    function Get_Type return Glib.GType; 
  146.    pragma Import (C, Get_Type, "gtk_file_filter_get_type"); 
  147.  
  148.    ------------- 
  149.    -- Methods -- 
  150.    ------------- 
  151.  
  152.    procedure Add_Custom 
  153.       (Self   : not null access Gtk_File_Filter_Record; 
  154.        Needed : Gtk_File_Filter_Flags; 
  155.        Func   : Gtk_File_Filter_Func; 
  156.        Notify : Glib.G_Destroy_Notify_Address); 
  157.    --  Adds rule to a filter that allows files based on a custom callback 
  158.    --  function. The bitfield Needed which is passed in provides information 
  159.    --  about what sorts of information that the filter function needs; this 
  160.    --  allows GTK+ to avoid retrieving expensive information when it isn't 
  161.    --  needed by the filter. 
  162.    --  Since: gtk+ 2.4 
  163.    --  "needed": bitfield of flags indicating the information that the custom 
  164.    --  filter function needs. 
  165.    --  "func": callback function; if the function returns True, then the file 
  166.    --  will be displayed. 
  167.    --  "notify": function to call to free Data when it is no longer needed. 
  168.  
  169.    generic 
  170.       type User_Data_Type (<>) is private; 
  171.       with procedure Destroy (Data : in out User_Data_Type) is null; 
  172.    package Add_Custom_User_Data is 
  173.  
  174.       type Gtk_File_Filter_Func is access function 
  175.         (Filter_Info : Gtk.File_Filter.Gtk_File_Filter_Info; 
  176.          Data        : User_Data_Type) return Boolean; 
  177.       --  The type of function that is used with custom filters, see 
  178.       --  Gtk.File_Filter.Add_Custom. 
  179.       --  "filter_info": a Gtk.File_Filter.Gtk_File_Filter_Info that is filled 
  180.       --  according to the Needed flags passed to Gtk.File_Filter.Add_Custom 
  181.       --  "data": user data passed to Gtk.File_Filter.Add_Custom 
  182.  
  183.       procedure Add_Custom 
  184.          (Self   : not null access Gtk.File_Filter.Gtk_File_Filter_Record'Class; 
  185.           Needed : Gtk.File_Filter.Gtk_File_Filter_Flags; 
  186.           Func   : Gtk_File_Filter_Func; 
  187.           Data   : User_Data_Type; 
  188.           Notify : Glib.G_Destroy_Notify_Address); 
  189.       --  Adds rule to a filter that allows files based on a custom callback 
  190.       --  function. The bitfield Needed which is passed in provides information 
  191.       --  about what sorts of information that the filter function needs; this 
  192.       --  allows GTK+ to avoid retrieving expensive information when it isn't 
  193.       --  needed by the filter. 
  194.       --  Since: gtk+ 2.4 
  195.       --  "needed": bitfield of flags indicating the information that the 
  196.       --  custom filter function needs. 
  197.       --  "func": callback function; if the function returns True, then the 
  198.       --  file will be displayed. 
  199.       --  "data": data to pass to Func 
  200.       --  "notify": function to call to free Data when it is no longer needed. 
  201.  
  202.    end Add_Custom_User_Data; 
  203.  
  204.    procedure Add_Mime_Type 
  205.       (Self      : not null access Gtk_File_Filter_Record; 
  206.        Mime_Type : UTF8_String); 
  207.    --  Adds a rule allowing a given mime type to Filter. 
  208.    --  Since: gtk+ 2.4 
  209.    --  "mime_type": name of a MIME type 
  210.  
  211.    procedure Add_Pattern 
  212.       (Self    : not null access Gtk_File_Filter_Record; 
  213.        Pattern : UTF8_String); 
  214.    --  Adds a rule allowing a shell style glob to a filter. 
  215.    --  Since: gtk+ 2.4 
  216.    --  "pattern": a shell style glob 
  217.  
  218.    procedure Add_Pixbuf_Formats 
  219.       (Self : not null access Gtk_File_Filter_Record); 
  220.    --  Adds a rule allowing image files in the formats supported by GdkPixbuf. 
  221.    --  Since: gtk+ 2.6 
  222.  
  223.    function Filter 
  224.       (Self        : not null access Gtk_File_Filter_Record; 
  225.        Filter_Info : Gtk_File_Filter_Info) return Boolean; 
  226.    --  Tests whether a file should be displayed according to Filter. The 
  227.    --  Gtk.File_Filter.Gtk_File_Filter_Info structure Filter_Info should 
  228.    --  include the fields returned from Gtk.File_Filter.Get_Needed. 
  229.    --  This function will not typically be used by applications; it is 
  230.    --  intended principally for use in the implementation of 
  231.    --  Gtk.File_Chooser.Gtk_File_Chooser. 
  232.    --  Since: gtk+ 2.4 
  233.    --  "filter_info": a Gtk.File_Filter.Gtk_File_Filter_Info structure 
  234.    --  containing information about a file. 
  235.  
  236.    function Get_Name 
  237.       (Self : not null access Gtk_File_Filter_Record) return UTF8_String; 
  238.    --  Gets the human-readable name for the filter. See 
  239.    --  Gtk.File_Filter.Set_Name. 
  240.    --  Since: gtk+ 2.4 
  241.  
  242.    procedure Set_Name 
  243.       (Self : not null access Gtk_File_Filter_Record; 
  244.        Name : UTF8_String := ""); 
  245.    --  Sets the human-readable name of the filter; this is the string that 
  246.    --  will be displayed in the file selector user interface if there is a 
  247.    --  selectable list of filters. 
  248.    --  Since: gtk+ 2.4 
  249.    --  "name": the human-readable-name for the filter, or null to remove any 
  250.    --  existing name. 
  251.  
  252.    function Get_Needed 
  253.       (Self : not null access Gtk_File_Filter_Record) 
  254.        return Gtk_File_Filter_Flags; 
  255.    --  Gets the fields that need to be filled in for the structure passed to 
  256.    --  Gtk.File_Filter.Filter 
  257.    --  This function will not typically be used by applications; it is 
  258.    --  intended principally for use in the implementation of 
  259.    --  Gtk.File_Chooser.Gtk_File_Chooser. 
  260.    --  Since: gtk+ 2.4 
  261.  
  262.    ---------------- 
  263.    -- Interfaces -- 
  264.    ---------------- 
  265.    --  This class implements several interfaces. See Glib.Types 
  266.    -- 
  267.    --  - "Buildable" 
  268.  
  269.    package Implements_Gtk_Buildable is new Glib.Types.Implements 
  270.      (Gtk.Buildable.Gtk_Buildable, Gtk_File_Filter_Record, Gtk_File_Filter); 
  271.    function "+" 
  272.      (Widget : access Gtk_File_Filter_Record'Class) 
  273.    return Gtk.Buildable.Gtk_Buildable 
  274.    renames Implements_Gtk_Buildable.To_Interface; 
  275.    function "-" 
  276.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  277.    return Gtk_File_Filter 
  278.    renames Implements_Gtk_Buildable.To_Object; 
  279.  
  280. end Gtk.File_Filter;