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