docs/latex/wx/mimetype.tex

   1 \section{\class{wxMimeTypesManager}}\label{wxmimetypesmanager}
   2
   3 This class allows the application to retrieve the information about all known
   4 MIME types from a system-specific location and the filename extensions to the
   5 MIME types and vice versa. After initialization the functions
   6 \helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}
   7 and \helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
   8 may be called: they will return a \helpref{wxFileType}{wxfiletype} object which
   9 may be further queried for file description, icon and other attributes.
  10
  11 {\bf Windows:} MIME type information is stored in the registry and no additional
  12 initialization is needed.
  13
  14 {\bf Unix:} MIME type information is stored in the files mailcap and mime.types
  15 (system-wide) and .mailcap and .mime.types in the current user's home directory:
  16 all of these files are searched for and loaded if found by default. However,
  17 additional functions
  18 \helpref{wxMimeTypesManager::ReadMailcap}{wxmimetypesmanagerreadmailcap} and
  19 \helpref{wxMimeTypesManager::ReadMimeTypes}{wxmimetypesmanagerreadmimetypes} are
  20 provided to load additional files.
  21
  22 If GNOME or KDE desktop environment is installed, then wxMimeTypesManager
  23 gathers MIME information from respective files (e.g. .kdelnk files under KDE).
  24
  25 NB: Currently, wxMimeTypesManager is limited to reading MIME type information
  26 but it will support modifying it as well in future versions.
  27
  28 \wxheading{Global objects}
  29
  30 Global instance of wxMimeTypesManager is always available. It is defined
  31 as follows:
  32
  33 \begin{verbatim}
  34 wxMimeTypesManager *wxTheMimeTypesManager;
  35 \end{verbatim}
  36
  37 It is recommended to use this instance instead of creating your own because
  38 gathering MIME information may take quite a long time on Unix systems.
  39
  40 \wxheading{Derived from}
  41
  42 No base class.
  43
  44 \wxheading{Include files}
  45
  46 <wx/mimetype.h>
  47
  48 \wxheading{Library}
  49
  50 \helpref{wxBase}{librarieslist}
  51
  52 \wxheading{See also}
  53
  54 \helpref{wxFileType}{wxfiletype}
  55
  56 \latexignore{\rtfignore{\wxheading{Function groups}}}
  57
  58
  59 \membersection{Helper functions}\label{mimehelperfunctions}
  60
  61 All of these functions are static (i.e. don't need a wxMimeTypesManager object
  62 to call them) and provide some useful operations for string representations of
  63 MIME types. Their usage is recommended instead of directly working with MIME
  64 types using wxString functions.
  65
  66 \helpref{IsOfType}{wxmimetypesmanagerisoftype}
  67
  68
  69 \membersection{Constructor and destructor}\label{mimeconstructordestructor}
  70
  71 NB: You won't normally need to use more than one wxMimeTypesManager object in a
  72 program.
  73
  74 \helpref{wxMimeTypesManager}{wxmimetypesmanagerctor}\\
  75 \helpref{\destruct{wxMimeTypesManager}}{wxmimetypesmanagerdtor}
  76
  77
  78 \membersection{Query database}\label{mimequerydatabase}
  79
  80 These functions are the heart of this class: they allow to find a \helpref{file type}{wxfiletype} object
  81 from either file extension or MIME type.
  82 If the function is successful, it returns a pointer to the wxFileType object
  83 which {\bf must} be deleted by the caller, otherwise \NULL will be returned.
  84
  85 \helpref{GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}\\
  86 \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
  87
  88
  89 \membersection{Initialization functions}\label{wxmimetypesmanagerinit}
  90
  91 {\bf Unix:} These functions may be used to load additional files (except for the
  92 default ones which are loaded automatically) containing MIME
  93 information in either mailcap(5) or mime.types(5) format.
  94
  95 \helpref{ReadMailcap}{wxmimetypesmanagerreadmailcap}\\
  96 \helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}\\
  97 \helpref{AddFallbacks}{wxmimetypesmanageraddfallbacks}
  98
  99 %%%%% MEMBERS HERE %%%%%
 100 \helponly{\insertatlevel{2}{
 101
 102 \wxheading{Members}
 103
 104 }}
 105
 106
 107 \membersection{wxMimeTypesManager::wxMimeTypesManager}\label{wxmimetypesmanagerctor}
 108
 109 \func{}{wxMimeTypesManager}{\void}
 110
 111 Constructor puts the object in the "working" state, no additional initialization
 112 are needed - but \helpref{ReadXXX}{wxmimetypesmanagerinit} may be used to load
 113 additional mailcap/mime.types files.
 114
 115
 116 \membersection{wxMimeTypesManager::\destruct{wxMimeTypesManager}}\label{wxmimetypesmanagerdtor}
 117
 118 \func{}{\destruct{wxMimeTypesManager}}{\void}
 119
 120 Destructor is not virtual, so this class should not be derived from.
 121
 122
 123 \membersection{wxMimeTypesManager::AddFallbacks}\label{wxmimetypesmanageraddfallbacks}
 124
 125 \func{void}{AddFallbacks}{\param{const wxFileTypeInfo *}{fallbacks}}
 126
 127 This function may be used to provide hard-wired fallbacks for the MIME types
 128 and extensions that might not be present in the system MIME database.
 129
 130 % TODO
 131
 132 Please see the typetest sample for an example of using it.
 133
 134
 135 \membersection{wxMimeTypesManager::GetFileTypeFromExtension}\label{wxmimetypesmanagergetfiletypefromextension}
 136
 137 \func{wxFileType*}{GetFileTypeFromExtension}{\param{const wxString\&}{ extension}}
 138
 139 Gather information about the files with given extension and return the
 140 corresponding \helpref{wxFileType}{wxfiletype} object or \NULL if the extension
 141 is unknown.
 142
 143 The \arg{extension} parameter may have, or not, the leading dot, if it has it,
 144 it is stripped automatically. It must not however be empty.
 145
 146
 147 \membersection{wxMimeTypesManager::GetFileTypeFromMimeType}\label{wxmimetypesmanagergetfiletypefrommimetype}
 148
 149 \func{wxFileType*}{GetFileTypeFromMimeType}{\param{const wxString\&}{ mimeType}}
 150
 151 Gather information about the files with given MIME type and return the
 152 corresponding \helpref{wxFileType}{wxfiletype} object or \NULL if the MIME type
 153 is unknown.
 154
 155
 156 \membersection{wxMimeTypesManager::IsOfType}\label{wxmimetypesmanagerisoftype}
 157
 158 \func{bool}{IsOfType}{\param{const wxString\&}{ mimeType}, \param{const wxString\&}{ wildcard}}
 159
 160 This function returns true if either the given {\it mimeType} is exactly the
 161 same as {\it wildcard} or if it has the same category and the subtype of
 162 {\it wildcard} is '*'. Note that the '*' wildcard is not allowed in
 163 {\it mimeType} itself.
 164
 165 The comparison don by this function is case insensitive so it is not
 166 necessary to convert the strings to the same case before calling it.
 167
 168
 169 \membersection{wxMimeTypesManager::ReadMailcap}\label{wxmimetypesmanagerreadmailcap}
 170
 171 \func{bool}{ReadMailcap}{\param{const wxString\&}{ filename}, \param{bool}{ fallback = false}}
 172
 173 Load additional file containing information about MIME types and associated
 174 information in mailcap format. See metamail(1) and mailcap(5) for more
 175 information.
 176
 177 {\it fallback} parameter may be used to load additional mailcap files without
 178 overriding the settings found in the standard files: normally, entries from
 179 files loaded with ReadMailcap will override the entries from files loaded
 180 previously (and the standard ones are loaded in the very beginning), but this
 181 will not happen if this parameter is set to true (default is false).
 182
 183 The return value is true if there were no errors in the file or false
 184 otherwise.
 185
 186
 187 \membersection{wxMimeTypesManager::ReadMimeTypes}\label{wxmimetypesmanagerreadmimetypes}
 188
 189 \func{bool}{ReadMimeTypes}{\param{const wxString\&}{ filename}}
 190
 191 Load additional file containing information about MIME types and associated
 192 information in mime.types file format. See metamail(1) and mailcap(5) for more
 193 information.
 194
 195 The return value is true if there were no errors in the file or false
 196 otherwise.
 197