Make the CreateTool factories be public so they can be used from application code

[wxWidgets.git] / interface / wx / mimetype.h

diff --git a/interface/wx/mimetype.h b/interface/wx/mimetype.h
index 3e753b05f0cf9b526c8ddb0ba8579c68af23eb0c..d4937b13430b2f898d3c933d06ef7cd782c89a20 100644 (file)
--- a/interface/wx/mimetype.h
+++ b/interface/wx/mimetype.h
@@ -3,40 +3,51 @@
 // Purpose:     interface of wxMimeTypesManager
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxMimeTypesManager
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxMimeTypesManager
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxMimeTypesManager

-    @wxheader{mimetype.h}

 
 

-    This class allows the application to retrieve the information about all known
+    This class allows the application to retrieve informations about all known

     MIME types from a system-specific location and the filename extensions to the
     MIME types from a system-specific location and the filename extensions to the

-    MIME types and vice versa. After initialization the functions
-    wxMimeTypesManager::GetFileTypeFromMimeType
-    and wxMimeTypesManager::GetFileTypeFromExtension
-    may be called: they will return a wxFileType object which
-    may be further queried for file description, icon and other attributes.
+    MIME types and vice versa. 
+    
+    MIME stands for "Multipurpose Internet Mail Extensions" and was originally
+    used in mail protocols. It's standardized by several RFCs.
+    
+    Under Windows, the MIME type information is queried from registry.
+    Under Linux and Unix, it is queried from the XDG data directories.

 
 

-    @b Windows: MIME type information is stored in the registry and no additional
-    initialization is needed.
+    Currently, wxMimeTypesManager is limited to @e reading MIME type information.

 
 

-    @b 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
-    wxMimeTypesManager::ReadMailcap and
-    wxMimeTypesManager::ReadMimeTypes are
-    provided to load additional files.
+    The application should not construct its own manager: it should use the
+    object pointer ::wxTheMimeTypesManager.
+    The functions GetFileTypeFromMimeType() and GetFileTypeFromExtension()
+    return a wxFileType object which may be further queried for file description, 
+    icon and other attributes.

 
 

-    If GNOME or KDE desktop environment is installed, then wxMimeTypesManager
-    gathers MIME information from respective files (e.g. .kdelnk files under KDE).
+    @section mimetypemanager_helpers Helper functions

 
 

-    @note Currently, wxMimeTypesManager is limited to reading MIME type information
-    but it will support modifying it as well in future versions.
+    All of these functions are static (i.e. don't need a wxMimeTypesManager object
+    to call them) and provide some useful operations for string representations of
+    MIME types. Their usage is recommended instead of directly working with MIME
+    types using wxString functions.
+
+    - wxMimeTypesManager::IsOfType()
+
+    @section mimetypemanager_query Query database
+
+    These functions are the heart of this class: they allow to find a file type
+    object from either file extension or MIME type.
+    If the function is successful, it returns a pointer to the wxFileType object
+    which must be deleted by the caller, otherwise @NULL will be returned.
+
+    - wxMimeTypesManager::GetFileTypeFromMimeType()
+    - wxMimeTypesManager::GetFileTypeFromExtension()

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{misc}
+    @category{cfg}

 
     @see wxFileType
 */
 
     @see wxFileType
 */


@@ -44,9 +55,7 @@ class wxMimeTypesManager
 {
 public:
     /**
 {
 public:
     /**

-        Constructor puts the object in the "working" state, no additional initialization
-        are needed - but @ref init() ReadXXX may be used to load
-        additional mailcap/mime.types files.
+        Constructor puts the object in the "working" state.

     */
     wxMimeTypesManager();
 
     */
     wxMimeTypesManager();
 


@@ -62,19 +71,10 @@ public:
     */
     void AddFallbacks(const wxFileTypeInfo* fallbacks);
 
     */
     void AddFallbacks(const wxFileTypeInfo* fallbacks);
 

-    /**
-        @note You won't normally need to use more than one wxMimeTypesManager object in a
-        program.
-        @ref ctor() wxMimeTypesManager
-
-        @ref dtor() ~wxMimeTypesManager
-    */
-
-

     /**
         Gather information about the files with given extension and return the
     /**
         Gather information about the files with given extension and return the

-        corresponding wxFileType object or @NULL if the extension
-        is unknown.
+        corresponding wxFileType object or @NULL if the extension is unknown.
+

         The @a extension parameter may have, or not, the leading dot, if it has it,
         it is stripped automatically. It must not however be empty.
     */
         The @a extension parameter may have, or not, the leading dot, if it has it,
         it is stripped automatically. It must not however be empty.
     */


@@ -82,90 +82,41 @@ public:
 
     /**
         Gather information about the files with given MIME type and return the
 
     /**
         Gather information about the files with given MIME type and return the

-        corresponding wxFileType object or @NULL if the MIME type
-        is unknown.
+        corresponding wxFileType object or @NULL if the MIME type is unknown.

     */
     wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);
 
     */
     wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);
 

