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 the future versions.
  27
  28 \wxheading{Derived from}
  29
  30 No base class.
  31
  32 \wxheading{Include files}
  33
  34 <wx/mimetype.h>
  35
  36 \wxheading{See also}
  37
  38 \helpref{wxFileType}{wxfiletype}
  39
  40 \latexignore{\rtfignore{\wxheading{Function groups}}}
  41
  42 \membersection{Helper functions}
  43
  44 All of these functions are static (i.e. don't need a wxMimeTypesManager object
  45 to call them) and provide some useful operations for string representations of
  46 MIME types. Their usage is recommended instead of directly working with MIME
  47 types using wxString functions.
  48
  49 \helpref{IsOfType}{wxmimetypesmanagerisoftype}
  50
  51 \membersection{Constructor and destructor}
  52
  53 NB: You won't normally need to use more than one wxMimeTypesManager object in a
  54 program.
  55
  56 \helpref{wxMimeTypesManager}{wxmimetypesmanagerctor}\\
  57 \helpref{\destruct{wxMimeTypesManager}}{wxmimetypesmanagerdtor}
  58
  59 \membersection{Query database}
  60
  61 These functions are the heart of this class: they allow to find a \helpref{file type}{wxfiletype} object
  62 from either file extension or MIME type.
  63 If the function is successful, it returns a pointer to the wxFileType object
  64 which {\bf must} be deleted by the caller, otherwise NULL will be returned.
  65
  66 \helpref{GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}\\
  67 \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
  68
  69 \membersection{Initialization functions}\label{wxmimetypesmanagerinit}
  70
  71 {\bf Unix:} These functions may be used to load additional files (except for the
  72 default ones which are loaded automatically) containing MIME
  73 information in either mailcap(5) or mime.types(5) format.
  74
  75 \helpref{ReadMailcap}{wxmimetypesmanagerreadmailcap}\\
  76 \helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}\\
  77 \helpref{AddFallbacks}{wxmimetypesmanageraddfallbacks}
  78
  79 %%%%% MEMBERS HERE %%%%%
  80 \helponly{\insertatlevel{2}{
  81
  82 \wxheading{Members}
  83
  84 }}
  85
  86 \membersection{wxMimeTypesManager::wxMimeTypesManager}\label{wxmimetypesmanagerctor}
  87
  88 \func{}{wxMimeTypesManager}{\void}
  89
  90 Constructor puts the object in the "working" state, no additional initialization
  91 are needed - but \helpref{ReadXXX}{wxmimetypesmanagerinit} may be used to load
  92 additional mailcap/mime.types files.
  93
  94 \membersection{wxMimeTypesManager::\destruct{wxMimeTypesManager}}\label{wxmimetypesmanagerdtor}
  95
  96 \func{}{\destruct{wxMimeTypesManager}}{\void}
  97
  98 Destructor is not virtual, so this class should not be derived from.
  99
 100 \membersection{wxMimeTypesManager::AddFallbacks}\label{wxmimetypesmanageraddfallbacks}
 101
 102 \func{void}{AddFallbacks}{\param{const wxFileTypeInfo *}{fallbacks}}
 103
 104 This function may be used to provdie hard-wired fallbacks for the MIME types
 105 and extensions that might not be present in the system MIME database.
 106
 107 % TODO
 108
 109 Please see the typetest sample for an example of using it.
 110
 111 \membersection{wxMimeTypesManager::GetFileTypeFromExtension}\label{wxmimetypesmanagergetfiletypefromextension}
 112
 113 \func{wxFileType*}{GetFileTypeFromExtension}{\param{const wxString\&}{ extension}}
 114
 115 Gather information about the files with given extension and return the
 116 corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the extension
 117 is unknown.
 118
 119 \membersection{wxMimeTypesManager::GetFileTypeFromMimeType}\label{wxmimetypesmanagergetfiletypefrommimetype}
 120
 121 \func{wxFileType*}{GetFileTypeFromMimeType}{\param{const wxString\&}{ mimeType}}
 122
 123 Gather information about the files with given MIME type and return the
 124 corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the MIME type
 125 is unknown.
 126
 127 \membersection{wxMimeTypesManager::IsOfType}\label{wxmimetypesmanagerisoftype}
 128
 129 \func{bool}{IsOfType}{\param{const wxString\&}{ mimeType}, \param{const wxString\&}{ wildcard}}
 130
 131 This function returns TRUE if either the given {\it mimeType} is exactly the
 132 same as {\it wildcard} or if it has the same category and the subtype of
 133 {\it wildcard} is '*'. Note that the '*' wildcard is not allowed in
 134 {\it mimeType} itself.
 135
 136 The comparaison don by this function is case insensitive so it is not
 137 necessary to convert the strings to the same case before calling it.
 138
 139 \membersection{wxMimeTypesManager::ReadMailcap}\label{wxmimetypesmanagerreadmailcap}
 140
 141 \func{bool}{ReadMailcap}{\param{const wxString\&}{ filename}, \param{bool}{ fallback = FALSE}}
 142
 143 Load additional file containing information about MIME types and associated
 144 information in mailcap format. See metamail(1) and mailcap(5) for more
 145 information.
 146
 147 {\it fallback} parameter may be used to load additional mailcap files without
 148 overriding the settings found in the standard files: normally, entries from
 149 files loaded with ReadMailcap will override the entries from files loaded
 150 previously (and the standard ones are loaded in the very beginning), but this
 151 will not happen if this parameter is set to TRUE (default is FALSE).
 152
 153 The return value is TRUE if there were no errors in the file or FALSE
 154 otherwise.
 155
 156 \membersection{wxMimeTypesManager::ReadMimeTypes}\label{wxmimetypesmanagerreadmimetypes}
 157
 158 \func{bool}{ReadMimeTypes}{\param{const wxString\&}{ filename}}
 159
 160 Load additional file containing information about MIME types and associated
 161 information in mime.types file format. See metamail(1) and mailcap(5) for more
 162 information.
 163
 164 The return value is TRUE if there were no errors in the file or FALSE
 165 otherwise.
 166