(system-wide) and .mailcap and .mime.types in the current user's home directory:
all of these files are searched for and loaded if found by default. However,
additional functions
-\helpref{wxMimeTypesManager::ReadMailcap}{wxmimetypesmanagerreadmailcap} and
+\helpref{wxMimeTypesManager::ReadMailcap}{wxmimetypesmanagerreadmailcap} and
\helpref{wxMimeTypesManager::ReadMimeTypes}{wxmimetypesmanagerreadmimetypes} are
provided to load additional files.
+If GNOME or KDE desktop environment is installed, then wxMimeTypesManager
+gathers MIME information from respective files (e.g. .kdelnk files under KDE).
+
NB: Currently, wxMimeTypesManager is limited to reading MIME type information
-but it will support modifying it as well in the future versions.
+but it will support modifying it as well in future versions.
+
+\wxheading{Global objects}
+
+Global instance of wxMimeTypesManager is always available. It is defined
+as follows:
-\wxheading{Required headers}
+\begin{verbatim}
+wxMimeTypesManager *wxTheMimeTypesManager;
+\end{verbatim}
-#include <wx/mimetype.h>
+It is recommended to use this instance instead of creating your own because
+gathering MIME information may take quite a long time on Unix systems.
\wxheading{Derived from}
No base class.
+\wxheading{Include files}
+
+<wx/mimetype.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
\wxheading{See also}
\helpref{wxFileType}{wxfiletype}
\latexignore{\rtfignore{\wxheading{Function groups}}}
-\membersection{Constructor and destructor}
+
+\membersection{Helper functions}\label{mimehelperfunctions}
+
+All of these functions are static (i.e. don't need a wxMimeTypesManager object
+to call them) and provide some useful operations for string representations of
+MIME types. Their usage is recommended instead of directly working with MIME
+types using wxString functions.
+
+\helpref{IsOfType}{wxmimetypesmanagerisoftype}
+
+
+\membersection{Constructor and destructor}\label{mimeconstructordestructor}
NB: You won't normally need to use more than one wxMimeTypesManager object in a
program.
\helpref{wxMimeTypesManager}{wxmimetypesmanagerctor}\\
\helpref{\destruct{wxMimeTypesManager}}{wxmimetypesmanagerdtor}
-\membersection{Query database}
-These functions are the heart of this class: they allow to find a
-\helpref{file type}{wxfiletype} object from either file extension or MIME type.
+\membersection{Query database}\label{mimequerydatabase}
+
+These functions are the heart of this class: they allow to find a \helpref{file type}{wxfiletype} object
+from either file extension or MIME type.
If the function is successful, it returns a pointer to the wxFileType object
-which {\bf must be deleted by the caller}, otherwise NULL will be returned.
+which {\bf must} be deleted by the caller, otherwise \NULL will be returned.
\helpref{GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}\\
\helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
-\membersection{Initialization functions}
-{\bf Unix:} These functions may be used to load additional (except for the
-default ones which are loaded automatically) files containing MIME
+\membersection{Initialization functions}\label{wxmimetypesmanagerinit}
+
+{\bf 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.
\helpref{ReadMailcap}{wxmimetypesmanagerreadmailcap}\\
-\helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}
+\helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}\\
+\helpref{AddFallbacks}{wxmimetypesmanageraddfallbacks}
%%%%% MEMBERS HERE %%%%%
\helponly{\insertatlevel{2}{
}}
+
\membersection{wxMimeTypesManager::wxMimeTypesManager}\label{wxmimetypesmanagerctor}
+
\func{}{wxMimeTypesManager}{\void}
Constructor puts the object in the "working" state, no additional initialization
are needed - but \helpref{ReadXXX}{wxmimetypesmanagerinit} may be used to load
additional mailcap/mime.types files.
+
\membersection{wxMimeTypesManager::\destruct{wxMimeTypesManager}}\label{wxmimetypesmanagerdtor}
-\func{}{\destruct{wxMimeTypesManager}{\void}
+
+\func{}{\destruct{wxMimeTypesManager}}{\void}
Destructor is not virtual, so this class should not be derived from.
+
+\membersection{wxMimeTypesManager::AddFallbacks}\label{wxmimetypesmanageraddfallbacks}
+
+\func{void}{AddFallbacks}{\param{const wxFileTypeInfo *}{fallbacks}}
+
+This function may be used to provide hard-wired fallbacks for the MIME types
+and extensions that might not be present in the system MIME database.
+
+% TODO
+
+Please see the typetest sample for an example of using it.
+
+
\membersection{wxMimeTypesManager::GetFileTypeFromExtension}\label{wxmimetypesmanagergetfiletypefromextension}
-\func{wxFileType *}{GetFileTypeFromExtension}{\param{const wxString \&}{extension}}
+
+\func{wxFileType*}{GetFileTypeFromExtension}{\param{const wxString\&}{ extension}}
Gather information about the files with given extension and return the
-corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the extension
+corresponding \helpref{wxFileType}{wxfiletype} object or \NULL if the extension
is unknown.
+The \arg{extension} parameter may have, or not, the leading dot, if it has it,
+it is stripped automatically. It must not however be empty.
+
+
\membersection{wxMimeTypesManager::GetFileTypeFromMimeType}\label{wxmimetypesmanagergetfiletypefrommimetype}
-\func{wxFileType *}{GetFileTypeFromMimeType}{\param{const wxString \&}{mimeType}}
+
+\func{wxFileType*}{GetFileTypeFromMimeType}{\param{const wxString\&}{ mimeType}}
Gather information about the files with given MIME type and return the
-corresponding \helpref{wxFileType}{wxfiletype} object or NULL if the MIME type
+corresponding \helpref{wxFileType}{wxfiletype} object or \NULL if the MIME type
is unknown.
+
+\membersection{wxMimeTypesManager::IsOfType}\label{wxmimetypesmanagerisoftype}
+
+\func{bool}{IsOfType}{\param{const wxString\&}{ mimeType}, \param{const wxString\&}{ wildcard}}
+
+This function returns true if either the given {\it mimeType} is exactly the
+same as {\it wildcard} or if it has the same category and the subtype of
+{\it wildcard} is '*'. Note that the '*' wildcard is not allowed in
+{\it mimeType} itself.
+
+The comparison don by this function is case insensitive so it is not
+necessary to convert the strings to the same case before calling it.
+
+
\membersection{wxMimeTypesManager::ReadMailcap}\label{wxmimetypesmanagerreadmailcap}
-\func{\void}{ReadMailcap}{\param{const wxString \&}{filename}}
+
+\func{bool}{ReadMailcap}{\param{const wxString\&}{ filename}, \param{bool}{ fallback = false}}
Load additional file containing information about MIME types and associated
information in mailcap format. See metamail(1) and mailcap(5) for more
information.
+{\it fallback} parameter may be used to load additional mailcap files without
+overriding the settings found in the standard files: normally, entries from
+files loaded with ReadMailcap will override the entries from files loaded
+previously (and the standard ones are loaded in the very beginning), but this
+will not happen if this parameter is set to true (default is false).
+
+The return value is true if there were no errors in the file or false
+otherwise.
+
+
\membersection{wxMimeTypesManager::ReadMimeTypes}\label{wxmimetypesmanagerreadmimetypes}
-\func{\void}{ReadMimeTypes}{\param{const wxString \&}{filename}}
+
+\func{bool}{ReadMimeTypes}{\param{const wxString\&}{ filename}}
Load additional file containing information about MIME types and associated
information in mime.types file format. See metamail(1) and mailcap(5) for more
information.
+
+The return value is true if there were no errors in the file or false
+otherwise.
+
projects / wxWidgets.git / blobdiff