]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/latex/wx/filetype.tex
Added periods
[wxWidgets.git] / docs / latex / wx / filetype.tex
index f4d52516a7e8718f12e4184554bd77a2bdd75a7c..58cc65b4039a8578d65689d761b572bd032a902d 100644 (file)
@@ -1,26 +1,26 @@
 \section{\class{wxFileType}}\label{wxfiletype}
 
-This class holds information about a given "file type". File type is the same as
+This class holds information about a given {\it file type}. File type is the same as
 MIME type under Unix, but under Windows it corresponds more to an extension than
 to MIME type (in fact, several extensions may correspond to a file type). This
 object may be created in several different ways: the program might know the file
 extension and wish to find out the corresponding MIME type or, conversely, it
 might want to find the right extension for the file to which it writes the
 contents of given MIME type. Depending on how it was created some fields may be
-unknown so the return value of all the accessors {\bf must} be checked: FALSE
+unknown so the return value of all the accessors {\bf must} be checked: {\tt false}
 will be returned if the corresponding information couldn't be found.
 
 The objects of this class are never created by the application code but are
 returned by \helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype} and 
 \helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} methods.
-But it's your responsability to delete the returned pointer when you're done
+But it is your responsibility to delete the returned pointer when you're done
 with it!
 
 % TODO describe MIME types better than this...
-A brief remainder about what the MIME types are (see the RFC 1341 for more
-information): basicly, it is just a pair category/type (for example,
-"text/plain") where the category is a basic indication of what a file is
-(examples of categories are "application", "image", "text", "binary"...) and
+A brief reminder about what the MIME types are (see the RFC 1341 for more
+information): basically, it is just a pair category/type (for example,
+"text/plain") where the category is a basic indication of what a file is.
+Examples of categories are "application", "image", "text", "binary", and
 type is a precise definition of the document format: "plain" in the example
 above means just ASCII text without any formatting, while "text/html" is the
 HTML document source.
@@ -29,13 +29,17 @@ A MIME type may have one or more associated extensions: "text/plain" will
 typically correspond to the extension ".txt", but may as well be associated with
 ".ini" or ".conf".
 
-\wxheading{Required headers}
+\wxheading{Derived from}
+
+None
+
+\wxheading{Include files}
 
 <wx/mimetype.h>
 
-\wxheading{Derived from}
+\wxheading{Library}
 
-No base class.
+\helpref{wxBase}{librarieslist}
 
 \wxheading{See also}
 
@@ -43,7 +47,7 @@ No base class.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{MessageParameters class}{wxfiletypemessageparameters}
+\membersection{MessageParameters class}\label{wxfiletypemessageparameters}
 
 One of the most common usages of MIME is to encode an e-mail message. The MIME
 type of the encoded message is an example of a {\it message parameter}. These
@@ -56,7 +60,7 @@ These parameters may be useful to the program used to open, edit, view or print
 the message, so, for example, an e-mail client program will have to pass them to
 this program. Because wxFileType itself can not know about these parameters,
 it uses MessageParameters class to query them. The default implementation only
-requiers the caller to provide the file name (always used by the program to be
+requires the caller to provide the file name (always used by the program to be
 called - it must know which file to open) and the MIME type and supposes that
 there are no other parameters. If you wish to supply additional parameters, you
 must derive your own class from MessageParameters and override GetParamValue()
@@ -90,7 +94,7 @@ Now you only need to create an object of this class and pass it to, for example,
 \begin{verbatim}
 wxString command;
 if ( filetype->GetOpenCommand(&command,
-                              MailMessageParamaters("foo.txt", "text/plain")) )
+                              MailMessageParameters("foo.txt", "text/plain")) )
 {
     // the full command for opening the text documents is in 'command'
     // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
@@ -122,38 +126,56 @@ The destructor of this class is not virtual, so it should not be derived from.
 
 \func{bool}{GetMimeType}{\param{wxString*}{ mimeType}}
 
-If the function returns TRUE, the string pointed to by {\it mimeType} is filled
+If the function returns {\tt true}, the string pointed to by {\it mimeType} is filled
 with full MIME type specification for this file type: for example, "text/plain".
 
+\membersection{wxFileType::GetMimeTypes}\label{wxfiletypegetmimetypes}
+
+\func{bool}{GetMimeType}{\param{wxArrayString\&}{ mimeTypes}}
+
+Same as \helpref{GetMimeType}{wxfiletypegetmimetype} but returns array of MIME
+types. This array will contain only one item in most cases but sometimes,
+notably under Unix with KDE, may contain more MIME types. This happens when
+one file extension is mapped to different MIME types by KDE, mailcap and
+mime.types.
+
 \membersection{wxFileType::GetExtensions}\label{wxfiletypegetextensions}
 
 \func{bool}{GetExtensions}{\param{wxArrayString\&}{ extensions}}
 
-If the function returns TRUE, the array {\it extensions} is filled
+If the function returns {\tt true}, the array {\it extensions} is filled
 with all extensions associated with this file type: for example, it may
 contain the following two elements for the MIME type "text/html" (notice the
 absence of the leading dot): "html" and "htm".
 
 {\bf Windows:} This function is currently not implemented: there is no
 (efficient) way to retrieve associated extensions from the given MIME type on
-this platform, so it will only return TRUE if the wxFileType object was created
+this platform, so it will only return {\tt true} if the wxFileType object was created
 by \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} 
 function in the first place.
 
 \membersection{wxFileType::GetIcon}\label{wxfiletypegeticon}
 