-    /**
-        All of these functions are static (i.e. don't need a wxMimeTypesManager object
-        to call them) and provide some useful operations for string representations of
-        MIME types. Their usage is recommended instead of directly working with MIME
-        types using wxString functions.
-        IsOfType()
-    */
-

 
     /**
 
     /**

-        @b Unix: These functions may be used to load additional files (except for the
-        default ones which are loaded automatically) containing MIME
-        information in either mailcap(5) or mime.types(5) format.
-        ReadMailcap()
-
-        ReadMimeTypes()
-
-        AddFallbacks()
-    */
-
-
-    /**
-        This function returns @true if either the given @a mimeType is exactly the
-        same as @a wildcard or if it has the same category and the subtype of
+        This function returns @true if either the given @a mimeType is exactly
+        the same as @a wildcard or if it has the same category and the subtype of

         @a wildcard is '*'. Note that the '*' wildcard is not allowed in
         @a mimeType itself.
         @a wildcard is '*'. Note that the '*' wildcard is not allowed in
         @a mimeType itself.

+

         The comparison don by this function is case insensitive so it is not
         necessary to convert the strings to the same case before calling it.
     */
         The comparison don by this function is case insensitive so it is not
         necessary to convert the strings to the same case before calling it.
     */

-    bool IsOfType(const wxString& mimeType, const wxString& wildcard);
+    static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
+};

 
 

-    /**
-        These functions are the heart of this class: they allow to find a @ref
-        overview_wxfiletype "file type" object
-        from either file extension or MIME type.
-        If the function is successful, it returns a pointer to the wxFileType object
-        which @b must be deleted by the caller, otherwise @NULL will be returned.
-        GetFileTypeFromMimeType()
-
-        GetFileTypeFromExtension()
-    */

 
 

+/**
+    The global wxMimeTypesManager instance.
+*/
+wxMimeTypesManager* wxTheMimeTypesManager;

 
 

-    /**
-        Load additional file containing information about MIME types and associated
-        information in mailcap format. See metamail(1) and mailcap(5) for more
-        information.
-        @a fallback parameter may be used to load additional mailcap files without
-        overriding the settings found in the standard files: normally, entries from
-        files loaded with ReadMailcap will override the entries from files loaded
-        previously (and the standard ones are loaded in the very beginning), but this
-        will not happen if this parameter is set to @true (default is @false).
-        The return value is @true if there were no errors in the file or @false
-        otherwise.
-    */
-    bool ReadMailcap(const wxString& filename, bool fallback = false);

 
 

