interface/wx/mimetype.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mimetype.h
   3 // Purpose:     interface of wxMimeTypesManager
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMimeTypesManager
  11
  12     This class allows the application to retrieve the information about all known
  13     MIME types from a system-specific location and the filename extensions to the
  14     MIME types and vice versa. After initialization the functions
  15     GetFileTypeFromMimeType() and GetFileTypeFromExtension()
  16     may be called: they will return a wxFileType object which
  17     may be further queried for file description, icon and other attributes.
  18
  19     Under Windows, the MIME type information is queried from registry. Under
  20     Linux and Unix, it is queried from the XDG data directories.
  21
  22     Currently, wxMimeTypesManager is limited to reading MIME type information.
  23
  24     The application should not construct its own manaer: it should use the
  25     object pointer ::wxTheMimeTypesManger.
  26
  27     @library{wxbase}
  28     @category{misc}
  29
  30     @see wxFileType
  31 */
  32 class wxMimeTypesManager
  33 {
  34 public:
  35     /**
  36         Constructor puts the object in the "working" state.
  37     */
  38     wxMimeTypesManager();
  39
  40     /**
  41         Destructor is not virtual, so this class should not be derived from.
  42     */
  43     ~wxMimeTypesManager();
  44
  45     /**
  46         This function may be used to provide hard-wired fallbacks for the MIME types
  47         and extensions that might not be present in the system MIME database.
  48         Please see the typetest sample for an example of using it.
  49     */
  50     void AddFallbacks(const wxFileTypeInfo* fallbacks);
  51
  52     /**
  53         Gather information about the files with given extension and return the
  54         corresponding wxFileType object or @NULL if the extension is unknown.
  55
  56         The @a extension parameter may have, or not, the leading dot, if it has it,
  57         it is stripped automatically. It must not however be empty.
  58     */
  59     wxFileType* GetFileTypeFromExtension(const wxString& extension);
  60
  61     /**
  62         Gather information about the files with given MIME type and return the
  63         corresponding wxFileType object or @NULL if the MIME type is unknown.
  64     */
  65     wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);
  66
  67
  68     /**
  69         This function returns @true if either the given @a mimeType is exactly the
  70         same as @a wildcard or if it has the same category and the subtype of
  71         @a wildcard is '*'. Note that the '*' wildcard is not allowed in
  72         @a mimeType itself.
  73         The comparison don by this function is case insensitive so it is not
  74         necessary to convert the strings to the same case before calling it.
  75     */
  76     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
  77
  78 };
  79
  80
  81 /**
  82     The global wxMimeTypesManager instance.
  83 */
  84 wxMimeTypesManager* wxTheMimeTypesManager;
  85
  86
  87 /**
  88     @class wxFileType
  89
  90     This class holds information about a given @e file type. File type is the same
  91     as
  92     MIME type under Unix, but under Windows it corresponds more to an extension than
  93     to MIME type (in fact, several extensions may correspond to a file type). This
  94     object may be created in several different ways: the program might know the file
  95     extension and wish to find out the corresponding MIME type or, conversely, it
  96     might want to find the right extension for the file to which it writes the
  97     contents of given MIME type. Depending on how it was created some fields may be
  98     unknown so the return value of all the accessors @b must be checked: @false
  99     will be returned if the corresponding information couldn't be found.
 100
 101     The objects of this class are never created by the application code but are
 102     returned by wxMimeTypesManager::GetFileTypeFromMimeType and
 103     wxMimeTypesManager::GetFileTypeFromExtension methods.
 104     But it is your responsibility to delete the returned pointer when you're done
 105     with it!
 106
 107     A brief reminder about what the MIME types are (see the RFC 1341 for more
 108     information): basically, it is just a pair category/type (for example,
 109     "text/plain") where the category is a basic indication of what a file is.
 110     Examples of categories are "application", "image", "text", "binary", and
 111     type is a precise definition of the document format: "plain" in the example
 112     above means just ASCII text without any formatting, while "text/html" is the
 113     HTML document source.
 114
 115     A MIME type may have one or more associated extensions: "text/plain" will
 116     typically correspond to the extension ".txt", but may as well be associated with
 117     ".ini" or ".conf".
 118
 119     @library{wxbase}
 120     @category{FIXME}
 121
 122     @see wxMimeTypesManager
 123 */
 124 class wxFileType
 125 {
 126 public:
 127     /**
 128         The default constructor is private because you should never create objects of
 129         this type: they are only returned by wxMimeTypesManager methods.
 130     */
 131     wxFileType();
 132
 133     /**
 134         The destructor of this class is not virtual, so it should not be derived from.
 135     */
 136     ~wxFileType();
 137
 138     /**
 139         This function is primarily intended for GetOpenCommand and GetPrintCommand
 140         usage but may be also used by the application directly if, for example, you want
 141         to use some non-default command to open the file.
 142         The function replaces all occurrences of
 143
 144         format specification
 145
 146         with
 147
 148         %s
 149
 150         the full file name
 151
 152         %t
 153
 154         the MIME type
 155
 156         %{param}
 157
 158         the value of the parameter @e param
 159
 160         using the MessageParameters object you pass to it.
 161         If there is no '%s' in the command string (and the string is not empty), it is
 162         assumed that the command reads the data on stdin and so the effect is the same
 163         as " %s" were appended to the string.
 164         Unlike all other functions of this class, there is no error return for this
 165         function.
 166     */
 167     static wxString ExpandCommand(const wxString& command,
 168                                   MessageParameters& params);
 169
 170     /**
 171         If the function returns @true, the string pointed to by @a desc is filled
 172         with a brief description for this file type: for example, "text document" for
 173         the "text/plain" MIME type.
 174     */
 175     bool GetDescription(wxString* desc) const;
 176
 177     /**
 178         If the function returns @true, the array @a extensions is filled
 179         with all extensions associated with this file type: for example, it may
 180         contain the following two elements for the MIME type "text/html" (notice the
 181         absence of the leading dot): "html" and "htm".
 182         @b Windows: This function is currently not implemented: there is no
 183         (efficient) way to retrieve associated extensions from the given MIME type on
 184         this platform, so it will only return @true if the wxFileType object was
 185         created
 186         by wxMimeTypesManager::GetFileTypeFromExtension
 187         function in the first place.
 188     */
 189     bool GetExtensions(wxArrayString& extensions);
 190
 191     /**
 192         If the function returns @true, the @c iconLoc is filled with the
 193         location of the icon for this MIME type. A wxIcon may be
 194         created from @a iconLoc later.
 195         @b Windows: The function returns the icon shown by Explorer for the files of
 196         the specified type.
 197         @b Mac: This function is not implemented and always returns @false.
 198         @b Unix: MIME manager gathers information about icons from GNOME
 199         and KDE settings and thus GetIcon's success depends on availability
 200         of these desktop environments.
 201     */
 202     bool GetIcon(wxIconLocation* iconLoc) const;
 203
 204     /**
 205         If the function returns @true, the string pointed to by @a mimeType is filled
 206         with full MIME type specification for this file type: for example, "text/plain".
 207     */
 208     bool GetMimeType(wxString* mimeType) const;
 209
 210     /**
 211         Same as GetMimeType() but returns array of MIME
 212         types. This array will contain only one item in most cases but sometimes,
 213         notably under Unix with KDE, may contain more MIME types. This happens when
 214         one file extension is mapped to different MIME types by KDE, mailcap and
 215         mime.types.
 216     */
 217     bool GetMimeType(wxArrayString& mimeTypes);
 218
 219     //@{
 220     /**
 221         With the first version of this method, if the @true is returned, the
 222         string pointed to by @a command is filled with the command which must be
 223         executed (see wxExecute()) in order to open the file of the
 224         given type. In this case, the name of the file as well as any other parameters
 225         is retrieved from MessageParameters()
 226         class.
 227         In the second case, only the filename is specified and the command to be used
 228         to open this kind of file is returned directly. An empty string is returned to
 229         indicate that an error occurred (typically meaning that there is no standard way
 230         to open this kind of files).
 231     */
 232     bool GetOpenCommand(wxString* command,
 233                         MessageParameters& params);
 234     wxString GetOpenCommand(const wxString& filename);
 235     //@}
 236
 237     /**
 238         If the function returns @true, the string pointed to by @a command is filled
 239         with the command which must be executed (see wxExecute()) in
 240         order to print the file of the given type. The name of the file is
 241         retrieved from MessageParameters() class.
 242     */
 243     bool GetPrintCommand(wxString* command,
 244                          MessageParameters& params);
 245
 246     /**
 247         One of the most common usages of MIME is to encode an e-mail message. The MIME
 248         type of the encoded message is an example of a @e message parameter. These
 249         parameters are found in the message headers ("Content-XXX"). At the very least,
 250         they must specify the MIME type and the version of MIME used, but almost always
 251         they provide additional information about the message such as the original file
 252         name or the charset (for the text documents).
 253         These parameters may be useful to the program used to open, edit, view or print
 254         the message, so, for example, an e-mail client program will have to pass them to
 255         this program. Because wxFileType itself can not know about these parameters,
 256         it uses MessageParameters class to query them. The default implementation only
 257         requires the caller to provide the file name (always used by the program to be
 258         called - it must know which file to open) and the MIME type and supposes that
 259         there are no other parameters. If you wish to supply additional parameters, you
 260         must derive your own class from MessageParameters and override GetParamValue()
 261         function, for example:
 262
 263         Now you only need to create an object of this class and pass it to, for example,
 264         GetOpenCommand() like this:
 265
 266         @b Windows: As only the file name is used by the program associated with the
 267         given extension anyhow (but no other message parameters), there is no need to
 268         ever derive from MessageParameters class for a Windows-only program.
 269     */
 270 };
 271