]> git.saurik.com Git - wxWidgets.git/blob - include/wx/mimetype.h
change the selection appropriately (and refresh it as needed) after deleting a notebo...
[wxWidgets.git] / include / wx / mimetype.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/mimetype.h
3 // Purpose: classes and functions to manage MIME types
4 // Author: Vadim Zeitlin
5 // Modified by:
6 // Chris Elliott (biol75@york.ac.uk) 5 Dec 00: write support for Win32
7 // Created: 23.09.98
8 // RCS-ID: $Id$
9 // Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows license (part of wxExtra library)
11 /////////////////////////////////////////////////////////////////////////////
12
13 #ifndef _WX_MIMETYPE_H_
14 #define _WX_MIMETYPE_H_
15
16 #ifdef __GNUG__
17 #pragma interface "mimetypebase.h"
18 #endif // __GNUG__
19
20 // ----------------------------------------------------------------------------
21 // headers and such
22 // ----------------------------------------------------------------------------
23
24 #include "wx/defs.h"
25
26 #if wxUSE_MIMETYPE
27
28 // the things we really need
29 #include "wx/string.h"
30 #include "wx/dynarray.h"
31
32 // fwd decls
33 class WXDLLEXPORT wxIcon;
34 class WXDLLEXPORT wxFileTypeImpl;
35 class WXDLLEXPORT wxMimeTypesManagerImpl;
36
37 // these constants define the MIME informations source under UNIX and are used
38 // by wxMimeTypesManager::Initialize()
39 enum wxMailcapStyle
40 {
41 wxMAILCAP_STANDARD = 1,
42 wxMAILCAP_NETSCAPE = 2,
43 wxMAILCAP_KDE = 4,
44 wxMAILCAP_GNOME = 8,
45
46 wxMAILCAP_ALL = 15
47 };
48
49 /*
50 TODO: would it be more convenient to have this class?
51
52 class WXDLLEXPORT wxMimeType : public wxString
53 {
54 public:
55 // all string ctors here
56
57 wxString GetType() const { return BeforeFirst(_T('/')); }
58 wxString GetSubType() const { return AfterFirst(_T('/')); }
59
60 void SetSubType(const wxString& subtype)
61 {
62 *this = GetType() + _T('/') + subtype;
63 }
64
65 bool Matches(const wxMimeType& wildcard)
66 {
67 // implement using wxMimeTypesManager::IsOfType()
68 }
69 };
70
71 */
72
73 // ----------------------------------------------------------------------------
74 // wxFileTypeInfo: static container of information accessed via wxFileType.
75 //
76 // This class is used with wxMimeTypesManager::AddFallbacks() and Associate()
77 // ----------------------------------------------------------------------------
78
79 class WXDLLEXPORT wxFileTypeInfo
80 {
81 public:
82 // ctors
83 // a normal item
84 wxFileTypeInfo(const char *mimeType,
85 const char *openCmd,
86 const char *printCmd,
87 const char *desc,
88 // the other parameters form a NULL terminated list of
89 // extensions
90 ...);
91
92 // the array elements correspond to the parameters of the ctor above in
93 // the same order
94 wxFileTypeInfo(const wxArrayString& sArray);
95
96 // invalid item - use this to terminate the array passed to
97 // wxMimeTypesManager::AddFallbacks
98 wxFileTypeInfo() { }
99
100 // test if this object can be used
101 bool IsValid() const { return !m_mimeType.IsEmpty(); }
102
103 // setters
104 // set the icon info
105 void SetIcon(const wxString& iconFile, int iconIndex = 0)
106 {
107 m_iconFile = iconFile;
108 m_iconIndex = iconIndex;
109 }
110 // set the short desc
111 void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }
112
113 // accessors
114 // get the MIME type
115 const wxString& GetMimeType() const { return m_mimeType; }
116 // get the open command
117 const wxString& GetOpenCommand() const { return m_openCmd; }
118 // get the print command
119 const wxString& GetPrintCommand() const { return m_printCmd; }
120 // get the short description (only used under Win32 so far)
121 const wxString& GetShortDesc() const { return m_shortDesc; }
122 // get the long, user visible description
123 const wxString& GetDescription() const { return m_desc; }
124 // get the array of all extensions
125 const wxArrayString& GetExtensions() const { return m_exts; }
126 int GetExtensionsCount() const {return m_exts.GetCount(); }
127 // get the icon info
128 const wxString& GetIconFile() const { return m_iconFile; }
129 int GetIconIndex() const { return m_iconIndex; }
130
131 private:
132 wxString m_mimeType, // the MIME type in "type/subtype" form
133 m_openCmd, // command to use for opening the file (%s allowed)
134 m_printCmd, // command to use for printing the file (%s allowed)
135 m_shortDesc, // a short string used in the registry
136 m_desc; // a free form description of this file type
137
138 // icon stuff
139 wxString m_iconFile; // the file containing the icon
140 int m_iconIndex; // icon index in this file
141
142 wxArrayString m_exts; // the extensions which are mapped on this filetype
143
144
145 #if 0 // TODO
146 // the additional (except "open" and "print") command names and values
147 wxArrayString m_commandNames,
148 m_commandValues;
149 #endif // 0
150 };
151
152 WX_DECLARE_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo);
153
154 // ----------------------------------------------------------------------------
155 // wxFileType: gives access to all information about the files of given type.
156 //
157 // This class holds information about a given "file type". File type is the
158 // same as MIME type under Unix, but under Windows it corresponds more to an
159 // extension than to MIME type (in fact, several extensions may correspond to a
160 // file type). This object may be created in many different ways and depending
161 // on how it was created some fields may be unknown so the return value of all
162 // the accessors *must* be checked!
163 // ----------------------------------------------------------------------------
164
165 class WXDLLEXPORT wxFileType
166 {
167 friend class WXDLLEXPORT wxMimeTypesManagerImpl; // it has access to m_impl
168
169 public:
170 // An object of this class must be passed to Get{Open|Print}Command. The
171 // default implementation is trivial and doesn't know anything at all about
172 // parameters, only filename and MIME type are used (so it's probably ok for
173 // Windows where %{param} is not used anyhow)
174 class MessageParameters
175 {
176 public:
177 // ctors
178 MessageParameters() { }
179 MessageParameters(const wxString& filename,
180 const wxString& mimetype = _T(""))
181 : m_filename(filename), m_mimetype(mimetype) { }
182
183 // accessors (called by GetOpenCommand)
184 // filename
185 const wxString& GetFileName() const { return m_filename; }
186 // mime type
187 const wxString& GetMimeType() const { return m_mimetype; }
188
189 // override this function in derived class
190 virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
191 { return wxEmptyString; }
192
193 // virtual dtor as in any base class
194 virtual ~MessageParameters() { }
195
196 protected:
197 wxString m_filename, m_mimetype;
198 };
199
200 // ctor from static data
201 wxFileType(const wxFileTypeInfo& ftInfo);
202
203 // accessors: all of them return true if the corresponding information
204 // could be retrieved/found, false otherwise (and in this case all [out]
205 // parameters are unchanged)
206 // return the MIME type for this file type
207 bool GetMimeType(wxString *mimeType) const;
208 bool GetMimeTypes(wxArrayString& mimeTypes) const;
209 // fill passed in array with all extensions associated with this file
210 // type
211 bool GetExtensions(wxArrayString& extensions);
212 // get the icon corresponding to this file type, the name of the file
213 // where the icon resides is return in iconfile if !NULL and its index
214 // in this file (Win-only) is in iconIndex
215 bool GetIcon(wxIcon *icon,
216 wxString *iconFile = NULL,
217 int *iconIndex = NULL) const;
218 // get a brief file type description ("*.txt" => "text document")
219 bool GetDescription(wxString *desc) const;
220
221 // get the command to be used to open/print the given file.
222 // get the command to execute the file of given type
223 bool GetOpenCommand(wxString *openCmd,
224 const MessageParameters& params) const;
225 // a simpler to use version of GetOpenCommand() -- it only takes the
226 // filename and returns an empty string on failure
227 wxString GetOpenCommand(const wxString& filename) const;
228 // get the command to print the file of given type
229 bool GetPrintCommand(wxString *printCmd,
230 const MessageParameters& params) const;
231
232
233 // return the number of commands defined for this file type, 0 if none
234 size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
235 const wxFileType::MessageParameters& params) const;
236
237 // set an arbitrary command, ask confirmation if it already exists and
238 // overwriteprompt is TRUE
239 bool SetCommand(const wxString& cmd, const wxString& verb,
240 bool overwriteprompt = TRUE);
241
242 bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);
243
244
245 // remove the association for this filetype from the system MIME database:
246 // notice that it will only work if the association is defined in the user
247 // file/registry part, we will never modify the system-wide settings
248 bool Unassociate();
249
250 // operations
251 // expand a string in the format of GetOpenCommand (which may contain
252 // '%s' and '%t' format specificators for the file name and mime type
253 // and %{param} constructions).
254 static wxString ExpandCommand(const wxString& command,
255 const MessageParameters& params);
256
257 // dtor (not virtual, shouldn't be derived from)
258 ~wxFileType();
259
260 private:
261 // default ctor is private because the user code never creates us
262 wxFileType();
263
264 // no copy ctor/assignment operator
265 wxFileType(const wxFileType&);
266 wxFileType& operator=(const wxFileType&);
267
268 // the static container of wxFileType data: if it's not NULL, it means that
269 // this object is used as fallback only
270 const wxFileTypeInfo *m_info;
271
272 // the object which implements the real stuff like reading and writing
273 // to/from system MIME database
274 wxFileTypeImpl *m_impl;
275 };
276
277 // ----------------------------------------------------------------------------
278 // wxMimeTypesManager: interface to system MIME database.
279 //
280 // This class accesses the information about all known MIME types and allows
281 // the application to retrieve information (including how to handle data of
282 // given type) about them.
283 // ----------------------------------------------------------------------------
284
285 class WXDLLEXPORT wxMimeTypesManager
286 {
287 public:
288 // static helper functions
289 // -----------------------
290
291 // check if the given MIME type is the same as the other one: the
292 // second argument may contain wildcards ('*'), but not the first. If
293 // the types are equal or if the mimeType matches wildcard the function
294 // returns TRUE, otherwise it returns FALSE
295 static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
296
297 // ctor
298 wxMimeTypesManager();
299
300 // NB: the following 2 functions are for Unix only and don't do anything
301 // elsewhere
302
303 // loads data from standard files according to the mailcap styles
304 // specified: this is a bitwise OR of wxMailcapStyle values
305 //
306 // use the extraDir parameter if you want to look for files in another
307 // directory
308 void Initialize(int mailcapStyle = wxMAILCAP_STANDARD,
309 const wxString& extraDir = wxEmptyString);
310
311 // and this function clears all the data from the manager
312 void ClearData();
313
314 // Database lookup: all functions return a pointer to wxFileType object
315 // whose methods may be used to query it for the information you're
316 // interested in. If the return value is !NULL, caller is responsible for
317 // deleting it.
318 // get file type from file extension
319 wxFileType *GetFileTypeFromExtension(const wxString& ext);
320 // get file type from MIME type (in format <category>/<format>)
321 wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
322
323 // other operations: return TRUE if there were no errors or FALSE if there
324 // were some unreckognized entries (the good entries are always read anyhow)
325 //
326 // FIXME: These ought to be private ??
327
328 // read in additional file (the standard ones are read automatically)
329 // in mailcap format (see mimetype.cpp for description)
330 //
331 // 'fallback' parameter may be set to TRUE to avoid overriding the
332 // settings from other, previously parsed, files by this one: normally,
333 // the files read most recently would override the older files, but with
334 // fallback == TRUE this won't happen
335
336 bool ReadMailcap(const wxString& filename, bool fallback = FALSE);
337 // read in additional file in mime.types format
338 bool ReadMimeTypes(const wxString& filename);
339
340 // enumerate all known MIME types
341 //
342 // returns the number of retrieved file types
343 size_t EnumAllFileTypes(wxArrayString& mimetypes);
344
345 // these functions can be used to provide default values for some of the
346 // MIME types inside the program itself (you may also use
347 // ReadMailcap(filenameWithDefaultTypes, TRUE /* use as fallback */) to
348 // achieve the same goal, but this requires having this info in a file).
349 //
350 // The filetypes array should be terminated by either NULL entry or an
351 // invalid wxFileTypeInfo (i.e. the one created with default ctor)
352 void AddFallbacks(const wxFileTypeInfo *filetypes);
353 void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
354
355 // create or remove associations
356
357 // create a new association using the fields of wxFileTypeInfo (at least
358 // the MIME type and the extension should be set)
359 // if the other fields are empty, the existing values should be left alone
360 wxFileType *Associate(const wxFileTypeInfo& ftInfo);
361
362 // undo Associate()
363 bool Unassociate(wxFileType *ft) ;
364
365 // dtor (not virtual, shouldn't be derived from)
366 ~wxMimeTypesManager();
367
368 private:
369 // no copy ctor/assignment operator
370 wxMimeTypesManager(const wxMimeTypesManager&);
371 wxMimeTypesManager& operator=(const wxMimeTypesManager&);
372
373 // the fallback info which is used if the information is not found in the
374 // real system database
375 wxArrayFileTypeInfo m_fallbacks;
376
377 // the object working with the system MIME database
378 wxMimeTypesManagerImpl *m_impl;
379
380 // if m_impl is NULL, create one
381 void EnsureImpl();
382
383 friend class wxMimeTypeCmnModule;
384 };
385
386
387 // ----------------------------------------------------------------------------
388 // global variables
389 // ----------------------------------------------------------------------------
390
391 // the default mime manager for wxWindows programs
392 WXDLLEXPORT_DATA(extern wxMimeTypesManager *) wxTheMimeTypesManager;
393
394 #endif // wxUSE_MIMETYPE
395
396 #endif
397 //_WX_MIMETYPE_H_