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