docs/latex/wx/filetype.tex

   1 \section{\class{wxFileType}}\label{wxfiletype}
   2
   3 This class holds information about a given "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: 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's your responsability to delete the returned pointer when you're done
  17 with it!
  18
  19 % TODO describe MIME types better than this...
  20 A brief remainder about what the MIME types are (see the RFC 1341 for more
  21 information): basicly, 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{Required headers}
  33
  34 <wx/mimetype.h>
  35
  36 \wxheading{Derived from}
  37
  38 No base class.
  39
  40 \wxheading{See also}
  41
  42 \helpref{wxMimeTypesManager}{wxmimetypesmanager}
  43
  44 \latexignore{\rtfignore{\wxheading{Members}}}
  45
  46 \membersection{MessageParameters class}\label{wxfiletypemessageparameters}
  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
  67 class MailMessageParameters : public wxFileType::MessageParameters
  68 {
  69 public:
  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
  87 Now 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}
  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 }
 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}
 109
 110 \func{}{wxFileType}{\void}
 111
 112 The default constructor is private because you should never create objects of
 113 this 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
 119 The 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
 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
 128 \membersection{wxFileType::GetExtensions}\label{wxfiletypegetextensions}
 129
 130 \func{bool}{GetExtensions}{\param{wxArrayString\&}{ extensions}}
 131
 132 If the function returns TRUE, the array {\it extensions} is filled
 133 with all extensions associated with this file type: for example, it may
 134 contain the following two elements for the MIME type "text/html" (notice the
 135 absence of the leading dot): "html" and "htm".
 136
 137 {\bf Windows:} This function is currently not implemented: there is no
 138 (efficient) way to retrieve associated extensions from the given MIME type on
 139 this platform, so it will only return TRUE if the wxFileType object was created
 140 by \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
 141 function in the first place.
 142
 143 \membersection{wxFileType::GetIcon}\label{wxfiletypegeticon}
 144
 145 \func{bool}{GetIcon}{\param{wxIcon*}{ icon}}
 146
 147 If the function returns TRUE, the icon associated with this file type will be
 148 created and assigned to the {\it icon} parameter.
 149
 150 {\bf Unix:} This function always returns FALSE under Unix.
 151
 152 \membersection{wxFileType::GetDescription}\label{wxfiletypegetdescription}
 153
 154 \func{bool}{GetDescription}{\param{wxString*}{ desc}}
 155
 156 If the function returns TRUE, the string pointed to by {\it desc} is filled
 157 with a brief description for this file type: for example, "text document" for
 158 the "text/plain" MIME type.
 159
 160 \membersection{wxFileType::GetOpenCommand}\label{wxfiletypegetopencommand}
 161
 162 \func{bool}{GetOpenCommand}{\param{wxString*}{ command}, \param{MessageParameters\&}{ params}}
 163
 164 If the function returns TRUE, the string pointed to by {\it command} is filled
 165 with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
 166 order to open the file of the given type. The name of the file is
 167 retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
 168
 169 \membersection{wxFileType::GetPrintCommand}\label{wxfiletypegetprintcommand}
 170
 171 \func{bool}{GetPrintCommand}{\param{wxString*}{ command},\param{MessageParameters\&}{ params}}
 172
 173 If the function returns TRUE, the string pointed to by {\it command} is filled
 174 with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
 175 order to print the file of the given type. The name of the file is
 176 retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
 177
 178 \membersection{wxFileType::ExpandCommand}\label{wxfiletypeexpandcommand}
 179
 180 \func{static wxString}{ExpandCommand}{\param{const wxString\&}{ command}, \param{MessageParameters\&}{ params}}
 181
 182 This function is primarly intended for GetOpenCommand and GetPrintCommand
 183 usage but may be also used by the application directly if, for example, you want
 184 to use some non default command to open the file.
 185
 186 The function replaces all occurences of
 187
 188 \twocolwidtha{7cm}
 189 \begin{twocollist}\itemsep=0pt
 190 \twocolitem{format specificator}{with}
 191 \twocolitem{\%s}{the full file name}
 192 \twocolitem{\%t}{the MIME type}
 193 \twocolitem{\%\{param\}}{the value of the parameter {\it param}}
 194 \end{twocollist}
 195
 196 using the MessageParameters object you pass to it.
 197
 198 If there is no '\%s' in the command string (and the string is not empty), it is
 199 assumed that the command reads the data on stdin and so the effect is the same
 200 as "< \%s" were appended to the string.
 201
 202 Unlike all other functions of this class, there is no error return for this
 203 function.
 204