]> git.saurik.com Git - wxWidgets.git/blame - include/wx/mimetype.h
Added simplistic makefile/project files for wxWinCE.
[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>
10// Licence: wxWindows license (part of wxExtra library)
11/////////////////////////////////////////////////////////////////////////////
12
a6c65e88
VZ
13#ifndef _WX_MIMETYPE_H_
14#define _WX_MIMETYPE_H_
b13d92d1 15
af49c4b8 16#if defined(__GNUG__) && !defined(__APPLE__)
a6c65e88
VZ
17 #pragma interface "mimetypebase.h"
18#endif // __GNUG__
ecf23aa6 19
a6c65e88
VZ
20// ----------------------------------------------------------------------------
21// headers and such
22// ----------------------------------------------------------------------------
b13d92d1 23
ce4169a4
RR
24#include "wx/defs.h"
25
1e6feb95
VZ
26#if wxUSE_MIMETYPE
27
b13d92d1
VZ
28// the things we really need
29#include "wx/string.h"
ecf23aa6 30#include "wx/dynarray.h"
b13d92d1 31
a6c65e88
VZ
32// fwd decls
33class WXDLLEXPORT wxIcon;
34class WXDLLEXPORT wxFileTypeImpl;
35class WXDLLEXPORT wxMimeTypesManagerImpl;
36
2b813b73
VZ
37// these constants define the MIME informations source under UNIX and are used
38// by wxMimeTypesManager::Initialize()
39enum 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
a6c65e88
VZ
49/*
50 TODO: would it be more convenient to have this class?
51
52class WXDLLEXPORT wxMimeType : public wxString
53{
54public:
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
79class WXDLLEXPORT wxFileTypeInfo
80{
81public:
82 // ctors
83 // a normal item
57e67135
VZ
84 wxFileTypeInfo(const wxChar *mimeType,
85 const wxChar *openCmd,
86 const wxChar *printCmd,
87 const wxChar *desc,
a6c65e88
VZ
88 // the other parameters form a NULL terminated list of
89 // extensions
90 ...);
91
2b813b73
VZ
92 // the array elements correspond to the parameters of the ctor above in
93 // the same order
94 wxFileTypeInfo(const wxArrayString& sArray);
95
a6c65e88
VZ
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; }
2b813b73 126 int GetExtensionsCount() const {return m_exts.GetCount(); }
a6c65e88
VZ
127 // get the icon info
128 const wxString& GetIconFile() const { return m_iconFile; }
129 int GetIconIndex() const { return m_iconIndex; }
130
131private:
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
2b813b73 144
a6c65e88
VZ
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
152WX_DECLARE_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo);
66806a0b 153
a6c65e88
VZ
154// ----------------------------------------------------------------------------
155// wxFileType: gives access to all information about the files of given type.
156//
b13d92d1
VZ
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!
a6c65e88
VZ
163// ----------------------------------------------------------------------------
164
9f04ccb1 165class WXDLLEXPORT wxFileType
b13d92d1 166{
d5a07b9e 167friend class WXDLLEXPORT wxMimeTypesManagerImpl; // it has access to m_impl
b13d92d1
VZ
168
169public:
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() { }
0532a258
VZ
179 MessageParameters(const wxString& filename,
180 const wxString& mimetype = _T(""))
b13d92d1
VZ
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
a6c65e88
VZ
190 virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
191 { return wxEmptyString; }
b13d92d1
VZ
192
193 // virtual dtor as in any base class
194 virtual ~MessageParameters() { }
195
196 protected:
197 wxString m_filename, m_mimetype;
198 };
199
a6c65e88
VZ
200 // ctor from static data
201 wxFileType(const wxFileTypeInfo& ftInfo);
202
b13d92d1
VZ
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;
4d2976ad 208 bool GetMimeTypes(wxArrayString& mimeTypes) const;
b13d92d1
VZ
209 // fill passed in array with all extensions associated with this file
210 // type
211 bool GetExtensions(wxArrayString& extensions);
c7ce8392
VZ
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;
b13d92d1
VZ
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;
0532a258
VZ
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;
b13d92d1
VZ
228 // get the command to print the file of given type
229 bool GetPrintCommand(wxString *printCmd,
230 const MessageParameters& params) const;
231
c7ce8392
VZ
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
2b813b73
VZ
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
a6c65e88
VZ
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
c7ce8392
VZ
248 bool Unassociate();
249
b13d92d1
VZ
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
260private:
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
a6c65e88
VZ
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;
71f21f46 271
a6c65e88
VZ
272 // the object which implements the real stuff like reading and writing
273 // to/from system MIME database
274 wxFileTypeImpl *m_impl;
71f21f46
VZ
275};
276
a6c65e88
VZ
277// ----------------------------------------------------------------------------
278// wxMimeTypesManager: interface to system MIME database.
279//
b13d92d1
VZ
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.
a6c65e88
VZ
283// ----------------------------------------------------------------------------
284
9f04ccb1 285class WXDLLEXPORT wxMimeTypesManager
b13d92d1
VZ
286{
287public:
da61ab31
VZ
288 // static helper functions
289 // -----------------------
290
a6c65e88
VZ
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
da61ab31
VZ
294 // returns TRUE, otherwise it returns FALSE
295 static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
296
b13d92d1
VZ
297 // ctor
298 wxMimeTypesManager();
299
2b813b73
VZ
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
b13d92d1
VZ
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
cc385968
VZ
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)
2b813b73
VZ
325 //
326 // FIXME: These ought to be private ??
327
b13d92d1
VZ
328 // read in additional file (the standard ones are read automatically)
329 // in mailcap format (see mimetype.cpp for description)
cc385968
VZ
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
2b813b73 335
cc385968 336 bool ReadMailcap(const wxString& filename, bool fallback = FALSE);
b13d92d1 337 // read in additional file in mime.types format
cc385968 338 bool ReadMimeTypes(const wxString& filename);
b13d92d1 339
696e1ea0 340 // enumerate all known MIME types
1b986aef
VZ
341 //
342 // returns the number of retrieved file types
696e1ea0 343 size_t EnumAllFileTypes(wxArrayString& mimetypes);
1b986aef 344
71f21f46
VZ
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 //
a6c65e88
VZ
350 // The filetypes array should be terminated by either NULL entry or an
351 // invalid wxFileTypeInfo (i.e. the one created with default ctor)
8e124873 352 void AddFallbacks(const wxFileTypeInfo *filetypes);
a6c65e88
VZ
353 void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
354
355 // create or remove associations
71f21f46 356
a6c65e88
VZ
357 // create a new association using the fields of wxFileTypeInfo (at least
358 // the MIME type and the extension should be set)
2b813b73 359 // if the other fields are empty, the existing values should be left alone
a6c65e88
VZ
360 wxFileType *Associate(const wxFileTypeInfo& ftInfo);
361
362 // undo Associate()
2b813b73 363 bool Unassociate(wxFileType *ft) ;
c7ce8392 364
b13d92d1
VZ
365 // dtor (not virtual, shouldn't be derived from)
366 ~wxMimeTypesManager();
367
368private:
369 // no copy ctor/assignment operator
370 wxMimeTypesManager(const wxMimeTypesManager&);
371 wxMimeTypesManager& operator=(const wxMimeTypesManager&);
372
a6c65e88
VZ
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
b13d92d1 378 wxMimeTypesManagerImpl *m_impl;
c7ce8392 379
ecf23aa6
VS
380 // if m_impl is NULL, create one
381 void EnsureImpl();
c7ce8392 382
66806a0b 383 friend class wxMimeTypeCmnModule;
b13d92d1
VZ
384};
385
ecf23aa6
VS
386
387// ----------------------------------------------------------------------------
388// global variables
389// ----------------------------------------------------------------------------
390
391// the default mime manager for wxWindows programs
392WXDLLEXPORT_DATA(extern wxMimeTypesManager *) wxTheMimeTypesManager;
393
1e6feb95
VZ
394#endif // wxUSE_MIMETYPE
395
ce4169a4 396#endif
a6c65e88 397 //_WX_MIMETYPE_H_