]>
Commit | Line | Data |
---|---|---|
b13d92d1 VZ |
1 | \section{\class{wxFileType}}\label{wxfiletype} |
2 | ||
36edded9 | 3 | This class holds information about a given {\it file type}. File type is the same as |
b13d92d1 VZ |
4 | MIME type under Unix, but under Windows it corresponds more to an extension than |
5 | to MIME type (in fact, several extensions may correspond to a file type). This | |
6 | object may be created in several different ways: the program might know the file | |
7 | extension and wish to find out the corresponding MIME type or, conversely, it | |
8 | might want to find the right extension for the file to which it writes the | |
9 | contents of given MIME type. Depending on how it was created some fields may be | |
10 | unknown so the return value of all the accessors {\bf must} be checked: FALSE | |
11 | will be returned if the corresponding information couldn't be found. | |
12 | ||
13 | The objects of this class are never created by the application code but are | |
14 | returned by \helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype} and | |
15 | \helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} methods. | |
36edded9 | 16 | But it's your responsibility to delete the returned pointer when you're done |
b13d92d1 VZ |
17 | with it! |
18 | ||
19 | % TODO describe MIME types better than this... | |
36edded9 JS |
20 | A brief reminder about what the MIME types are (see the RFC 1341 for more |
21 | information): basically, it is just a pair category/type (for example, | |
22 | "text/plain") where the category is a basic indication of what a file is. | |
23 | Examples of categories are "application", "image", "text", "binary", and | |
b13d92d1 VZ |
24 | type is a precise definition of the document format: "plain" in the example |
25 | above means just ASCII text without any formatting, while "text/html" is the | |
26 | HTML document source. | |
27 | ||
28 | A MIME type may have one or more associated extensions: "text/plain" will | |
29 | typically correspond to the extension ".txt", but may as well be associated with | |
30 | ".ini" or ".conf". | |
31 | ||
b13d92d1 VZ |
32 | \wxheading{Derived from} |
33 | ||
36edded9 | 34 | None |
b13d92d1 | 35 | |
954b8ae6 JS |
36 | \wxheading{Include files} |
37 | ||
38 | <wx/mimetype.h> | |
39 | ||
b13d92d1 VZ |
40 | \wxheading{See also} |
41 | ||
42 | \helpref{wxMimeTypesManager}{wxmimetypesmanager} | |
43 | ||
44 | \latexignore{\rtfignore{\wxheading{Members}}} | |
45 | ||
6be663cf | 46 | \membersection{MessageParameters class}\label{wxfiletypemessageparameters} |
b13d92d1 VZ |
47 | |
48 | One of the most common usages of MIME is to encode an e-mail message. The MIME | |
49 | type of the encoded message is an example of a {\it message parameter}. These | |
50 | parameters are found in the message headers ("Content-XXX"). At the very least, | |
51 | they must specify the MIME type and the version of MIME used, but almost always | |
52 | they provide additional information about the message such as the original file | |
53 | name or the charset (for the text documents). | |
54 | ||
55 | These parameters may be useful to the program used to open, edit, view or print | |
56 | the message, so, for example, an e-mail client program will have to pass them to | |
57 | this program. Because wxFileType itself can not know about these parameters, | |
58 | it uses MessageParameters class to query them. The default implementation only | |
59 | requiers the caller to provide the file name (always used by the program to be | |
60 | called - it must know which file to open) and the MIME type and supposes that | |
61 | there are no other parameters. If you wish to supply additional parameters, you | |
62 | must derive your own class from MessageParameters and override GetParamValue() | |
63 | function, for example: | |
64 | ||
65 | \begin{verbatim} | |
66 | // provide the message parameters for the MIME type manager | |
2432b92d | 67 | class MailMessageParameters : public wxFileType::MessageParameters |
b13d92d1 VZ |
68 | { |
69 | public: | |
2432b92d | 70 | MailMessageParameters(const wxString& filename, |
b13d92d1 VZ |
71 | const wxString& mimetype) |
72 | : wxFileType::MessageParameters(filename, mimetype) | |
73 | { | |
74 | } | |
75 | ||
76 | virtual wxString GetParamValue(const wxString& name) const | |
77 | { | |
78 | // parameter names are not case-sensitive | |
79 | if ( name.CmpNoCase("charset") == 0 ) | |
80 | return "US-ASCII"; | |
81 | else | |
82 | return wxFileType::MessageParameters::GetParamValue(name); | |
83 | } | |
84 | }; | |
85 | \end{verbatim} | |
86 | ||
87 | Now you only need to create an object of this class and pass it to, for example, | |
2432b92d | 88 | \rtfsp\helpref{GetOpenCommand}{wxfiletypegetopencommand} like this: |
b13d92d1 VZ |
89 | |
90 | \begin{verbatim} | |
91 | wxString command; | |
92 | if ( filetype->GetOpenCommand(&command, | |
93 | MailMessageParamaters("foo.txt", "text/plain")) ) | |
94 | { | |
95 | // the full command for opening the text documents is in 'command' | |
96 | // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix) | |
97 | } | |
98 | else | |
99 | { | |
100 | // we don't know how to handle such files... | |
101 | } | |
b13d92d1 VZ |
102 | \end{verbatim} |
103 | ||
104 | {\bf Windows:} As only the file name is used by the program associated with the | |
105 | given extension anyhow (but no other message parameters), there is no need to | |
106 | ever derive from MessageParameters class for a Windows-only program. | |
107 | ||
108 | \membersection{wxFileType::wxFileType}\label{wxfiletypewxfiletype} | |
2432b92d | 109 | |
b13d92d1 VZ |
110 | \func{}{wxFileType}{\void} |
111 | ||
112 | The default constructor is private because you should never create objects of | |
2432b92d | 113 | this type: they are only returned by \helpref{wxMimeTypesManager}{wxmimetypesmanager} methods. |
b13d92d1 VZ |
114 | |
115 | \membersection{wxFileType::\destruct{wxFileType}}\label{wxfiletypedtor} | |
2432b92d JS |
116 | |
117 | \func{}{\destruct{wxFileType}}{\void} | |
b13d92d1 VZ |
118 | |
119 | The destructor of this class is not virtual, so it should not be derived from. | |
120 | ||
121 | \membersection{wxFileType::GetMimeType}\label{wxfiletypegetmimetype} | |
2432b92d JS |
122 | |
123 | \func{bool}{GetMimeType}{\param{wxString*}{ mimeType}} | |
b13d92d1 VZ |
124 | |
125 | If the function returns TRUE, the string pointed to by {\it mimeType} is filled | |
126 | with full MIME type specification for this file type: for example, "text/plain". | |
127 | ||
4d2976ad VS |
128 | \membersection{wxFileType::GetMimeTypes}\label{wxfiletypegetmimetypes} |
129 | ||
130 | \func{bool}{GetMimeType}{\param{wxArrayString&}{ mimeTypes}} | |
131 | ||
132 | Same as \helpref{GetMimeType}{wxfiletypegetmimetype} but returns array of MIME | |
133 | types. This array will contain only one item in most cases but sometimes, | |
134 | notably under Unix with KDE, may contain more MIME types. This happens when | |
135 | one file extension is mapped to different MIME types by KDE, mailcap and | |
136 | mime.types. | |
137 | ||
b13d92d1 | 138 | \membersection{wxFileType::GetExtensions}\label{wxfiletypegetextensions} |
2432b92d JS |
139 | |
140 | \func{bool}{GetExtensions}{\param{wxArrayString\&}{ extensions}} | |
b13d92d1 VZ |
141 | |
142 | If the function returns TRUE, the array {\it extensions} is filled | |
143 | with all extensions associated with this file type: for example, it may | |
144 | contain the following two elements for the MIME type "text/html" (notice the | |
145 | absence of the leading dot): "html" and "htm". | |
146 | ||
147 | {\bf Windows:} This function is currently not implemented: there is no | |
148 | (efficient) way to retrieve associated extensions from the given MIME type on | |
149 | this platform, so it will only return TRUE if the wxFileType object was created | |
150 | by \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} | |
151 | function in the first place. | |
152 | ||
153 | \membersection{wxFileType::GetIcon}\label{wxfiletypegeticon} | |
2432b92d JS |
154 | |
155 | \func{bool}{GetIcon}{\param{wxIcon*}{ icon}} | |
b13d92d1 VZ |
156 | |
157 | If the function returns TRUE, the icon associated with this file type will be | |
158 | created and assigned to the {\it icon} parameter. | |
159 | ||
cdf339c9 VS |
160 | {\bf Unix:} MIME manager gathers information about icons from GNOME |
161 | and KDE settings and thus GetIcon's success depends on availability | |
162 | of these desktop environments. | |
b13d92d1 VZ |
163 | |
164 | \membersection{wxFileType::GetDescription}\label{wxfiletypegetdescription} | |
2432b92d JS |
165 | |
166 | \func{bool}{GetDescription}{\param{wxString*}{ desc}} | |
b13d92d1 VZ |
167 | |
168 | If the function returns TRUE, the string pointed to by {\it desc} is filled | |
169 | with a brief description for this file type: for example, "text document" for | |
170 | the "text/plain" MIME type. | |
171 | ||
172 | \membersection{wxFileType::GetOpenCommand}\label{wxfiletypegetopencommand} | |
2432b92d JS |
173 | |
174 | \func{bool}{GetOpenCommand}{\param{wxString*}{ command}, \param{MessageParameters\&}{ params}} | |
b13d92d1 VZ |
175 | |
176 | If the function returns TRUE, the string pointed to by {\it command} is filled | |
177 | with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in | |
178 | order to open the file of the given type. The name of the file is | |
179 | retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class. | |
180 | ||
181 | \membersection{wxFileType::GetPrintCommand}\label{wxfiletypegetprintcommand} | |
2432b92d JS |
182 | |
183 | \func{bool}{GetPrintCommand}{\param{wxString*}{ command},\param{MessageParameters\&}{ params}} | |
b13d92d1 VZ |
184 | |
185 | If the function returns TRUE, the string pointed to by {\it command} is filled | |
186 | with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in | |
187 | order to print the file of the given type. The name of the file is | |
188 | retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class. | |
189 | ||
190 | \membersection{wxFileType::ExpandCommand}\label{wxfiletypeexpandcommand} | |
2432b92d JS |
191 | |
192 | \func{static wxString}{ExpandCommand}{\param{const wxString\&}{ command}, \param{MessageParameters\&}{ params}} | |
b13d92d1 VZ |
193 | |
194 | This function is primarly intended for GetOpenCommand and GetPrintCommand | |
195 | usage but may be also used by the application directly if, for example, you want | |
196 | to use some non default command to open the file. | |
197 | ||
198 | The function replaces all occurences of | |
2432b92d | 199 | |
b13d92d1 VZ |
200 | \twocolwidtha{7cm} |
201 | \begin{twocollist}\itemsep=0pt | |
202 | \twocolitem{format specificator}{with} | |
203 | \twocolitem{\%s}{the full file name} | |
204 | \twocolitem{\%t}{the MIME type} | |
205 | \twocolitem{\%\{param\}}{the value of the parameter {\it param}} | |
206 | \end{twocollist} | |
2432b92d | 207 | |
b13d92d1 VZ |
208 | using the MessageParameters object you pass to it. |
209 | ||
210 | If there is no '\%s' in the command string (and the string is not empty), it is | |
211 | assumed that the command reads the data on stdin and so the effect is the same | |
212 | as "< \%s" were appended to the string. | |
213 | ||
214 | Unlike all other functions of this class, there is no error return for this | |
215 | function. | |
2432b92d | 216 |