-    /**
-        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.
-        The return value is @true if there were no errors in the file or @false
-        otherwise.
-    */
-    bool ReadMimeTypes(const wxString& filename);
-};
+/**
+    @class wxFileType

 
 

+    This class holds information about a given @e 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).

 
 

-/**
-    @class wxFileType
-    @wxheader{mimetype.h}
-
-    This class holds information about a given @e 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
+    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 @b must be checked: @false
     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 @b must be checked: @false


@@ -189,156 +140,306 @@ public:
     typically correspond to the extension ".txt", but may as well be associated with
     ".ini" or ".conf".
 
     typically correspond to the extension ".txt", but may as well be associated with
     ".ini" or ".conf".
 

+
+    @section filetype_example MessageParameters class
+
+    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 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 cannot know about
+    these parameters, it uses MessageParameters class to query them.
+
+    The default implementation only 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() function, for example:
+
+    @code
+    // provide the message parameters for the MIME type manager
+    class MailMessageParameters : public wxFileType::MessageParameters
+    {
+    public:
+        MailMessageParameters(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);
+        }
+    };
+    @endcode
+
+    Now you only need to create an object of this class and pass it to, for example,
+    GetOpenCommand like this:
+
+    @code
+    wxString command;
+    if ( filetype->GetOpenCommand(&command,
+                                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)
+    }
+    else
+    {
+        // we don't know how to handle such files...
+    }
+    @endcode
+
+    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.
+
+

     @library{wxbase}
     @library{wxbase}

-    @category{FIXME}
+    @category{data}

 
     @see wxMimeTypesManager
 */
 class wxFileType
 {
 
     @see wxMimeTypesManager
 */
 class wxFileType
 {

-public:
+private:

     /**
         The default constructor is private because you should never create objects of
         this type: they are only returned by wxMimeTypesManager methods.
     */
     wxFileType();
 
     /**
         The default constructor is private because you should never create objects of
         this type: they are only returned by wxMimeTypesManager methods.
     */
     wxFileType();
 

+public:

     /**
     /**

-        The destructor of this class is not virtual, so it should not be derived from.
-    */
-    ~wxFileType();
+        Class representing message parameters.

 
 

-    /**
-        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.
-        The function replaces all occurrences of
+        An object of this class may be passed to wxFileType::GetOpenCommand()
+        and GetPrintCommand() if more than the file name needs to be specified.
+     */
+    class MessageParameters
+    {
+    public:
+        /// Trivial default constructor.
+        MessageParameters();

 
 

-        format specification
+        /// Constructor taking a filename and a mime type.
+        MessageParameters(const wxString& filename,
+                          const wxString& mimetype = wxEmptyString);

 
 

-        with
+        /// Return the filename.
+        const wxString& GetFileName() const;

 
 

-        %s
+        /// Return the MIME type.
+        const wxString& GetMimeType() const;

 
 

-        the full file name
+        /// Overridable method for derived classes. Returns empty string by default.
+        virtual wxString GetParamValue(const wxString& name) const;

 
 

-        %t
+        /// Trivial but virtual dtor as this class can be inherited from.
+        virtual ~MessageParameters();
+    };

 
 

-        the MIME type
+    /**
+        Copy ctor.
+    */
+    wxFileType(const wxFileTypeInfo& ftInfo);

 
 

-        %{param}
+    /**
+        The destructor of this class is not virtual, so it should not be derived from.
+    */
+    ~wxFileType();

 
 

-        the value of the parameter @e param
+    /**
+        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.

 
 

+        The function replaces all occurrences of:
+        - %s with the full file name
+        - %t with the MIME type
+        - %{param} with the value of the parameter @e param

         using the MessageParameters object you pass to it.
         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.
         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.
     */
     static wxString ExpandCommand(const wxString& command,
         Unlike all other functions of this class, there is no error return for this
         function.
     */
     static wxString ExpandCommand(const wxString& command,

-                                  MessageParameters& params);
+                                  const MessageParameters& params);

 
     /**
         If the function returns @true, the string pointed to by @a desc is filled
         with a brief description for this file type: for example, "text document" for
         the "text/plain" MIME type.
     */
 
     /**
         If the function returns @true, the string pointed to by @a desc is filled
         with a brief description for this file type: for example, "text document" for
         the "text/plain" MIME type.
     */

-    bool GetDescription(wxString* desc);
+    bool GetDescription(wxString* desc) const;

 
     /**
         If the function returns @true, the array @a extensions is filled
         with all extensions associated with this file type: for example, it may
 
     /**
         If the function returns @true, the array @a 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".
+        contain the following two elements for the MIME type "text/html"
+        (notice the absence of the leading dot): "html" and "htm".
+

         @b Windows: This function is currently not implemented: there is no
         @b 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 wxMimeTypesManager::GetFileTypeFromExtension
-        function in the first place.
+        (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 wxMimeTypesManager::GetFileTypeFromExtension function in the
+        first place.

     */
     bool GetExtensions(wxArrayString& extensions);
 
     /**
         If the function returns @true, the @c iconLoc is filled with the
     */
     bool GetExtensions(wxArrayString& extensions);
 
     /**
         If the function returns @true, the @c iconLoc is filled with the

-        location of the icon for this MIME type. A wxIcon may be
-        created from @a iconLoc later.
+        location of the icon for this MIME type.
+        A wxIcon may be created from @a iconLoc later.
+

         @b Windows: The function returns the icon shown by Explorer for the files of
         the specified type.
         @b Windows: The function returns the icon shown by Explorer for the files of
         the specified type.

+

         @b Mac: This function is not implemented and always returns @false.
         @b Mac: This function is not implemented and always returns @false.

+

         @b Unix: MIME manager gathers information about icons from GNOME
         and KDE settings and thus GetIcon's success depends on availability
         of these desktop environments.
     */
         @b Unix: MIME manager gathers information about icons from GNOME
         and KDE settings and thus GetIcon's success depends on availability
         of these desktop environments.
     */

-    bool GetIcon(wxIconLocation* iconLoc);
+    bool GetIcon(wxIconLocation* iconLoc) const;

 
     /**
         If the function returns @true, the string pointed to by @a mimeType is filled
         with full MIME type specification for this file type: for example, "text/plain".
     */
 
     /**
         If the function returns @true, the string pointed to by @a mimeType is filled
         with full MIME type specification for this file type: for example, "text/plain".
     */

-    bool GetMimeType(wxString* mimeType);
+    bool GetMimeType(wxString* mimeType) const;

 
     /**
 
     /**

-        Same as GetMimeType() 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.
+        Same as GetMimeType() 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.

     */
     */

-    bool GetMimeType(wxArrayString& mimeTypes);
+    bool GetMimeTypes(wxArrayString& mimeTypes) const;

 
     //@{
     /**
         With the first version of this method, if the @true is returned, the
         string pointed to by @a command is filled with the command which must be
 
     //@{
     /**
         With the first version of this method, if the @true is returned, the
         string pointed to by @a command is filled with the command which must be

-        executed (see 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 MessageParameters()
-        class.
+        executed (see 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 MessageParameters() 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).
     */
         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).
     */

-    bool GetOpenCommand(wxString* command,
-                        MessageParameters& params);
-    wxString GetOpenCommand(const wxString& filename);
+    bool GetOpenCommand(wxString* command, const MessageParameters& params);
+    wxString GetOpenCommand(const wxString& filename) const;

     //@}
 
     /**
         If the function returns @true, the string pointed to by @a command is filled
     //@}
 
     /**
         If the function returns @true, the string pointed to by @a command is filled

-        with the command which must be executed (see wxExecute()) in
-        order to print the file of the given type. The name of the file is
-        retrieved from MessageParameters() class.
+        with the command which must be executed (see wxExecute()) in order to
+        print the file of the given type.
+
+        The name of the file is retrieved from the MessageParameters class.

     */
     bool GetPrintCommand(wxString* command,
     */
     bool GetPrintCommand(wxString* command,

-                         MessageParameters& params);
+                         const MessageParameters& params) const;
+};

 
 

