MIME classes with docs (not yet added to the makefiles)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1321 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -81,6 +81,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$
 \input file.tex
 \input filedlg.tex
 \input filehist.tex
+\input filetype.tex
 \input focusevt.tex
 \input font.tex
 \input fontdlg.tex
@@ -113,13 +114,14 @@ $$\image{14cm;0cm}{wxclass.ps}$$
 \input menuitem.tex
 \input menuevt.tex
 \input memorydc.tex
-\input msgdlg.tex
 \input metafile.tex
+\input mimetype.tex
 \input minifram.tex
 \input module.tex
 \input mouseevt.tex
 \input moveevt.tex
 \input mltchdlg.tex
+\input msgdlg.tex
 \input mutex.tex
 \input mutexlck.tex
 \input node.tex

docs/latex/wx/filetype.tex

@@ -0,0 +1,194 @@
+\section{\class{wxFileType}}\label{wxfiletype}
+
+This class holds information about a given "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
+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
+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
+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.
+
+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}
+
+#include <wx/mimetype.h>
+
+\wxheading{Derived from}
+
+No base class.
+
+\wxheading{See also}
+
+\helpref{wxMimeTypesManager}{wxmimetypesmanager}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{MessageParameters class}{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
+parameters are found in the message headers ("Content-XXX"). At the very least,
+they must specify the MIME type and the version of MIME used, but almost always
+they provide additional information about the message such as the original file
+name or the charset (for the text documents).
+
+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
+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()
+function, for example:
+
+\begin{verbatim}
+// provide the message parameters for the MIME type manager
+class MailMessageParamaters : public wxFileType::MessageParameters
+{
+public:
+   MailMessageParamaters(const wxString& filename,
+                         const wxString& mimetype)
+      : wxFileType::MessageParameters(filename, mimetype)
+   {
+   }
+
+   virtual wxString GetParamValue(const wxString& name) const
+   {
+       // parameter names are not case-sensitive
+       if ( name.CmpNoCase("charset") == 0 )
+           return "US-ASCII";
+       else
+           return wxFileType::MessageParameters::GetParamValue(name);
+   }
+};
+\end{verbatim}
+
+Now you only need to create an object of this class and pass it to, for example,
+\helpref{GetOpenCommand}{wxfiletypegetopencommand} like this:
+
+\begin{verbatim}
+wxString command;
+if ( filetype->GetOpenCommand(&command,
+                              MailMessageParamaters("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)
+}
+else
+{
+    // we don't know how to handle such files...
+}
+
+\end{verbatim}
+
+{\bf Windows:} As only the file name is used by the program associated with the
+given extension anyhow (but no other message parameters), there is no need to
+ever derive from MessageParameters class for a Windows-only program.
+
+\membersection{wxFileType::wxFileType}\label{wxfiletypewxfiletype}
+\func{}{wxFileType}{\void}
+
+The default constructor is private because you should never create objects of
+this type: they are only returned by 
+\helpref{wxMimeTypesManager}{wxmimetypesmanager} methods.
+
+\membersection{wxFileType::\destruct{wxFileType}}\label{wxfiletypedtor}
+\func{}{\destruct{wxFileType}{\void}
+
+The destructor of this class is not virtual, so it should not be derived from.
+
+\membersection{wxFileType::GetMimeType}\label{wxfiletypegetmimetype}
+\func{bool}{GetMimeType}{\param{wxString *}{mimeType}}
+
+If the function returns 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::GetExtensions}\label{wxfiletypegetextensions}
+\func{bool}{GetExtensions}{\param{wxArrayString \&}{extensions}}
+
+If the function returns 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
+by \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} 
+function in the first place.
+
+\membersection{wxFileType::GetIcon}\label{wxfiletypegeticon}
+\func{bool}{GetIcon}{\param{wxIcon *}{icon}}
+
+If the function returns TRUE, the icon associated with this file type will be
+created and assigned to the {\it icon} parameter.
+
+{\bf Unix:} This function always returns FALSE under Unix.
+
+\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
+with a brief description for this file type: for example, "text document" for
+the "text/plain" MIME type.
+
+\membersection{wxFileType::GetOpenCommand}\label{wxfiletypegetopencommand}
+\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.
+
+\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
+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.
+
+\membersection{wxFileType::ExpandCommand}\label{wxfiletypeexpandcommand}
+\func{static wxString}{ExpandCommand}{\param{const wxString \&}{command},\param{MessageParameters \&}{params}}
+
+This function is primarly 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.
+
+The function replaces all occurences of
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{format specificator}{with}
+\twocolitem{\%s}{the full file name}
+\twocolitem{\%t}{the MIME type}
+\twocolitem{\%\{param\}}{the value of the parameter {\it param}}
+\end{twocollist}
+using the MessageParameters object you pass to it.
+
+If there is no '\%s' in the command string (and the string is not empty), it is
+assumed that the command reads the data on stdin and so the effect is the same
+as "< \%s" were appended to the string.
+
+Unlike all other functions of this class, there is no error return for this
+function.

docs/latex/wx/mimetype.tex

@@ -0,0 +1,111 @@
+\section{\class{wxMimeTypesManager}}\label{wxmimetypesmanager}
+
+This class allows the application to retrieve the information about all known
+MIME types from a system-specific location and the filename extensions to the
+MIME types and vice versa. After initialization the functions
+\helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype} 
+and \helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} 
+may be called: they will return a \helpref{wxFileType}{wxfiletype} object which
+may be further queried for file description, icon and other attributes.
+
+{\bf Windows:} MIME type information is stored in the registry and no additional
+initialization is needed.
+
+{\bf Unix:} MIME type information is stored in the files mailcap and mime.types
+(system-wide) and .mailcap and .mime.types in the current user's home directory:
+all of these files are searched for and loaded if found by default. However,
+additional functions 
+\helpref{wxMimeTypesManager::ReadMailcap}{wxmimetypesmanagerreadmailcap} and
+\helpref{wxMimeTypesManager::ReadMimeTypes}{wxmimetypesmanagerreadmimetypes} are
+provided to load additional files.
+
+NB: Currently, wxMimeTypesManager is limited to reading MIME type information
+but it will support modifying it as well in the future versions.
+
+\wxheading{Required headers}
+
+#include <wx/mimetype.h>
+
+\wxheading{Derived from}
+
+No base class.
+
+\wxheading{See also}
+
+\helpref{wxFileType}{wxfiletype}
+
+\latexignore{\rtfignore{\wxheading{Function groups}}}
+
+\membersection{Constructor and destructor}
+
+NB: You won't normally need to use more than one wxMimeTypesManager object in a
+program.
+
+\helpref{wxMimeTypesManager}{wxmimetypesmanagerctor}\\
+\helpref{\destruct{wxMimeTypesManager}}{wxmimetypesmanagerdtor}
+
+\membersection{Query database}
+
+These functions are the heart of this class: they allow to find a 
+\helpref{file type}{wxfiletype} object from either file extension or MIME type.
+If the function is successful, it returns a pointer to the wxFileType object
+which {\bf must be deleted by the caller}, otherwise NULL will be returned.
+
+\helpref{GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}\\
+\helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
+
+\membersection{Initialization functions}
+
+{\bf Unix:} These functions may be used to load additional (except for the
+default ones which are loaded automatically) files containing MIME
+information in either mailcap(5) or mime.types(5) format.
+
+\helpref{ReadMailcap}{wxmimetypesmanagerreadmailcap}\\
+\helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}
+
+%%%%% MEMBERS HERE %%%%%
+\helponly{\insertatlevel{2}{
+
+\wxheading{Members}
+
+}}
+
+\membersection{wxMimeTypesManager::wxMimeTypesManager}\label{wxmimetypesmanagerctor}
+\func{}{wxMimeTypesManager}{\void}
+
+Constructor puts the object in the "working" state, no additional initialization
+are needed - but \helpref{ReadXXX}{wxmimetypesmanagerinit} may be used to load
+additional mailcap/mime.types files.
+
+\membersection{wxMimeTypesManager::\destruct{wxMimeTypesManager}}\label{wxmimetypesmanagerdtor}
+\func{}{\destruct{wxMimeTypesManager}{\void}
+
+Destructor is not virtual, so this class should not be derived from.
+
+\membersection{wxMimeTypesManager::GetFileTypeFromExtension}\label{wxmimetypesmanagergetfiletypefromextension}
+\func{wxFileType *}{GetFileTypeFromExtension}{\param{const wxString \&}{extension}}
+
+Gather information about the files with given extension and return the
+corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the extension
+is unknown.
+
+\membersection{wxMimeTypesManager::GetFileTypeFromMimeType}\label{wxmimetypesmanagergetfiletypefrommimetype}
+\func{wxFileType *}{GetFileTypeFromMimeType}{\param{const wxString \&}{mimeType}}
+
+Gather information about the files with given MIME type and return the
+corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the MIME type
+is unknown.
+
+\membersection{wxMimeTypesManager::ReadMailcap}\label{wxmimetypesmanagerreadmailcap}
+\func{\void}{ReadMailcap}{\param{const wxString \&}{filename}}
+
+Load additional file containing information about MIME types and associated
+information in mailcap format. See metamail(1) and mailcap(5) for more
+information.
+
+\membersection{wxMimeTypesManager::ReadMimeTypes}\label{wxmimetypesmanagerreadmimetypes}
+\func{\void}{ReadMimeTypes}{\param{const wxString \&}{filename}}
+
+Load additional file containing information about MIME types and associated
+information in mime.types file format. See metamail(1) and mailcap(5) for more
+information.

include/wx/mimetype.h

@@ -0,0 +1,145 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/mimetype.h
+// Purpose:     classes and functions to manage MIME types
+// Author:      Vadim Zeitlin
+// Modified by:
+// Created:     23.09.98
+// RCS-ID:      $Id$
+// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
+// Licence:     wxWindows license (part of wxExtra library)
+/////////////////////////////////////////////////////////////////////////////
+
+#ifndef   _MIMETYPE_H
+#define   _MIMETYPE_H
+
+// fwd decls
+class wxIcon;
+class wxFileTypeImpl;
+class wxMimeTypesManagerImpl;
+
+// the things we really need
+#include "wx/string.h"
+
+// This class holds information about a given "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 many different ways and depending
+// on how it was created some fields may be unknown so the return value of all
+// the accessors *must* be checked!
+class wxFileType
+{
+friend wxMimeTypesManagerImpl;  // it has access to m_impl
+
+public:
+    // An object of this class must be passed to Get{Open|Print}Command. The
+    // default implementation is trivial and doesn't know anything at all about
+    // parameters, only filename and MIME type are used (so it's probably ok for
+    // Windows where %{param} is not used anyhow)
+    class MessageParameters
+    {
+    public:
+        // ctors
+        MessageParameters() { }
+        MessageParameters(const wxString& filename, const wxString& mimetype)
+            : m_filename(filename), m_mimetype(mimetype) { }
+
+        // accessors (called by GetOpenCommand)
+            // filename
+        const wxString& GetFileName() const { return m_filename; }
+            // mime type
+        const wxString& GetMimeType() const { return m_mimetype; }
+
+        // override this function in derived class
+        virtual wxString GetParamValue(const wxString& paramName) const
+            { return ""; }
+
+        // virtual dtor as in any base class
+        virtual ~MessageParameters() { }
+
+    protected:
+        wxString m_filename, m_mimetype;
+    };
+
+    // accessors: all of them return true if the corresponding information
+    // could be retrieved/found, false otherwise (and in this case all [out]
+    // parameters are unchanged)
+        // return the MIME type for this file type
+    bool GetMimeType(wxString *mimeType) const;
+        // fill passed in array with all extensions associated with this file
+        // type
+    bool GetExtensions(wxArrayString& extensions);
+        // get the icon corresponding to this file type
+    bool GetIcon(wxIcon *icon) const;
+        // get a brief file type description ("*.txt" => "text document")
+    bool GetDescription(wxString *desc) const;
+
+    // get the command to be used to open/print the given file.
+        // get the command to execute the file of given type
+    bool GetOpenCommand(wxString *openCmd,
+                        const MessageParameters& params) const;
+        // get the command to print the file of given type
+    bool GetPrintCommand(wxString *printCmd,
+                         const MessageParameters& params) const;
+
+    // operations
+        // expand a string in the format of GetOpenCommand (which may contain
+        // '%s' and '%t' format specificators for the file name and mime type
+        // and %{param} constructions).
+    static wxString ExpandCommand(const wxString& command,
+                                  const MessageParameters& params);
+
+    // dtor (not virtual, shouldn't be derived from)
+    ~wxFileType();
+
+private:
+    // default ctor is private because the user code never creates us
+    wxFileType();
+
+    // no copy ctor/assignment operator
+    wxFileType(const wxFileType&);
+    wxFileType& operator=(const wxFileType&);
+
+    wxFileTypeImpl *m_impl;
+};
+
+// This class accesses the information about all known MIME types and allows
+// the application to retrieve information (including how to handle data of
+// given type) about them.
+//
+// NB: currently it doesn't support modifying MIME database (read-only access).
+class wxMimeTypesManager
+{
+public:
+    // ctor
+    wxMimeTypesManager();
+
+    // Database lookup: all functions return a pointer to wxFileType object
+    // whose methods may be used to query it for the information you're
+    // interested in. If the return value is !NULL, caller is responsible for
+    // deleting it.
+        // get file type from file extension
+    wxFileType *GetFileTypeFromExtension(const wxString& ext);
+        // get file type from MIME type (in format <category>/<format>)
+    wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
+
+    // other operations
+        // read in additional file (the standard ones are read automatically)
+        // in mailcap format (see mimetype.cpp for description)
+    void ReadMailcap(const wxString& filename);
+        // read in additional file in mime.types format
+    void ReadMimeTypes(const wxString& filename);
+
+    // dtor (not virtual, shouldn't be derived from)
+    ~wxMimeTypesManager();
+
+private:
+    // no copy ctor/assignment operator
+    wxMimeTypesManager(const wxMimeTypesManager&);
+    wxMimeTypesManager& operator=(const wxMimeTypesManager&);
+
+    wxMimeTypesManagerImpl *m_impl;
+};
+
+#endif  //_MIMETYPE_H
+
+/* vi: set cin tw=80 ts=4 sw=4: */