-\func{bool}{GetIcon}{\param{wxIcon*}{ icon}}
+\func{bool}{GetIcon}{\param{wxIconLocation *}{ iconLoc}}
 
-If the function returns TRUE, the icon associated with this file type will be
-created and assigned to the {\it icon} parameter.
+If the function returns {\tt true}, the {\tt iconLoc} is filled with the
+location of the icon for this MIME type. A \helpref{wxIcon}{wxicon} may be
+created from {\it iconLoc} later.
 
-{\bf Unix:} This function always returns FALSE under Unix.
+{\bf Windows:} The function returns the icon shown by Explorer for the files of
+the specified type.
+
+{\bf Mac:} This function is not implemented and always returns {\tt false}.
+
+{\bf Unix:} MIME manager gathers information about icons from GNOME
+and KDE settings and thus GetIcon's success depends on availability
+of these desktop environments.
 
 \membersection{wxFileType::GetDescription}\label{wxfiletypegetdescription}
 
 \func{bool}{GetDescription}{\param{wxString*}{ desc}}
 
-If the function returns TRUE, the string pointed to by {\it desc} is filled
+If the function returns {\tt true}, the string pointed to by {\it desc} is filled
 with a brief description for this file type: for example, "text document" for
 the "text/plain" MIME type.
 
@@ -161,16 +183,25 @@ the "text/plain" MIME type.
 
 \func{bool}{GetOpenCommand}{\param{wxString*}{ command}, \param{MessageParameters\&}{ params}}
 
-If the function returns TRUE, the string pointed to by {\it command} is filled
-with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
-order to open the file of the given type. The name of the file is
-retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
+\func{wxString}{GetOpenCommand}{\param{const wxString\&}{ filename}}
+
+With the first version of this method, if the {\tt true} is returned, the
+string pointed to by {\it command} is filled with the command which must be
+executed (see \helpref{wxExecute}{wxexecute}) in order to open the file of the
+given type. In this case, the name of the file as well as any other parameters
+is retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} 
+class.
+
+In the second case, only the filename is specified and the command to be used
+to open this kind of file is returned directly. An empty string is returned to
+indicate that an error occurred (typically meaning that there is no standard way
+to open this kind of files).
 
 \membersection{wxFileType::GetPrintCommand}\label{wxfiletypegetprintcommand}
 
 \func{bool}{GetPrintCommand}{\param{wxString*}{ command},\param{MessageParameters\&}{ params}}
 
-If the function returns TRUE, the string pointed to by {\it command} is filled
+If the function returns {\tt true}, the string pointed to by {\it command} is filled
 with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
 order to print the file of the given type. The name of the file is
 retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
@@ -179,15 +210,15 @@ retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
 
 \func{static wxString}{ExpandCommand}{\param{const wxString\&}{ command}, \param{MessageParameters\&}{ params}}
 
-This function is primarly intended for GetOpenCommand and GetPrintCommand
+This function is primarily intended for GetOpenCommand and GetPrintCommand
 usage but may be also used by the application directly if, for example, you want
-to use some non default command to open the file.
+to use some non-default command to open the file.
 
-The function replaces all occurences of
+The function replaces all occurrences of
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
-\twocolitem{format specificator}{with}
+\twocolitem{format specification}{with}
 \twocolitem{\%s}{the full file name}
 \twocolitem{\%t}{the MIME type}
 \twocolitem{\%\{param\}}{the value of the parameter {\it param}}