Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MIME classes with docs (not yet added to the makefiles)

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1321 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
1999-01-05 22:40:50 +00:00
parent 89b193cb43
commit b13d92d1c8
5 changed files with 1664 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/latex/wx/classes.tex
View File

@@ -81,6 +81,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$
\input file.tex
\input filedlg.tex
\input filehist.tex
\input filetype.tex
\input focusevt.tex
\input font.tex
\input fontdlg.tex
@@ -113,13 +114,14 @@ $$\image{14cm;0cm}{wxclass.ps}$$
\input menuitem.tex
\input menuevt.tex
\input memorydc.tex
\input msgdlg.tex
\input metafile.tex
\input mimetype.tex
\input minifram.tex
\input module.tex
\input mouseevt.tex
\input moveevt.tex
\input mltchdlg.tex
\input msgdlg.tex
\input mutex.tex
\input mutexlck.tex
\input node.tex

194
docs/latex/wx/filetype.tex Normal file
View File

@@ -0,0 +1,194 @@
\section{\class{wxFileType}}\label{wxfiletype}
This class holds information about a given "file type". File type is the same as
MIME type under Unix, but under Windows it corresponds more to an extension than
to MIME type (in fact, several extensions may correspond to a file type). This
object may be created in several different ways: the program might know the file
extension and wish to find out the corresponding MIME type or, conversely, it
might want to find the right extension for the file to which it writes the
contents of given MIME type. Depending on how it was created some fields may be
unknown so the return value of all the accessors {\bf must} be checked: FALSE
will be returned if the corresponding information couldn't be found.
The objects of this class are never created by the application code but are
returned by \helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype} and
\helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension} methods.
But it's your responsability to delete the returned pointer when you're done
with it!
% TODO describe MIME types better than this...
A brief remainder about what the MIME types are (see the RFC 1341 for more
information): basicly, it is just a pair category/type (for example,
"text/plain") where the category is a basic indication of what a file is
(examples of categories are "application", "image", "text", "binary"...) and
type is a precise definition of the document format: "plain" in the example
above means just ASCII text without any formatting, while "text/html" is the
HTML document source.
A MIME type may have one or more associated extensions: "text/plain" will
typically correspond to the extension ".txt", but may as well be associated with
".ini" or ".conf".
\wxheading{Required headers}
#include <wx/mimetype.h>
\wxheading{Derived from}
No base class.
\wxheading{See also}
\helpref{wxMimeTypesManager}{wxmimetypesmanager}
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{MessageParameters class}{wxfiletypemessageparameters}
One of the most common usages of MIME is to encode an e-mail message. The MIME
type of the encoded message is an example of a {\it message parameter}. These
parameters are found in the message headers ("Content-XXX"). At the very least,
they must specify the MIME type and the version of MIME used, but almost always
they provide additional information about the message such as the original file
name or the charset (for the text documents).
These parameters may be useful to the program used to open, edit, view or print
the message, so, for example, an e-mail client program will have to pass them to
this program. Because wxFileType itself can not know about these parameters,
it uses MessageParameters class to query them. The default implementation only
requiers the caller to provide the file name (always used by the program to be
called - it must know which file to open) and the MIME type and supposes that
there are no other parameters. If you wish to supply additional parameters, you
must derive your own class from MessageParameters and override GetParamValue()
function, for example:
\begin{verbatim}
// provide the message parameters for the MIME type manager
class MailMessageParamaters : public wxFileType::MessageParameters
{
public:
MailMessageParamaters(const wxString& filename,
const wxString& mimetype)
: wxFileType::MessageParameters(filename, mimetype)
{
}
virtual wxString GetParamValue(const wxString& name) const
{
// parameter names are not case-sensitive
if ( name.CmpNoCase("charset") == 0 )
return "US-ASCII";
else
return wxFileType::MessageParameters::GetParamValue(name);
}
};
\end{verbatim}
Now you only need to create an object of this class and pass it to, for example,
\helpref{GetOpenCommand}{wxfiletypegetopencommand} like this:
\begin{verbatim}
wxString command;
if ( filetype->GetOpenCommand(&command,
MailMessageParamaters("foo.txt", "text/plain")) )
{
// the full command for opening the text documents is in 'command'
// (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
}
else
{
// we don't know how to handle such files...
}
\end{verbatim}
{\bf Windows:} As only the file name is used by the program associated with the
given extension anyhow (but no other message parameters), there is no need to
ever derive from MessageParameters class for a Windows-only program.
\membersection{wxFileType::wxFileType}\label{wxfiletypewxfiletype}
\func{}{wxFileType}{\void}
The default constructor is private because you should never create objects of
this type: they are only returned by
\helpref{wxMimeTypesManager}{wxmimetypesmanager} methods.
\membersection{wxFileType::\destruct{wxFileType}}\label{wxfiletypedtor}
\func{}{\destruct{wxFileType}{\void}
The destructor of this class is not virtual, so it should not be derived from.
\membersection{wxFileType::GetMimeType}\label{wxfiletypegetmimetype}
\func{bool}{GetMimeType}{\param{wxString *}{mimeType}}
If the function returns TRUE, the string pointed to by {\it mimeType} is filled
with full MIME type specification for this file type: for example, "text/plain".
\membersection{wxFileType::GetExtensions}\label{wxfiletypegetextensions}
\func{bool}{GetExtensions}{\param{wxArrayString \&}{extensions}}
If the function returns TRUE, the array {\it extensions} is filled
with all extensions associated with this file type: for example, it may
contain the following two elements for the MIME type "text/html" (notice the
absence of the leading dot): "html" and "htm".
{\bf Windows:} This function is currently not implemented: there is no
(efficient) way to retrieve associated extensions from the given MIME type on
this platform, so it will only return TRUE if the wxFileType object was created
by \helpref{GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
function in the first place.
\membersection{wxFileType::GetIcon}\label{wxfiletypegeticon}
\func{bool}{GetIcon}{\param{wxIcon *}{icon}}
If the function returns TRUE, the icon associated with this file type will be
created and assigned to the {\it icon} parameter.
{\bf Unix:} This function always returns FALSE under Unix.
\membersection{wxFileType::GetDescription}\label{wxfiletypegetdescription}
\func{bool}{GetDescription}{\param{wxString *}{desc}}
If the function returns TRUE, the string pointed to by {\it desc} is filled
with a brief description for this file type: for example, "text document" for
the "text/plain" MIME type.
\membersection{wxFileType::GetOpenCommand}\label{wxfiletypegetopencommand}
\func{bool}{GetOpenCommand}{\param{wxString *}{command},\param{MessageParameters \&}{params}}
If the function returns TRUE, the string pointed to by {\it command} is filled
with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
order to open the file of the given type. The name of the file is
retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
\membersection{wxFileType::GetPrintCommand}\label{wxfiletypegetprintcommand}
\func{bool}{GetPrintCommand}{\param{wxString *}{command},\param{MessageParameters \&}{params}}
If the function returns TRUE, the string pointed to by {\it command} is filled
with the command which must be executed (see \helpref{wxExecute}{wxexecute}) in
order to print the file of the given type. The name of the file is
retrieved from \helpref{MessageParameters}{wxfiletypemessageparameters} class.
\membersection{wxFileType::ExpandCommand}\label{wxfiletypeexpandcommand}
\func{static wxString}{ExpandCommand}{\param{const wxString \&}{command},\param{MessageParameters \&}{params}}
This function is primarly intended for GetOpenCommand and GetPrintCommand
usage but may be also used by the application directly if, for example, you want
to use some non default command to open the file.
The function replaces all occurences of
\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{format specificator}{with}
\twocolitem{\%s}{the full file name}
\twocolitem{\%t}{the MIME type}
\twocolitem{\%\{param\}}{the value of the parameter {\it param}}
\end{twocollist}
using the MessageParameters object you pass to it.
If there is no '\%s' in the command string (and the string is not empty), it is
assumed that the command reads the data on stdin and so the effect is the same
as "< \%s" were appended to the string.
Unlike all other functions of this class, there is no error return for this
function.

111
docs/latex/wx/mimetype.tex Normal file
View File

@@ -0,0 +1,111 @@
\section{\class{wxMimeTypesManager}}\label{wxmimetypesmanager}
This class allows the application to retrieve the information about all known
MIME types from a system-specific location and the filename extensions to the
MIME types and vice versa. After initialization the functions
\helpref{wxMimeTypesManager::GetFileTypeFromMimeType}{wxmimetypesmanagergetfiletypefrommimetype}
and \helpref{wxMimeTypesManager::GetFileTypeFromExtension}{wxmimetypesmanagergetfiletypefromextension}
may be called: they will return a \helpref{wxFileType}{wxfiletype} object which
may be further queried for file description, icon and other attributes.
{\bf Windows:} MIME type information is stored in the registry and no additional
initialization is needed.
{\bf Unix:} MIME type information is stored in the files mailcap and mime.types
(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::ReadMimeTypes}{wxmimetypesmanagerreadmimetypes} are
provided to load additional files.
NB: Currently, wxMimeTypesManager is limited to reading MIME type information
but it will support modifying it as well in the future versions.
\wxheading{Required headers}
#include <wx/mimetype.h>
\wxheading{Derived from}
No base class.
\wxheading{See also}
\helpref{wxFileType}{wxfiletype}
\latexignore{\rtfignore{\wxheading{Function groups}}}
\membersection{Constructor and destructor}
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.
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.
\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
information in either mailcap(5) or mime.types(5) format.
\helpref{ReadMailcap}{wxmimetypesmanagerreadmailcap}\\
\helpref{ReadMimeTypes}{wxmimetypesmanagerreadmimetypes}
%%%%% MEMBERS HERE %%%%%
\helponly{\insertatlevel{2}{
\wxheading{Members}
}}
\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}
Destructor is not virtual, so this class should not be derived from.
\membersection{wxMimeTypesManager::GetFileTypeFromExtension}\label{wxmimetypesmanagergetfiletypefromextension}
\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
is unknown.
\membersection{wxMimeTypesManager::GetFileTypeFromMimeType}\label{wxmimetypesmanagergetfiletypefrommimetype}
\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
is unknown.
\membersection{wxMimeTypesManager::ReadMailcap}\label{wxmimetypesmanagerreadmailcap}
\func{\void}{ReadMailcap}{\param{const wxString \&}{filename}}
Load additional file containing information about MIME types and associated
information in mailcap format. See metamail(1) and mailcap(5) for more
information.
\membersection{wxMimeTypesManager::ReadMimeTypes}\label{wxmimetypesmanagerreadmimetypes}
\func{\void}{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.