+/**
+    Container of information about wxFileType.
+
+    This class simply stores information associated with the file type. It
+    doesn't do anything on its own and is used only to allow constructing
+    wxFileType from it (instead of specifying all the constituent pieces
+    separately) and also with wxMimeTypesManager::AddFallbacks().
+ */
+class wxFileTypeInfo
+{
+public:

     /**
     /**

-        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 @e 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
-        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()
-        function, for example:
-
-        Now you only need to create an object of this class and pass it to, for example,
-        GetOpenCommand() like this:
-
-        @b 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.
-    */
-};
+        Default constructor creates an invalid file type info object.

 
 

+        Such invalid/empty object should be used to terminate the list of file
+        types passed to wxMimeTypesManager::AddFallbacks().
+     */
+    wxFileTypeInfo();
+
+    /**
+        Constructor specifying just the MIME type name.
+
+        Use the various setter methods below to fully initialize the object.
+
+        @since 2.9.2
+     */
+    wxFileTypeInfo(const wxString& mimeType);
+
+    /**
+        Constructor allowing to specify all the fields at once.
+
+        This is a vararg constructor taking an arbitrary number of extensions
+        after the first four required parameters. The list must be terminated
+        by @c wxNullPtr, notice that @c NULL can't be used here in portable
+        code (C++0x @c nullptr can be used as well if your compiler supports
+        it).
+     */
+    wxFileTypeInfo(const wxString& mimeType,
+                   const wxString& openCmd,
+                   const wxString& printCmd,
+                   const wxString& description,
+                   const wxString& extension,
+                   ...);
+
+    /**
+        Add another extension associated with this file type.
+
+        @since 2.9.2
+     */
+    void AddExtension(const wxString& ext);
+
+    /**
+        Set the file type description.
+
+        @since 2.9.2
+     */
+    void SetDescription(const wxString& description);
+
+    /**
+        Set the command to be used for opening files of this type.
+
+        @since 2.9.2
+     */
+    void SetOpenCommand(const wxString& command);
+
+    /**
+        Set the command to be used for printing files of this type.
+
+        @since 2.9.2
+     */
+    void SetPrintCommand(const wxString& command);
+
+    /**
+        Set the short description for the files of this type.
+
+        This is only used under MSW for some of the registry keys used for the
+        file type registration.
+     */
+    void SetShortDesc(const wxString& shortDesc);
+};