]> git.saurik.com Git - wxWidgets.git/blob - include/wx/mimetype.h
Add wxUSE_RIBBON to wx/setup_inc.h and wx/chkconf.h.
[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 licence (part of wxExtra library)
11 /////////////////////////////////////////////////////////////////////////////
12
13 #ifndef _WX_MIMETYPE_H_
14 #define _WX_MIMETYPE_H_
15
16 // ----------------------------------------------------------------------------
17 // headers and such
18 // ----------------------------------------------------------------------------
19
20 #include "wx/defs.h"
21
22 #if wxUSE_MIMETYPE
23
24 // the things we really need
25 #include "wx/string.h"
26 #include "wx/dynarray.h"
27 #include "wx/arrstr.h"
28
29 #include <stdarg.h>
30
31 // fwd decls
32 class WXDLLIMPEXP_FWD_BASE wxIconLocation;
33 class WXDLLIMPEXP_FWD_BASE wxFileTypeImpl;
34 class WXDLLIMPEXP_FWD_BASE wxMimeTypesManagerImpl;
35
36 // these constants define the MIME informations source under UNIX and are used
37 // by wxMimeTypesManager::Initialize()
38 enum wxMailcapStyle
39 {
40 wxMAILCAP_STANDARD = 1,
41 wxMAILCAP_NETSCAPE = 2,
42 wxMAILCAP_KDE = 4,
43 wxMAILCAP_GNOME = 8,
44
45 wxMAILCAP_ALL = 15
46 };
47
48 /*
49 TODO: would it be more convenient to have this class?
50
51 class WXDLLIMPEXP_BASE wxMimeType : public wxString
52 {
53 public:
54 // all string ctors here
55
56 wxString GetType() const { return BeforeFirst(wxT('/')); }
57 wxString GetSubType() const { return AfterFirst(wxT('/')); }
58
59 void SetSubType(const wxString& subtype)
60 {
61 *this = GetType() + wxT('/') + subtype;
62 }
63
64 bool Matches(const wxMimeType& wildcard)
65 {
66 // implement using wxMimeTypesManager::IsOfType()
67 }
68 };
69
70 */
71
72 // wxMimeTypeCommands stores the verbs defined for the given MIME type with
73 // their values
74 class WXDLLIMPEXP_BASE wxMimeTypeCommands
75 {
76 public:
77 wxMimeTypeCommands() {}
78
79 wxMimeTypeCommands(const wxArrayString& verbs,
80 const wxArrayString& commands)
81 : m_verbs(verbs),
82 m_commands(commands)
83 {
84 }
85
86 // add a new verb with the command or replace the old value
87 void AddOrReplaceVerb(const wxString& verb, const wxString& cmd);
88 void Add(const wxString& s)
89 {
90 m_verbs.Add(s.BeforeFirst(wxT('=')));
91 m_commands.Add(s.AfterFirst(wxT('=')));
92 }
93
94 // access the commands
95 size_t GetCount() const { return m_verbs.GetCount(); }
96 const wxString& GetVerb(size_t n) const { return m_verbs[n]; }
97 const wxString& GetCmd(size_t n) const { return m_commands[n]; }
98
99 bool HasVerb(const wxString& verb) const
100 { return m_verbs.Index(verb) != wxNOT_FOUND; }
101
102 // returns empty string and wxNOT_FOUND in idx if no such verb
103 wxString GetCommandForVerb(const wxString& verb, size_t *idx = NULL) const;
104
105 // get a "verb=command" string
106 wxString GetVerbCmd(size_t n) const;
107
108 private:
109 wxArrayString m_verbs;
110 wxArrayString m_commands;
111 };
112
113 // ----------------------------------------------------------------------------
114 // wxFileTypeInfo: static container of information accessed via wxFileType.
115 //
116 // This class is used with wxMimeTypesManager::AddFallbacks() and Associate()
117 // ----------------------------------------------------------------------------
118
119 class WXDLLIMPEXP_BASE wxFileTypeInfo
120 {
121 private:
122 void DoVarArgInit(const wxString& mimeType,
123 const wxString& openCmd,
124 const wxString& printCmd,
125 const wxString& desc,
126 va_list argptr);
127
128 void VarArgInit(const wxString *mimeType,
129 const wxString *openCmd,
130 const wxString *printCmd,
131 const wxString *desc,
132 // the other parameters form a NULL terminated list of
133 // extensions
134 ...);
135
136 public:
137 // NB: This is a helper to get implicit conversion of variadic ctor's
138 // fixed arguments into something that can be passed to VarArgInit().
139 // Do not use, it's used by the ctor only.
140 struct WXDLLIMPEXP_BASE CtorString
141 {
142 CtorString(const char *str) : m_str(str) {}
143 CtorString(const wchar_t *str) : m_str(str) {}
144 CtorString(const wxString& str) : m_str(str) {}
145 CtorString(const wxCStrData& str) : m_str(str) {}
146 CtorString(const wxScopedCharBuffer& str) : m_str(str) {}
147 CtorString(const wxScopedWCharBuffer& str) : m_str(str) {}
148
149 operator const wxString*() const { return &m_str; }
150
151 wxString m_str;
152 };
153
154 // ctors
155 // a normal item
156
157 // wxFileTypeInfo(const wxString& mimeType,
158 // const wxString& openCmd,
159 // const wxString& printCmd,
160 // const wxString& desc,
161 // // the other parameters form a list of extensions for this
162 // // file type and should be terminated with wxNullPtr (not
163 // // just NULL!)
164 // ...);
165 WX_DEFINE_VARARG_FUNC_CTOR(wxFileTypeInfo,
166 4, (const CtorString&,
167 const CtorString&,
168 const CtorString&,
169 const CtorString&),
170 VarArgInit, VarArgInit)
171 #ifdef __WATCOMC__
172 // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
173 WX_VARARG_WATCOM_WORKAROUND_CTOR(
174 wxFileTypeInfo,
175 4, (const wxString&,
176 const wxString&,
177 const wxString&,
178 const wxString&),
179 (CtorString(f1),
180 CtorString(f2),
181 CtorString(f3),
182 CtorString(f4)));
183 WX_VARARG_WATCOM_WORKAROUND_CTOR(
184 wxFileTypeInfo,
185 4, (const wxCStrData&,
186 const wxCStrData&,
187 const wxCStrData&,
188 const wxCStrData&),
189 (CtorString(f1),
190 CtorString(f2),
191 CtorString(f3),
192 CtorString(f4)));
193 WX_VARARG_WATCOM_WORKAROUND_CTOR(
194 wxFileTypeInfo,
195 4, (const char*,
196 const char*,
197 const char*,
198 const char*),
199 (CtorString(f1),
200 CtorString(f2),
201 CtorString(f3),
202 CtorString(f4)));
203 WX_VARARG_WATCOM_WORKAROUND_CTOR(
204 wxFileTypeInfo,
205 4, (const wchar_t*,
206 const wchar_t*,
207 const wchar_t*,
208 const wchar_t*),
209 (CtorString(f1),
210 CtorString(f2),
211 CtorString(f3),
212 CtorString(f4)));
213 #endif
214
215 // the array elements correspond to the parameters of the ctor above in
216 // the same order
217 wxFileTypeInfo(const wxArrayString& sArray);
218
219 // invalid item - use this to terminate the array passed to
220 // wxMimeTypesManager::AddFallbacks
221 wxFileTypeInfo() { }
222
223 // test if this object can be used
224 bool IsValid() const { return !m_mimeType.empty(); }
225
226 // setters
227 // set the icon info
228 void SetIcon(const wxString& iconFile, int iconIndex = 0)
229 {
230 m_iconFile = iconFile;
231 m_iconIndex = iconIndex;
232 }
233 // set the short desc
234 void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }
235
236 // accessors
237 // get the MIME type
238 const wxString& GetMimeType() const { return m_mimeType; }
239 // get the open command
240 const wxString& GetOpenCommand() const { return m_openCmd; }
241 // get the print command
242 const wxString& GetPrintCommand() const { return m_printCmd; }
243 // get the short description (only used under Win32 so far)
244 const wxString& GetShortDesc() const { return m_shortDesc; }
245 // get the long, user visible description
246 const wxString& GetDescription() const { return m_desc; }
247 // get the array of all extensions
248 const wxArrayString& GetExtensions() const { return m_exts; }
249 size_t GetExtensionsCount() const {return m_exts.GetCount(); }
250 // get the icon info
251 const wxString& GetIconFile() const { return m_iconFile; }
252 int GetIconIndex() const { return m_iconIndex; }
253
254 private:
255 wxString m_mimeType, // the MIME type in "type/subtype" form
256 m_openCmd, // command to use for opening the file (%s allowed)
257 m_printCmd, // command to use for printing the file (%s allowed)
258 m_shortDesc, // a short string used in the registry
259 m_desc; // a free form description of this file type
260
261 // icon stuff
262 wxString m_iconFile; // the file containing the icon
263 int m_iconIndex; // icon index in this file
264
265 wxArrayString m_exts; // the extensions which are mapped on this filetype
266
267
268 #if 0 // TODO
269 // the additional (except "open" and "print") command names and values
270 wxArrayString m_commandNames,
271 m_commandValues;
272 #endif // 0
273 };
274
275 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo,
276 WXDLLIMPEXP_BASE);
277
278 // ----------------------------------------------------------------------------
279 // wxFileType: gives access to all information about the files of given type.
280 //
281 // This class holds information about a given "file type". File type is the
282 // same as MIME type under Unix, but under Windows it corresponds more to an
283 // extension than to MIME type (in fact, several extensions may correspond to a
284 // file type). This object may be created in many different ways and depending
285 // on how it was created some fields may be unknown so the return value of all
286 // the accessors *must* be checked!
287 // ----------------------------------------------------------------------------
288
289 class WXDLLIMPEXP_BASE wxFileType
290 {
291 friend class WXDLLIMPEXP_FWD_BASE wxMimeTypesManagerImpl; // it has access to m_impl
292
293 public:
294 // An object of this class must be passed to Get{Open|Print}Command. The
295 // default implementation is trivial and doesn't know anything at all about
296 // parameters, only filename and MIME type are used (so it's probably ok for
297 // Windows where %{param} is not used anyhow)
298 class MessageParameters
299 {
300 public:
301 // ctors
302 MessageParameters() { }
303 MessageParameters(const wxString& filename,
304 const wxString& mimetype = wxEmptyString)
305 : m_filename(filename), m_mimetype(mimetype) { }
306
307 // accessors (called by GetOpenCommand)
308 // filename
309 const wxString& GetFileName() const { return m_filename; }
310 // mime type
311 const wxString& GetMimeType() const { return m_mimetype; }
312
313 // override this function in derived class
314 virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
315 { return wxEmptyString; }
316
317 // virtual dtor as in any base class
318 virtual ~MessageParameters() { }
319
320 protected:
321 wxString m_filename, m_mimetype;
322 };
323
324 // ctor from static data
325 wxFileType(const wxFileTypeInfo& ftInfo);
326
327 // accessors: all of them return true if the corresponding information
328 // could be retrieved/found, false otherwise (and in this case all [out]
329 // parameters are unchanged)
330 // return the MIME type for this file type
331 bool GetMimeType(wxString *mimeType) const;
332 bool GetMimeTypes(wxArrayString& mimeTypes) const;
333 // fill passed in array with all extensions associated with this file
334 // type
335 bool GetExtensions(wxArrayString& extensions);
336 // get the icon corresponding to this file type and of the given size
337 bool GetIcon(wxIconLocation *iconloc) const;
338 bool GetIcon(wxIconLocation *iconloc,
339 const MessageParameters& params) const;
340 // get a brief file type description ("*.txt" => "text document")
341 bool GetDescription(wxString *desc) const;
342
343 // get the command to be used to open/print the given file.
344 // get the command to execute the file of given type
345 bool GetOpenCommand(wxString *openCmd,
346 const MessageParameters& params) const;
347 // a simpler to use version of GetOpenCommand() -- it only takes the
348 // filename and returns an empty string on failure
349 wxString GetOpenCommand(const wxString& filename) const;
350 // get the command to print the file of given type
351 bool GetPrintCommand(wxString *printCmd,
352 const MessageParameters& params) const;
353
354
355 // return the number of commands defined for this file type, 0 if none
356 size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
357 const wxFileType::MessageParameters& params) const;
358
359 // set an arbitrary command, ask confirmation if it already exists and
360 // overwriteprompt is true
361 bool SetCommand(const wxString& cmd, const wxString& verb,
362 bool overwriteprompt = true);
363
364 bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);
365
366
367 // remove the association for this filetype from the system MIME database:
368 // notice that it will only work if the association is defined in the user
369 // file/registry part, we will never modify the system-wide settings
370 bool Unassociate();
371
372 // operations
373 // expand a string in the format of GetOpenCommand (which may contain
374 // '%s' and '%t' format specificators for the file name and mime type
375 // and %{param} constructions).
376 static wxString ExpandCommand(const wxString& command,
377 const MessageParameters& params);
378
379 // dtor (not virtual, shouldn't be derived from)
380 ~wxFileType();
381
382 private:
383 // default ctor is private because the user code never creates us
384 wxFileType();
385
386 // no copy ctor/assignment operator
387 wxFileType(const wxFileType&);
388 wxFileType& operator=(const wxFileType&);
389
390 // the static container of wxFileType data: if it's not NULL, it means that
391 // this object is used as fallback only
392 const wxFileTypeInfo *m_info;
393
394 // the object which implements the real stuff like reading and writing
395 // to/from system MIME database
396 wxFileTypeImpl *m_impl;
397 };
398
399 //----------------------------------------------------------------------------
400 // wxMimeTypesManagerFactory
401 //----------------------------------------------------------------------------
402
403 class WXDLLIMPEXP_BASE wxMimeTypesManagerFactory
404 {
405 public:
406 wxMimeTypesManagerFactory() {}
407 virtual ~wxMimeTypesManagerFactory() {}
408
409 virtual wxMimeTypesManagerImpl *CreateMimeTypesManagerImpl();
410
411 static void Set( wxMimeTypesManagerFactory *factory );
412 static wxMimeTypesManagerFactory *Get();
413
414 private:
415 static wxMimeTypesManagerFactory *m_factory;
416 };
417
418 // ----------------------------------------------------------------------------
419 // wxMimeTypesManager: interface to system MIME database.
420 //
421 // This class accesses the information about all known MIME types and allows
422 // the application to retrieve information (including how to handle data of
423 // given type) about them.
424 // ----------------------------------------------------------------------------
425
426 class WXDLLIMPEXP_BASE wxMimeTypesManager
427 {
428 public:
429 // static helper functions
430 // -----------------------
431
432 // check if the given MIME type is the same as the other one: the
433 // second argument may contain wildcards ('*'), but not the first. If
434 // the types are equal or if the mimeType matches wildcard the function
435 // returns true, otherwise it returns false
436 static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
437
438 // ctor
439 wxMimeTypesManager();
440
441 // NB: the following 2 functions are for Unix only and don't do anything
442 // elsewhere
443
444 // loads data from standard files according to the mailcap styles
445 // specified: this is a bitwise OR of wxMailcapStyle values
446 //
447 // use the extraDir parameter if you want to look for files in another
448 // directory
449 void Initialize(int mailcapStyle = wxMAILCAP_ALL,
450 const wxString& extraDir = wxEmptyString);
451
452 // and this function clears all the data from the manager
453 void ClearData();
454
455 // Database lookup: all functions return a pointer to wxFileType object
456 // whose methods may be used to query it for the information you're
457 // interested in. If the return value is !NULL, caller is responsible for
458 // deleting it.
459 // get file type from file extension
460 wxFileType *GetFileTypeFromExtension(const wxString& ext);
461 // get file type from MIME type (in format <category>/<format>)
462 wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
463
464 // enumerate all known MIME types
465 //
466 // returns the number of retrieved file types
467 size_t EnumAllFileTypes(wxArrayString& mimetypes);
468
469 // these functions can be used to provide default values for some of the
470 // MIME types inside the program itself
471 //
472 // The filetypes array should be terminated by either NULL entry or an
473 // invalid wxFileTypeInfo (i.e. the one created with default ctor)
474 void AddFallbacks(const wxFileTypeInfo *filetypes);
475 void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
476
477 // create or remove associations
478
479 // create a new association using the fields of wxFileTypeInfo (at least
480 // the MIME type and the extension should be set)
481 // if the other fields are empty, the existing values should be left alone
482 wxFileType *Associate(const wxFileTypeInfo& ftInfo);
483
484 // undo Associate()
485 bool Unassociate(wxFileType *ft) ;
486
487 // dtor (not virtual, shouldn't be derived from)
488 ~wxMimeTypesManager();
489
490 private:
491 // no copy ctor/assignment operator
492 wxMimeTypesManager(const wxMimeTypesManager&);
493 wxMimeTypesManager& operator=(const wxMimeTypesManager&);
494
495 // the fallback info which is used if the information is not found in the
496 // real system database
497 wxArrayFileTypeInfo m_fallbacks;
498
499 // the object working with the system MIME database
500 wxMimeTypesManagerImpl *m_impl;
501
502 // if m_impl is NULL, create one
503 void EnsureImpl();
504
505 friend class wxMimeTypeCmnModule;
506 };
507
508
509 // ----------------------------------------------------------------------------
510 // global variables
511 // ----------------------------------------------------------------------------
512
513 // the default mime manager for wxWidgets programs
514 extern WXDLLIMPEXP_DATA_BASE(wxMimeTypesManager *) wxTheMimeTypesManager;
515
516 #endif // wxUSE_MIMETYPE
517
518 #endif
519 //_WX_MIMETYPE_H_