Ensure that the overall table border doesn't get overdrawn by cell borders with a...

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

diff --git a/interface/wx/mimetype.h b/interface/wx/mimetype.h
index ae5abb790eebf0f7420e54f53f0b9f0586ed910b..0e5125abf366703bd609320651b9e867f63e8290 100644 (file)
--- a/interface/wx/mimetype.h
+++ b/interface/wx/mimetype.h
@@ -2,28 +2,29 @@
 // Name:        mimetype.h
 // Purpose:     interface of wxMimeTypesManager
 // Author:      wxWidgets team
 // Name:        mimetype.h
 // Purpose:     interface of wxMimeTypesManager
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

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

-    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
-    GetFileTypeFromMimeType() and 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.
 
     Under Windows, the MIME type information is queried from registry.
     Under Linux and Unix, it is queried from the XDG data directories.
 

-    Currently, wxMimeTypesManager is limited to reading MIME type information.
+    Currently, wxMimeTypesManager is limited to @e reading MIME type information.

 
     The application should not construct its own manager: it should use the
 
     The application should not construct its own manager: it should use the

-    object pointer ::wxTheMimeTypesManger.
-
+    object pointer ::wxTheMimeTypesManager.
+    The functions GetFileTypeFromMimeType() and GetFileTypeFromExtension()
+    return a wxFileType object which may be further queried for file description, 
+    icon and other attributes.

 
     @section mimetypemanager_helpers Helper functions
 
 
     @section mimetypemanager_helpers Helper functions
 


@@ -34,41 +35,18 @@
 
     - wxMimeTypesManager::IsOfType()
 
 
     - wxMimeTypesManager::IsOfType()
 

-
-    @section mimetypemanager_ctor Constructor and destructor
-
-    NB: You won't normally need to use more than one wxMimeTypesManager object
-    in a program.
-
-    - wxMimeTypesManager::wxMimeTypesManager()
-    - wxMimeTypesManager::~wxMimeTypesManager()
-
-

     @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
     @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.
+    which must be deleted by the caller, otherwise @NULL will be returned.

 
     - wxMimeTypesManager::GetFileTypeFromMimeType()
     - wxMimeTypesManager::GetFileTypeFromExtension()
 
 
     - wxMimeTypesManager::GetFileTypeFromMimeType()
     - wxMimeTypesManager::GetFileTypeFromExtension()
 

-
-    @section mimetypemanager_init Initialization functions
-
-    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.
-
-    - wxMimeTypesManager::ReadMailcap()
-    - wxMimeTypesManager::ReadMimeTypes()
-    - wxMimeTypesManager::AddFallbacks()
-
-
-

     @library{wxbase}
     @library{wxbase}

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

 
     @see wxFileType
 */
 
     @see wxFileType
 */


@@ -118,6 +96,24 @@ public:
         necessary to convert the strings to the same case before calling it.
     */
     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
         necessary to convert the strings to the same case before calling it.
     */
     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);

+
+
+    /**
+       Create a new association using the fields of wxFileTypeInfo (at least
+       the MIME type and the extension should be set).
+    */
+    wxFileType *Associate(const wxFileTypeInfo& ftInfo);
+
+    /**
+       Undo Associate().
+    */
+    bool Unassociate(wxFileType *ft) ;
+
+    /**
+       Enumerate all known file types.  Returns the number of retrieved items.
+     */
+    size_t EnumAllFileTypes(wxArrayString& mimetypes);
+

 };
 
 
 };
 
 


@@ -127,6 +123,7 @@ public:
 wxMimeTypesManager* wxTheMimeTypesManager;
 
 
 wxMimeTypesManager* wxTheMimeTypesManager;
 
 

+

 /**
     @class wxFileType
 
 /**
     @class wxFileType
 


@@ -173,7 +170,7 @@ wxMimeTypesManager* wxTheMimeTypesManager;
     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
     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
+    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
     these parameters, it uses MessageParameters class to query them.
 
     The default implementation only requires the caller to provide the file name


@@ -228,19 +225,54 @@ wxMimeTypesManager* wxTheMimeTypesManager;
 
 
     @library{wxbase}
 
 
     @library{wxbase}

-    @category{misc}
+    @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:
+    /**
+        Class representing message parameters.
+
+        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();
+
+        /// Constructor taking a filename and a mime type.
+        MessageParameters(const wxString& filename,
+                          const wxString& mimetype = wxEmptyString);
+
+        /// Return the filename.
+        const wxString& GetFileName() const;
+
+        /// Return the MIME type.
+        const wxString& GetMimeType() const;
+
+        /// Overridable method for derived classes. Returns empty string by default.
+        virtual wxString GetParamValue(const wxString& name) const;
+
+        /// Trivial but virtual dtor as this class can be inherited from.
+        virtual ~MessageParameters();
+    };
+
+    /**
+        Copy ctor.
+    */
+    wxFileType(const wxFileTypeInfo& ftInfo);
+

     /**
         The destructor of this class is not virtual, so it should not be derived from.
     */
     /**
         The destructor of this class is not virtual, so it should not be derived from.
     */


@@ -265,7 +297,7 @@ public:
         function.
     */
     static wxString ExpandCommand(const wxString& command,
         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
 
     /**
         If the function returns @true, the string pointed to by @a desc is filled


@@ -318,7 +350,7 @@ public:
         This happens when one file extension is mapped to different MIME types
         by KDE, mailcap and 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;

 
     //@{
     /**
 
     //@{
     /**


@@ -334,8 +366,8 @@ public:
         indicate that an error occurred (typically meaning that there is no standard way
         to open this kind of files).
     */
         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;

     //@}
 
     /**
     //@}
 
     /**


@@ -345,6 +377,153 @@ public:
 
         The name of the file is retrieved from the MessageParameters class.
     */
 
         The name of the file is retrieved from the MessageParameters class.
     */

-    bool GetPrintCommand(wxString* command, MessageParameters& params);
+    bool GetPrintCommand(wxString* command,
+                         const MessageParameters& params) const;
+
+    /**
+       Returns the number of commands for this mime type, and fills the verbs
+       and commands arrays with the command information.
+     */
+    size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
+                          const wxFileType::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:
+    /**
+        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,
+                   ...);
+    
+    /**
+       Constuctor using an array of string elements corresponding to the
+       parameters of the ctor above in the same order.
+    */
+    wxFileTypeInfo(const wxArrayString& sArray);
+
+    /**
+        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);
+
+    /**
+       Set the icon information.
+    */
+    void SetIcon(const wxString& iconFile, int iconIndex = 0);
+
+    /**
+       Get the MIME type
+    */
+    const wxString& GetMimeType() const;
+    
+    /**
+       Get the open command
+    */
+    const wxString& GetOpenCommand() const;
+
+    /**
+       Get the print command
+    */
+    const wxString& GetPrintCommand() const;
+    
+    /**
+       Get the short description (only used under Win32 so far)
+    */
+    const wxString& GetShortDesc() const;
+    
+    /**
+       Get the long, user visible description
+    */
+    const wxString& GetDescription() const;
+    
+    /**
+       Get the array of all extensions
+    */
+    const wxArrayString& GetExtensions() const;
+
+    /**
+       Get the number of extensions.
+    */
+    size_t GetExtensionsCount() const;
+    
+    /**
+       Get the icon filename
+    */
+    const wxString& GetIconFile() const;
+
+    /**
+       Get the index of the icon within the icon file.
+    */
+    int GetIconIndex() const;
+
+};