include/wx/mimetype.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/mimetype.h
   3 // Purpose:     classes and functions to manage MIME types
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 //  Chris Elliott (biol75@york.ac.uk) 5 Dec 00: write support for Win32
   7 // Created:     23.09.98
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
  10 // Licence:     wxWindows license (part of wxExtra library)
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _MIMETYPE_H
  14 #define _MIMETYPE_H
  15
  16 #ifdef __GNUG__
  17 #pragma interface "mimetypebase.h"
  18 #endif
  19
  20
  21 // fwd decls
  22 class wxIcon;
  23 class wxFileTypeImpl;
  24 class wxMimeTypesManagerImpl;
  25
  26 #include "wx/defs.h"
  27
  28 #if wxUSE_FILE
  29
  30 // the things we really need
  31 #include "wx/string.h"
  32 #include "wx/dynarray.h"
  33
  34 class wxMimeTypeCmnModule;
  35
  36 // This class holds information about a given "file type". File type is the
  37 // same as MIME type under Unix, but under Windows it corresponds more to an
  38 // extension than to MIME type (in fact, several extensions may correspond to a
  39 // file type). This object may be created in many different ways and depending
  40 // on how it was created some fields may be unknown so the return value of all
  41 // the accessors *must* be checked!
  42 class WXDLLEXPORT wxFileType
  43 {
  44 friend class WXDLLEXPORT wxMimeTypesManagerImpl;  // it has access to m_impl
  45
  46 public:
  47     // An object of this class must be passed to Get{Open|Print}Command. The
  48     // default implementation is trivial and doesn't know anything at all about
  49     // parameters, only filename and MIME type are used (so it's probably ok for
  50     // Windows where %{param} is not used anyhow)
  51     class MessageParameters
  52     {
  53     public:
  54         // ctors
  55         MessageParameters() { }
  56         MessageParameters(const wxString& filename, const wxString& mimetype)
  57             : m_filename(filename), m_mimetype(mimetype) { }
  58
  59         // accessors (called by GetOpenCommand)
  60             // filename
  61         const wxString& GetFileName() const { return m_filename; }
  62             // mime type
  63         const wxString& GetMimeType() const { return m_mimetype; }
  64
  65         // override this function in derived class
  66         virtual wxString GetParamValue(const wxString& WXUNUSED(paramName)) const
  67             { return ""; }
  68
  69         // virtual dtor as in any base class
  70         virtual ~MessageParameters() { }
  71
  72     protected:
  73         wxString m_filename, m_mimetype;
  74     };
  75
  76     // accessors: all of them return true if the corresponding information
  77     // could be retrieved/found, false otherwise (and in this case all [out]
  78     // parameters are unchanged)
  79         // return the MIME type for this file type
  80     bool GetMimeType(wxString *mimeType) const;
  81     bool GetMimeTypes(wxArrayString& mimeTypes) const;
  82         // fill passed in array with all extensions associated with this file
  83         // type
  84     bool GetExtensions(wxArrayString& extensions);
  85         // get the icon corresponding to this file type, the name of the file
  86         // where the icon resides is return in iconfile if !NULL and its index
  87         // in this file (Win-only) is in iconIndex
  88     bool GetIcon(wxIcon *icon,
  89                  wxString *iconFile = NULL,
  90                  int *iconIndex = NULL) const;
  91         // get a brief file type description ("*.txt" => "text document")
  92     bool GetDescription(wxString *desc) const;
  93
  94     // get the command to be used to open/print the given file.
  95         // get the command to execute the file of given type
  96     bool GetOpenCommand(wxString *openCmd,
  97                         const MessageParameters& params) const;
  98         // get the command to print the file of given type
  99     bool GetPrintCommand(wxString *printCmd,
 100                          const MessageParameters& params) const;
 101
 102
 103         // return the number of commands defined for this file type, 0 if none
 104     size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
 105                           const wxFileType::MessageParameters& params) const;
 106
 107     // the methods which modify the system database are only implemented under
 108     // Win32 so far (on other platforms they will just return FALSE)
 109     //
 110     // also, they should only be used with the objects created using
 111     // wxMimeTypesManager::Associate()
 112
 113         // set the command to be used for opening the file
 114     bool SetOpenCommand(const wxString& cmd, bool overwriteprompt = TRUE);
 115
 116         // set an arbitrary command, ask confirmation if it already exists and
 117         // overwriteprompt is TRUE
 118     bool SetCommand(const wxString& cmd, const wxString& verb,
 119                     bool overwriteprompt = TRUE);
 120
 121         // set the MIME type for this filetype
 122     bool SetMimeType(const wxString& mimeType);
 123         // set the default icon for this filetype
 124     bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);
 125
 126         // remove the association from the system database
 127     bool Unassociate();
 128
 129         // delete registration info
 130     bool RemoveOpenCommand();
 131     bool RemoveCommand(const wxString& verb);
 132     bool RemoveMimeType();
 133     bool RemoveDefaultIcon();
 134
 135     // operations
 136         // expand a string in the format of GetOpenCommand (which may contain
 137         // '%s' and '%t' format specificators for the file name and mime type
 138         // and %{param} constructions).
 139     static wxString ExpandCommand(const wxString& command,
 140                                   const MessageParameters& params);
 141
 142     // dtor (not virtual, shouldn't be derived from)
 143     ~wxFileType();
 144
 145 private:
 146     // default ctor is private because the user code never creates us
 147     wxFileType();
 148
 149     // no copy ctor/assignment operator
 150     wxFileType(const wxFileType&);
 151     wxFileType& operator=(const wxFileType&);
 152
 153     wxFileTypeImpl *m_impl;
 154 };
 155
 156 // This class is only used wuth wxMimeTypesManager::AddFallbacks() and is meant
 157 // just as the container for the wxFileType data.
 158 class WXDLLEXPORT wxFileTypeInfo
 159 {
 160 public:
 161     // ctors
 162         // a normal item
 163     wxFileTypeInfo(const char *mimeType,
 164                    const char *openCmd,
 165                    const char *printCmd,
 166                    const char *desc,
 167                    // the other parameters form a NULL terminated list of
 168                    // extensions
 169                    ...);
 170
 171         // invalid item - use this to terminate the array passed to
 172         // wxMimeTypesManager::AddFallbacks
 173     wxFileTypeInfo() { }
 174
 175     bool IsValid() const { return !m_mimeType.IsEmpty(); }
 176
 177     // accessors
 178         // get the MIME type
 179     const wxString& GetMimeType() const { return m_mimeType; }
 180         // get the open command
 181     const wxString& GetOpenCommand() const { return m_openCmd; }
 182         // get the print command
 183     const wxString& GetPrintCommand() const { return m_printCmd; }
 184         // get the description
 185     const wxString& GetDescription() const { return m_desc; }
 186         // get the array of all extensions
 187     const wxArrayString& GetExtensions() const { return m_exts; }
 188
 189 private:
 190     wxString m_mimeType,    // the MIME type in "type/subtype" form
 191              m_openCmd,     // command to use for opening the file (%s allowed)
 192              m_printCmd,    // command to use for printing the file (%s allowed)
 193              m_desc;        // a free form description of this file type
 194
 195     wxArrayString m_exts;   // the extensions which are mapped on this filetype
 196 };
 197
 198 WX_DECLARE_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo);
 199
 200
 201 // This class accesses the information about all known MIME types and allows
 202 // the application to retrieve information (including how to handle data of
 203 // given type) about them.
 204 //
 205 // NB: currently it doesn't support modifying MIME database (read-only access).
 206 class WXDLLEXPORT wxMimeTypesManager
 207 {
 208 public:
 209     // static helper functions
 210     // -----------------------
 211
 212         // check if the given MIME type is the same as the other one: the second
 213         // argument may contain wildcards ('*'), but not the first. If the
 214         // types are equal or if the mimeType matches wildcard the function
 215         // returns TRUE, otherwise it returns FALSE
 216     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 217
 218     // ctor
 219     wxMimeTypesManager();
 220
 221     // Database lookup: all functions return a pointer to wxFileType object
 222     // whose methods may be used to query it for the information you're
 223     // interested in. If the return value is !NULL, caller is responsible for
 224     // deleting it.
 225         // get file type from file extension
 226     wxFileType *GetFileTypeFromExtension(const wxString& ext);
 227     wxFileType *GetOrAllocateFileTypeFromExtension(const wxString& ext);
 228         // get file type from MIME type (in format <category>/<format>)
 229     wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
 230
 231     // other operations: return TRUE if there were no errors or FALSE if there
 232     // were some unreckognized entries (the good entries are always read anyhow)
 233         // read in additional file (the standard ones are read automatically)
 234         // in mailcap format (see mimetype.cpp for description)
 235         //
 236         // 'fallback' parameter may be set to TRUE to avoid overriding the
 237         // settings from other, previously parsed, files by this one: normally,
 238         // the files read most recently would override the older files, but with
 239         // fallback == TRUE this won't happen
 240     bool ReadMailcap(const wxString& filename, bool fallback = FALSE);
 241         // read in additional file in mime.types format
 242     bool ReadMimeTypes(const wxString& filename);
 243
 244     // enumerate all known MIME types
 245     //
 246     // returns the number of retrieved file types
 247     size_t EnumAllFileTypes(wxArrayString& mimetypes);
 248
 249     // these functions can be used to provide default values for some of the
 250     // MIME types inside the program itself (you may also use
 251     // ReadMailcap(filenameWithDefaultTypes, TRUE /* use as fallback */) to
 252     // achieve the same goal, but this requires having this info in a file).
 253     //
 254     // It isn't possible (currently) to provide fallback icons using this
 255     // function.
 256     //
 257     // The filetypes array should be terminated by a NULL entry
 258     void AddFallbacks(const wxFileTypeInfo *filetypes);
 259
 260     // create a new association between the given extension and MIME type and
 261     // return the wxFileType object corresponding (which should be deleted by
 262     // caller) or NULL if something went wrong
 263     wxFileType *Associate(const wxString& ext,
 264                           const wxString& mimeType,
 265                           const wxString& filetype = wxEmptyString,
 266                           const wxString& desc = wxEmptyString);
 267
 268     // dtor (not virtual, shouldn't be derived from)
 269     ~wxMimeTypesManager();
 270
 271 private:
 272     // no copy ctor/assignment operator
 273     wxMimeTypesManager(const wxMimeTypesManager&);
 274     wxMimeTypesManager& operator=(const wxMimeTypesManager&);
 275
 276     wxMimeTypesManagerImpl *m_impl;
 277
 278     // if m_impl is NULL, create one
 279     void EnsureImpl();
 280
 281     friend class wxMimeTypeCmnModule;
 282 };
 283
 284
 285 // ----------------------------------------------------------------------------
 286 // global variables
 287 // ----------------------------------------------------------------------------
 288
 289 // the default mime manager for wxWindows programs
 290 WXDLLEXPORT_DATA(extern wxMimeTypesManager *) wxTheMimeTypesManager;
 291
 292 #endif
 293   // wxUSE_FILE
 294
 295 #endif
 296   //_MIMETYPE_H
 297
 298 /* vi: set cin tw=80 ts=4 sw=4: */