]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: mimetype.h | |
e54c96f1 | 3 | // Purpose: interface of wxMimeTypesManager |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxMimeTypesManager | |
7c913512 | 11 | |
30b10ed1 | 12 | This class allows the application to retrieve informations about all known |
23324ae1 | 13 | MIME types from a system-specific location and the filename extensions to the |
30b10ed1 FM |
14 | MIME types and vice versa. |
15 | ||
16 | MIME stands for "Multipurpose Internet Mail Extensions" and was originally | |
17 | used in mail protocols. It's standardized by several RFCs. | |
18 | ||
ba1d7a6c FM |
19 | Under Windows, the MIME type information is queried from registry. |
20 | Under Linux and Unix, it is queried from the XDG data directories. | |
7c913512 | 21 | |
30b10ed1 | 22 | Currently, wxMimeTypesManager is limited to @e reading MIME type information. |
7c913512 | 23 | |
ba1d7a6c | 24 | The application should not construct its own manager: it should use the |
30b10ed1 FM |
25 | object pointer ::wxTheMimeTypesManager. |
26 | The functions GetFileTypeFromMimeType() and GetFileTypeFromExtension() | |
27 | return a wxFileType object which may be further queried for file description, | |
28 | icon and other attributes. | |
ba1d7a6c FM |
29 | |
30 | @section mimetypemanager_helpers Helper functions | |
31 | ||
32 | All of these functions are static (i.e. don't need a wxMimeTypesManager object | |
33 | to call them) and provide some useful operations for string representations of | |
34 | MIME types. Their usage is recommended instead of directly working with MIME | |
35 | types using wxString functions. | |
36 | ||
37 | - wxMimeTypesManager::IsOfType() | |
38 | ||
ba1d7a6c FM |
39 | @section mimetypemanager_query Query database |
40 | ||
41 | These functions are the heart of this class: they allow to find a file type | |
42 | object from either file extension or MIME type. | |
43 | If the function is successful, it returns a pointer to the wxFileType object | |
30b10ed1 | 44 | which must be deleted by the caller, otherwise @NULL will be returned. |
ba1d7a6c FM |
45 | |
46 | - wxMimeTypesManager::GetFileTypeFromMimeType() | |
47 | - wxMimeTypesManager::GetFileTypeFromExtension() | |
48 | ||
23324ae1 | 49 | @library{wxbase} |
3c99e2fd | 50 | @category{cfg} |
7c913512 | 51 | |
e54c96f1 | 52 | @see wxFileType |
23324ae1 | 53 | */ |
7c913512 | 54 | class wxMimeTypesManager |
23324ae1 FM |
55 | { |
56 | public: | |
57 | /** | |
f369c7c2 | 58 | Constructor puts the object in the "working" state. |
23324ae1 FM |
59 | */ |
60 | wxMimeTypesManager(); | |
61 | ||
62 | /** | |
63 | Destructor is not virtual, so this class should not be derived from. | |
64 | */ | |
65 | ~wxMimeTypesManager(); | |
66 | ||
67 | /** | |
68 | This function may be used to provide hard-wired fallbacks for the MIME types | |
69 | and extensions that might not be present in the system MIME database. | |
23324ae1 FM |
70 | Please see the typetest sample for an example of using it. |
71 | */ | |
4cc4bfaf | 72 | void AddFallbacks(const wxFileTypeInfo* fallbacks); |
23324ae1 | 73 | |
23324ae1 FM |
74 | /** |
75 | Gather information about the files with given extension and return the | |
f369c7c2 | 76 | corresponding wxFileType object or @NULL if the extension is unknown. |
ba1d7a6c | 77 | |
4cc4bfaf | 78 | The @a extension parameter may have, or not, the leading dot, if it has it, |
23324ae1 FM |
79 | it is stripped automatically. It must not however be empty. |
80 | */ | |
81 | wxFileType* GetFileTypeFromExtension(const wxString& extension); | |
82 | ||
83 | /** | |
84 | Gather information about the files with given MIME type and return the | |
f369c7c2 | 85 | corresponding wxFileType object or @NULL if the MIME type is unknown. |
23324ae1 FM |
86 | */ |
87 | wxFileType* GetFileTypeFromMimeType(const wxString& mimeType); | |
88 | ||
23324ae1 FM |
89 | |
90 | /** | |
ba1d7a6c FM |
91 | This function returns @true if either the given @a mimeType is exactly |
92 | the same as @a wildcard or if it has the same category and the subtype of | |
4cc4bfaf FM |
93 | @a wildcard is '*'. Note that the '*' wildcard is not allowed in |
94 | @a mimeType itself. | |
ba1d7a6c | 95 | |
23324ae1 FM |
96 | The comparison don by this function is case insensitive so it is not |
97 | necessary to convert the strings to the same case before calling it. | |
98 | */ | |
f369c7c2 | 99 | static bool IsOfType(const wxString& mimeType, const wxString& wildcard); |
23324ae1 FM |
100 | }; |
101 | ||
102 | ||
f369c7c2 RR |
103 | /** |
104 | The global wxMimeTypesManager instance. | |
105 | */ | |
106 | wxMimeTypesManager* wxTheMimeTypesManager; | |
107 | ||
e54c96f1 | 108 | |
23324ae1 FM |
109 | /** |
110 | @class wxFileType | |
7c913512 | 111 | |
ba1d7a6c FM |
112 | This class holds information about a given @e file type. |
113 | ||
114 | File type is the same as MIME type under Unix, but under Windows it corresponds | |
115 | more to an extension than to MIME type (in fact, several extensions may | |
116 | correspond to a file type). | |
117 | ||
118 | This object may be created in several different ways: the program might know the | |
119 | file extension and wish to find out the corresponding MIME type or, conversely, it | |
23324ae1 FM |
120 | might want to find the right extension for the file to which it writes the |
121 | contents of given MIME type. Depending on how it was created some fields may be | |
122 | unknown so the return value of all the accessors @b must be checked: @false | |
123 | will be returned if the corresponding information couldn't be found. | |
7c913512 | 124 | |
23324ae1 | 125 | The objects of this class are never created by the application code but are |
7c913512 | 126 | returned by wxMimeTypesManager::GetFileTypeFromMimeType and |
23324ae1 FM |
127 | wxMimeTypesManager::GetFileTypeFromExtension methods. |
128 | But it is your responsibility to delete the returned pointer when you're done | |
129 | with it! | |
7c913512 | 130 | |
23324ae1 FM |
131 | A brief reminder about what the MIME types are (see the RFC 1341 for more |
132 | information): basically, it is just a pair category/type (for example, | |
133 | "text/plain") where the category is a basic indication of what a file is. | |
134 | Examples of categories are "application", "image", "text", "binary", and | |
135 | type is a precise definition of the document format: "plain" in the example | |
136 | above means just ASCII text without any formatting, while "text/html" is the | |
137 | HTML document source. | |
7c913512 | 138 | |
23324ae1 FM |
139 | A MIME type may have one or more associated extensions: "text/plain" will |
140 | typically correspond to the extension ".txt", but may as well be associated with | |
141 | ".ini" or ".conf". | |
7c913512 | 142 | |
ba1d7a6c FM |
143 | |
144 | @section filetype_example MessageParameters class | |
145 | ||
146 | One of the most common usages of MIME is to encode an e-mail message. | |
147 | The MIME type of the encoded message is an example of a message parameter. | |
148 | These parameters are found in the message headers ("Content-XXX"). | |
149 | ||
150 | At the very least, they must specify the MIME type and the version of MIME | |
151 | used, but almost always they provide additional information about the message | |
152 | such as the original file name or the charset (for the text documents). | |
153 | These parameters may be useful to the program used to open, edit, view or | |
154 | print the message, so, for example, an e-mail client program will have to | |
155 | pass them to this program. Because wxFileType itself can not know about | |
156 | these parameters, it uses MessageParameters class to query them. | |
157 | ||
158 | The default implementation only requires the caller to provide the file name | |
159 | (always used by the program to be called - it must know which file to open) | |
160 | and the MIME type and supposes that there are no other parameters. | |
161 | ||
162 | If you wish to supply additional parameters, you must derive your own class | |
163 | from MessageParameters and override GetParamValue() function, for example: | |
164 | ||
165 | @code | |
166 | // provide the message parameters for the MIME type manager | |
167 | class MailMessageParameters : public wxFileType::MessageParameters | |
168 | { | |
169 | public: | |
170 | MailMessageParameters(const wxString& filename, | |
171 | const wxString& mimetype) | |
172 | : wxFileType::MessageParameters(filename, mimetype) | |
173 | { | |
174 | } | |
175 | ||
176 | virtual wxString GetParamValue(const wxString& name) const | |
177 | { | |
178 | // parameter names are not case-sensitive | |
179 | if ( name.CmpNoCase("charset") == 0 ) | |
180 | return "US-ASCII"; | |
181 | else | |
182 | return wxFileType::MessageParameters::GetParamValue(name); | |
183 | } | |
184 | }; | |
185 | @endcode | |
186 | ||
187 | Now you only need to create an object of this class and pass it to, for example, | |
188 | GetOpenCommand like this: | |
189 | ||
190 | @code | |
191 | wxString command; | |
192 | if ( filetype->GetOpenCommand(&command, | |
193 | MailMessageParameters("foo.txt", "text/plain")) ) | |
194 | { | |
195 | // the full command for opening the text documents is in 'command' | |
196 | // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix) | |
197 | } | |
198 | else | |
199 | { | |
200 | // we don't know how to handle such files... | |
201 | } | |
202 | @endcode | |
203 | ||
204 | Windows: As only the file name is used by the program associated with the | |
205 | given extension anyhow (but no other message parameters), there is no need | |
206 | to ever derive from MessageParameters class for a Windows-only program. | |
207 | ||
208 | ||
23324ae1 | 209 | @library{wxbase} |
3c99e2fd | 210 | @category{data} |
7c913512 | 211 | |
e54c96f1 | 212 | @see wxMimeTypesManager |
23324ae1 | 213 | */ |
7c913512 | 214 | class wxFileType |
23324ae1 | 215 | { |
8067ee11 | 216 | private: |
23324ae1 FM |
217 | /** |
218 | The default constructor is private because you should never create objects of | |
219 | this type: they are only returned by wxMimeTypesManager methods. | |
220 | */ | |
221 | wxFileType(); | |
222 | ||
8067ee11 FM |
223 | public: |
224 | /** | |
225 | Copy ctor. | |
226 | */ | |
227 | wxFileType(const wxFileTypeInfo& ftInfo); | |
228 | ||
23324ae1 FM |
229 | /** |
230 | The destructor of this class is not virtual, so it should not be derived from. | |
231 | */ | |
232 | ~wxFileType(); | |
233 | ||
234 | /** | |
235 | This function is primarily intended for GetOpenCommand and GetPrintCommand | |
ba1d7a6c FM |
236 | usage but may be also used by the application directly if, for example, you |
237 | want to use some non-default command to open the file. | |
3c4f71cc | 238 | |
ba1d7a6c FM |
239 | The function replaces all occurrences of: |
240 | - %s with the full file name | |
241 | - %t with the MIME type | |
242 | - %{param} with the value of the parameter @e param | |
23324ae1 | 243 | using the MessageParameters object you pass to it. |
ba1d7a6c | 244 | |
23324ae1 FM |
245 | If there is no '%s' in the command string (and the string is not empty), it is |
246 | assumed that the command reads the data on stdin and so the effect is the same | |
247 | as " %s" were appended to the string. | |
ba1d7a6c | 248 | |
23324ae1 FM |
249 | Unlike all other functions of this class, there is no error return for this |
250 | function. | |
251 | */ | |
252 | static wxString ExpandCommand(const wxString& command, | |
382f12e4 | 253 | const MessageParameters& params); |
23324ae1 FM |
254 | |
255 | /** | |
4cc4bfaf | 256 | If the function returns @true, the string pointed to by @a desc is filled |
23324ae1 FM |
257 | with a brief description for this file type: for example, "text document" for |
258 | the "text/plain" MIME type. | |
259 | */ | |
adaaa686 | 260 | bool GetDescription(wxString* desc) const; |
23324ae1 FM |
261 | |
262 | /** | |
4cc4bfaf | 263 | If the function returns @true, the array @a extensions is filled |
23324ae1 | 264 | with all extensions associated with this file type: for example, it may |
ba1d7a6c FM |
265 | contain the following two elements for the MIME type "text/html" |
266 | (notice the absence of the leading dot): "html" and "htm". | |
267 | ||
23324ae1 | 268 | @b Windows: This function is currently not implemented: there is no |
ba1d7a6c FM |
269 | (efficient) way to retrieve associated extensions from the given MIME type |
270 | on this platform, so it will only return @true if the wxFileType object was | |
271 | created by wxMimeTypesManager::GetFileTypeFromExtension function in the | |
272 | first place. | |
23324ae1 FM |
273 | */ |
274 | bool GetExtensions(wxArrayString& extensions); | |
275 | ||
276 | /** | |
277 | If the function returns @true, the @c iconLoc is filled with the | |
ba1d7a6c FM |
278 | location of the icon for this MIME type. |
279 | A wxIcon may be created from @a iconLoc later. | |
280 | ||
23324ae1 FM |
281 | @b Windows: The function returns the icon shown by Explorer for the files of |
282 | the specified type. | |
ba1d7a6c | 283 | |
23324ae1 | 284 | @b Mac: This function is not implemented and always returns @false. |
ba1d7a6c | 285 | |
23324ae1 FM |
286 | @b Unix: MIME manager gathers information about icons from GNOME |
287 | and KDE settings and thus GetIcon's success depends on availability | |
288 | of these desktop environments. | |
289 | */ | |
adaaa686 | 290 | bool GetIcon(wxIconLocation* iconLoc) const; |
23324ae1 FM |
291 | |
292 | /** | |
4cc4bfaf | 293 | If the function returns @true, the string pointed to by @a mimeType is filled |
23324ae1 FM |
294 | with full MIME type specification for this file type: for example, "text/plain". |
295 | */ | |
adaaa686 | 296 | bool GetMimeType(wxString* mimeType) const; |
23324ae1 FM |
297 | |
298 | /** | |
ba1d7a6c FM |
299 | Same as GetMimeType() but returns array of MIME types. |
300 | ||
301 | This array will contain only one item in most cases but sometimes, | |
302 | notably under Unix with KDE, may contain more MIME types. | |
303 | This happens when one file extension is mapped to different MIME types | |
304 | by KDE, mailcap and mime.types. | |
23324ae1 | 305 | */ |
43c48e1e | 306 | bool GetMimeTypes(wxArrayString& mimeTypes) const; |
23324ae1 FM |
307 | |
308 | //@{ | |
309 | /** | |
310 | With the first version of this method, if the @true is returned, the | |
4cc4bfaf | 311 | string pointed to by @a command is filled with the command which must be |
ba1d7a6c FM |
312 | executed (see wxExecute()) in order to open the file of the given type. |
313 | ||
314 | In this case, the name of the file as well as any other parameters | |
315 | is retrieved from MessageParameters() class. | |
316 | ||
23324ae1 FM |
317 | In the second case, only the filename is specified and the command to be used |
318 | to open this kind of file is returned directly. An empty string is returned to | |
319 | indicate that an error occurred (typically meaning that there is no standard way | |
320 | to open this kind of files). | |
321 | */ | |
882678eb FM |
322 | bool GetOpenCommand(wxString* command, const MessageParameters& params); |
323 | wxString GetOpenCommand(const wxString& filename) const; | |
23324ae1 FM |
324 | //@} |
325 | ||
326 | /** | |
4cc4bfaf | 327 | If the function returns @true, the string pointed to by @a command is filled |
ba1d7a6c FM |
328 | with the command which must be executed (see wxExecute()) in order to |
329 | print the file of the given type. | |
23324ae1 | 330 | |
ba1d7a6c | 331 | The name of the file is retrieved from the MessageParameters class. |
23324ae1 | 332 | */ |
43c48e1e FM |
333 | bool GetPrintCommand(wxString* command, |
334 | const MessageParameters& params) const; | |
23324ae1 | 335 | }; |
e54c96f1 | 336 |