docs/latex/wx/filetype.tex

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