/src/wrappers/gtk/library/gtk_file_filter.e

  1indexing
  2	description: "GtkFileFilter - used to restrict the files shown in a GtkFileChoose."
  3	copyright: "[
  4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20				]"
 21	date: "$Date:$"
 22	revision: "$Revision:$"
 23
 24class GTK_FILE_FILTER
 25	-- A GtkFileFilter can be used to restrict the files being shown in
 26	-- a GtkFileChooser. Files can be filtered based on their name
 27	-- (with `add_pattern'), on their mime type (with `add_mime_type'),
 28	-- or by a custom filter function (with TODO: `add_custom').
 29
 30	-- Filtering by mime types handles aliasing and subclassing of mime
 31	-- types; e.g. a filter for text/plain also matches a file with
 32	-- mime type application/rtf, since application/rtf is a subclass
 33	-- of text/plain. Note that GtkFileFilter allows wildcards for the
 34	-- subtype of a mime type, so you can e.g. filter for image/*.
 35
 36	-- Normally, filters are used by adding them to a GtkFileChooser,
 37	-- see GTK_FILE_CHOOSER's `add_filter', but it is also possible to
 38	-- manually use a filter on a file with (TODO) `filter'.
 39
 40inherit
 41	GTK_OBJECT
 42
 43insert
 44	GTK_FILE_FILTER_EXTERNALS
 45	GTK_FILE_FILTER_INFO_EXTERNALS
 46	GTK_FILE_FILTER_FLAGS
 47
 48creation make, with_pattern, with_mime_type, from_external_pointer
 49
 50feature {} -- Creation
 51	make is
 52			-- Creates a new GtkFileFilter with no rules added to
 53			-- it. Such a filter doesn't accept any files, so is not
 54			-- particularly useful until you add rules with
 55			-- `add_mime_type', `add_pattern', or `add_custom'. To create
 56			-- a filter that accepts any file, use:
 57			-- create a_filter.make; a_filter.add_pattern ("*")
 58		
 59			-- See also `with_pattern', `with_mime_type'
 60		do
 61			from_external_pointer (gtk_file_filter_new)
 62		end
 63
 64	with_pattern  (a_pattern: STRING) is
 65			-- Creates a new GtkFileFilter with `a_pattern' rule.
 66		require pattern_not_void: a_pattern /= Void
 67		do
 68			make; add_pattern (a_pattern)
 69		end
 70
 71	with_mime_type(a_mime_type: STRING) is
 72			-- Creates a new GtkFileFilter with `a_mime_type' rule
 73		require valid_mime_type: a_mime_type /= Void
 74		do
 75			make; add_mime_type(a_mime_type)
 76		end
 77	
 78feature -- Filter name
 79	set_name (a_name: STRING) is
 80			-- Sets the human-readable name of the filter; this is the
 81			-- string that will be displayed in the file selector user
 82			-- interface if there is a selectable list of filters.
 83		require a_name /= Void
 84		do
 85			gtk_file_filter_set_name (handle, a_name.to_external)
 86		end
 87
 88	unset_name is
 89			-- Remove any human-readable name of the filter, the string
 90			-- that will be displayed in the file selector user interface
 91			-- if there is a selectable list of filters.
 92		do
 93			gtk_file_filter_set_name (handle, default_pointer)
 94		end
 95
 96	name: STRING is
 97			-- The human-readable name for the filter. See `set_name'.
 98		local cstr: POINTER
 99		do
100			cstr := gtk_file_filter_get_name (handle)
101			-- Returns : The human-readable name of the filter, or
102			-- NULL. This value is owned by GTK+ and must not be modified
103			-- or freed.
104			if cstr.is_not_null
105			then create Result.from_external_copy (cstr)
106			end
107		end
108			
109
110feature -- Mime type filter
111	add_mime_type (a_mime_type: STRING) is
112			-- Adds a rule allowing the given `a_mime_type' to filter.
113		require valid_mime_type: a_mime_type /= Void
114		do
115			gtk_file_filter_add_mime_type   (handle, a_mime_type.to_external)
116		end
117
118feature -- Pattern filter
119	add_pattern (a_pattern: STRING) is
120			-- Adds a rule allowing a shell style glob to a filter.
121		require pattern_not_void: a_pattern /= Void
122		do
123			gtk_file_filter_add_pattern     (handle, a_pattern.to_external)
124		end
125
126feature -- Image filter
127	add_pixbuf_formats is
128			-- Adds a rule allowing image files in the formats supported by GdkPixbuf.
129		do
130			gtk_file_filter_add_pixbuf_formats (handle)
131		end
132	
133
134	-- TODO: gtk_file_filter_add_custom ()
135
136-- void        gtk_file_filter_add_custom      (GtkFileFilter *filter,
137-- 															GtkFileFilterFlags needed,
138-- 															GtkFileFilterFunc func,
139-- 															gpointer data,
140-- 															GDestroyNotify notify);
141
142-- Adds rule to a filter that allows files based on a custom callback function. The bitfield needed which is passed in provides information about what sorts of information that the filter function needs; this allows GTK+ to avoid retrieving expensive information when it isn't needed by the filter.
143
144-- filter : 	a GtkFileFilter
145-- needed : 	bitfield of flags indicating the information that the custom filter function needs.
146-- func : 	callback function; if the function returns TRUE, then the file will be displayed.
147-- data : 	data to pass to func
148-- notify : 	function to call to free data when it is no longer needed.
149
150-- Since 2.4
151
152	-- TODO gtk_file_filter_get_needed ()
153
154-- GtkFileFilterFlags gtk_file_filter_get_needed
155-- 														  (GtkFileFilter *filter);
156
157-- Gets the fields that need to be filled in for the structure passed to gtk_file_filter_filter()
158
159-- This function will not typically be used by applications; it is intended principally for use in the implementation of GtkFileChooser.
160
161-- filter : 	a GtkFileFilter
162-- Returns : 	bitfield of flags indicating needed fields when calling gtk_file_filter_filter()
163
164-- Since 2.4
165-- gtk_file_filter_filter ()
166
167-- gboolean    gtk_file_filter_filter          (GtkFileFilter *filter,
168-- 															const GtkFileFilterInfo *filter_info);
169
170-- Tests whether a file should be displayed according to filter. The GtkFileFilterInfo structure filter_info should include the fields returned from gtk_file_filter_get_needed().
171
172-- This function will not typically be used by applications; it is intended principally for use in the implementation of GtkFileChooser.
173
174-- filter : 	a GtkFileFilter
175-- filter_info : 	a GtkFileFilterInfo structure containing information about a file.
176-- Returns : 	TRUE if the file should be displayed
177feature
178	struct_size: INTEGER is
179		external "C inline use <gtk/gtk.h>"
180		alias "sizeof(GtkFileFilter)"
181		end
182end