1 \section{\class{wxFileType
}}\label{wxfiletype
}
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: FALSE
11 will be returned if the corresponding information couldn't be found.
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 responsibility to delete the returned pointer when you're done
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
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
32 \wxheading{Derived from
}
36 \wxheading{Include files
}
42 \helpref{wxMimeTypesManager
}{wxmimetypesmanager
}
44 \latexignore{\rtfignore{\wxheading{Members
}}}
46 \membersection{MessageParameters class
}\label{wxfiletypemessageparameters
}
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).
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:
66 // provide the message parameters for the MIME type manager
67 class MailMessageParameters : public wxFileType::MessageParameters
70 MailMessageParameters(const wxString& filename,
71 const wxString& mimetype)
72 : wxFileType::MessageParameters(filename, mimetype)
76 virtual wxString GetParamValue(const wxString& name) const
78 // parameter names are not case-sensitive
79 if ( name.CmpNoCase("charset") ==
0 )
82 return wxFileType::MessageParameters::GetParamValue(name);
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:
92 if ( filetype->GetOpenCommand(&command,
93 MailMessageParamaters("foo.txt", "text/plain")) )
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)
100 // we don't know how to handle such files...
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.
108 \membersection{wxFileType::wxFileType
}\label{wxfiletypewxfiletype
}
110 \func{}{wxFileType
}{\void}
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.
115 \membersection{wxFileType::
\destruct{wxFileType
}}\label{wxfiletypedtor
}
117 \func{}{\destruct{wxFileType
}}{\void}
119 The destructor of this class is not virtual, so it should not be derived from.
121 \membersection{wxFileType::GetMimeType
}\label{wxfiletypegetmimetype
}
123 \func{bool
}{GetMimeType
}{\param{wxString*
}{ mimeType
}}
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".
128 \membersection{wxFileType::GetMimeTypes
}\label{wxfiletypegetmimetypes
}
130 \func{bool
}{GetMimeType
}{\param{wxArrayString\&
}{ mimeTypes
}}
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
138 \membersection{wxFileType::GetExtensions
}\label{wxfiletypegetextensions
}
140 \func{bool
}{GetExtensions
}{\param{wxArrayString\&
}{ extensions
}}
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".
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.
153 \membersection{wxFileType::GetIcon
}\label{wxfiletypegeticon
}
155 \func{bool
}{GetIcon
}{\param{wxIcon*
}{ icon
}}
157 If the function returns TRUE, the icon associated with this file type will be
158 created and assigned to the
{\it icon
} parameter.
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.
164 \membersection{wxFileType::GetDescription
}\label{wxfiletypegetdescription
}
166 \func{bool
}{GetDescription
}{\param{wxString*
}{ desc
}}
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.
172 \membersection{wxFileType::GetOpenCommand
}\label{wxfiletypegetopencommand
}
174 \func{bool
}{GetOpenCommand
}{\param{wxString*
}{ command
},
\param{MessageParameters\&
}{ params
}}
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.
181 \membersection{wxFileType::GetPrintCommand
}\label{wxfiletypegetprintcommand
}
183 \func{bool
}{GetPrintCommand
}{\param{wxString*
}{ command
},
\param{MessageParameters\&
}{ params
}}
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.
190 \membersection{wxFileType::ExpandCommand
}\label{wxfiletypeexpandcommand
}
192 \func{static wxString
}{ExpandCommand
}{\param{const wxString\&
}{ command
},
\param{MessageParameters\&
}{ params
}}
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.
198 The function replaces all occurences of
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
}}
208 using the MessageParameters object you pass to it.
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.
214 Unlike all other functions of this class, there is no error return for this