You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
qt3/doc/html/qmimesourcefactory.html

278 lines
16 KiB

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/kernel/qmime.cpp:179 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>QMimeSourceFactory Class</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All&nbsp;Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped&nbsp;Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QMimeSourceFactory Class Reference</h1>
<p>The QMimeSourceFactory class is an extensible provider of mime-typed data.
<a href="#details">More...</a>
<p><tt>#include &lt;<a href="qmime-h.html">qmime.h</a>&gt;</tt>
<p><a href="qmimesourcefactory-members.html">List of all member functions.</a>
<h2>Public Members</h2>
<ul>
<li class=fn><a href="#QMimeSourceFactory"><b>QMimeSourceFactory</b></a> ()</li>
<li class=fn>virtual <a href="#~QMimeSourceFactory"><b>~QMimeSourceFactory</b></a> ()</li>
<li class=fn>virtual const QMimeSource * <a href="#data"><b>data</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_name ) const</li>
<li class=fn>virtual QString <a href="#makeAbsolute"><b>makeAbsolute</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_or_rel_name, const&nbsp;QString&nbsp;&amp;&nbsp;context ) const</li>
<li class=fn>const QMimeSource * <a href="#data-2"><b>data</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_or_rel_name, const&nbsp;QString&nbsp;&amp;&nbsp;context ) const</li>
<li class=fn>virtual void <a href="#setText"><b>setText</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_name, const&nbsp;QString&nbsp;&amp;&nbsp;text )</li>
<li class=fn>virtual void <a href="#setImage"><b>setImage</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_name, const&nbsp;QImage&nbsp;&amp;&nbsp;image )</li>
<li class=fn>virtual void <a href="#setPixmap"><b>setPixmap</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_name, const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap )</li>
<li class=fn>virtual void <a href="#setData"><b>setData</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;abs_name, QMimeSource&nbsp;*&nbsp;data )</li>
<li class=fn>virtual void <a href="#setFilePath"><b>setFilePath</b></a> ( const&nbsp;QStringList&nbsp;&amp;&nbsp;path )</li>
<li class=fn>virtual QStringList <a href="#filePath"><b>filePath</b></a> () const</li>
<li class=fn>void <a href="#addFilePath"><b>addFilePath</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;p )</li>
<li class=fn>virtual void <a href="#setExtensionType"><b>setExtensionType</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;ext, const&nbsp;char&nbsp;*&nbsp;mimetype )</li>
</ul>
<h2>Static Public Members</h2>
<ul>
<li class=fn>QMimeSourceFactory * <a href="#defaultFactory"><b>defaultFactory</b></a> ()</li>
<li class=fn>void <a href="#setDefaultFactory"><b>setDefaultFactory</b></a> ( QMimeSourceFactory&nbsp;*&nbsp;factory )</li>
<li class=fn>QMimeSourceFactory * <a href="#takeDefaultFactory"><b>takeDefaultFactory</b></a> ()</li>
<li class=fn>void <a href="#addFactory"><b>addFactory</b></a> ( QMimeSourceFactory&nbsp;*&nbsp;f )</li>
<li class=fn>void <a href="#removeFactory"><b>removeFactory</b></a> ( QMimeSourceFactory&nbsp;*&nbsp;f )</li>
</ul>
<hr><a name="details"></a><h2>Detailed Description</h2>
The QMimeSourceFactory class is an extensible provider of mime-typed data.
<p>
<p> A QMimeSourceFactory provides an abstract interface to a
collection of information. Each piece of information is
represented by a <a href="qmimesource.html">QMimeSource</a> object which can be examined and
converted to concrete data types by functions such as
<a href="qimagedrag.html#canDecode">QImageDrag::canDecode</a>() and <a href="qimagedrag.html#decode">QImageDrag::decode</a>().
<p> The base QMimeSourceFactory can be used in two ways: as an
abstraction of a collection of files or as specifically stored
data. For it to access files, call <a href="#setFilePath">setFilePath</a>() before accessing
data. For stored data, call <a href="#setData">setData</a>() for each item (there are
also convenience functions, e.g. <a href="#setText">setText</a>(), <a href="#setImage">setImage</a>() and
<a href="#setPixmap">setPixmap</a>(), that simply call setData() with appropriate
parameters).
<p> The rich text widgets, <a href="qtextedit.html">QTextEdit</a> and <a href="qtextbrowser.html">QTextBrowser</a>, use
QMimeSourceFactory to resolve references such as images or links
within rich text documents. They either access the default factory
(see <a href="#defaultFactory">defaultFactory</a>()) or their own (see
<a href="qtextedit.html#setMimeSourceFactory">QTextEdit::setMimeSourceFactory</a>()). Other classes that are
capable of displaying rich text (such as <a href="qlabel.html">QLabel</a>, <a href="qwhatsthis.html">QWhatsThis</a> or
<a href="qmessagebox.html">QMessageBox</a>) always use the default factory.
<p> A factory can also be used as a container to store data associated
with a name. This technique is useful whenever rich text contains
images that are stored in the program itself, not loaded from the
hard disk. Your program may, for example, define some image data
as:
<pre>
static const char* myimage_data[]={
"...",
...
"..."};
</pre>
<p> To be able to use this image within some rich text, for example
inside a QLabel, you must create a <a href="qimage.html">QImage</a> from the raw data and
insert it into the factory with a unique name:
<pre>
QMimeSourceFactory::<a href="#defaultFactory">defaultFactory</a>()-&gt;setImage( "myimage", QImage(myimage_data) );
</pre>
<p> Now you can create a rich text QLabel with
<p> <pre>
<a href="qlabel.html">QLabel</a>* label = new <a href="qlabel.html">QLabel</a>(
"Rich text with embedded image:&lt;img source=\"myimage\"&gt;"
"Isn't that &lt;em&gt;cute&lt;/em&gt;?" );
</pre>
<p> When no longer needed, you can clear the data from the factory:
<p> <pre>
delete label;
QMimeSourceFactory::<a href="#defaultFactory">defaultFactory</a>()-&gt;setData( "myimage", 0 );
</pre>
<p>See also <a href="environment.html">Environment Classes</a> and <a href="io.html">Input/Output and Networking</a>.
<hr><h2>Member Function Documentation</h2>
<h3 class=fn><a name="QMimeSourceFactory"></a>QMimeSourceFactory::QMimeSourceFactory ()
</h3>
Constructs a QMimeSourceFactory that has no file path and no
stored content.
<h3 class=fn><a name="~QMimeSourceFactory"></a>QMimeSourceFactory::~QMimeSourceFactory ()<tt> [virtual]</tt>
</h3>
Destroys the QMimeSourceFactory, deleting all stored content.
<h3 class=fn>void <a name="addFactory"></a>QMimeSourceFactory::addFactory ( <a href="qmimesourcefactory.html">QMimeSourceFactory</a>&nbsp;*&nbsp;f )<tt> [static]</tt>
</h3>
Adds the QMimeSourceFactory <em>f</em> to the list of available
mimesource factories. If the <a href="#defaultFactory">defaultFactory</a>() can't resolve a
<a href="#data">data</a>() it iterates over the list of installed mimesource factories
until the data can be resolved.
<p> <p>See also <a href="#removeFactory">removeFactory</a>().
<h3 class=fn>void <a name="addFilePath"></a>QMimeSourceFactory::addFilePath ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;p )
</h3>
Adds another search path, <em>p</em> to the existing search paths.
<p> <p>See also <a href="#setFilePath">setFilePath</a>().
<h3 class=fn>const&nbsp;<a href="qmimesource.html">QMimeSource</a>&nbsp;* <a name="data"></a>QMimeSourceFactory::data ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_name ) const<tt> [virtual]</tt>
</h3>
Returns a reference to the data associated with <em>abs_name</em>. The
return value remains valid only until the next <a href="#data">data</a>() or <a href="#setData">setData</a>()
call, so you should immediately decode the result.
<p> If there is no data associated with <em>abs_name</em> in the factory's
store, the factory tries to access the local filesystem. If <em>abs_name</em> isn't an absolute file name, the factory will search for
it in all defined paths (see <a href="#setFilePath">setFilePath</a>()).
<p> The factory understands all the image formats supported by
<a href="qimageio.html">QImageIO</a>. Any other mime types are determined by the file name
extension. The default settings are
<pre>
<a href="#setExtensionType">setExtensionType</a>("html", "text/html;charset=iso8859-1");
<a href="#setExtensionType">setExtensionType</a>("htm", "text/html;charset=iso8859-1");
<a href="#setExtensionType">setExtensionType</a>("txt", "text/plain");
<a href="#setExtensionType">setExtensionType</a>("xml", "text/xml;charset=UTF-8");
</pre>
The effect of these is that file names ending in "txt" will be
treated as text encoded in the local encoding; those ending in
"xml" will be treated as text encoded in Unicode UTF-8 encoding.
The text/html type is treated specially, since the encoding can be
specified in the html file itself. "html" or "htm" will be treated
as text encoded in the encoding specified by the html meta tag, if
none could be found, the charset of the mime type will be used.
The text subtype ("html", "plain", or "xml") does not affect the
factory, but users of the factory may behave differently. We
recommend creating "xml" files where practical. These files can be
viewed regardless of the runtime encoding and can encode any
Unicode characters without resorting to encoding definitions
inside the file.
<p> Any file data that is not recognized will be retrieved as a
<a href="qmimesource.html">QMimeSource</a> providing the "application/octet-stream" mime type,
meaning uninterpreted binary data.
<p> You can add further extensions or change existing ones with
subsequent calls to <a href="#setExtensionType">setExtensionType</a>(). If the extension mechanism
is not sufficient for your problem domain, you can inherit
QMimeSourceFactory and reimplement this function to perform some
more specialized mime-type detection. The same applies if you want
to use the mime source factory to access URL referenced data over
a network.
<h3 class=fn>const&nbsp;<a href="qmimesource.html">QMimeSource</a>&nbsp;* <a name="data-2"></a>QMimeSourceFactory::data ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_or_rel_name, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;context ) const
</h3>
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
<p> A convenience function. See <a href="#data">data</a>(const <a href="qstring.html">QString</a>& abs_name). The
file name is given in <em>abs_or_rel_name</em> and the path is in <em>context</em>.
<h3 class=fn><a href="qmimesourcefactory.html">QMimeSourceFactory</a>&nbsp;* <a name="defaultFactory"></a>QMimeSourceFactory::defaultFactory ()<tt> [static]</tt>
</h3>
Returns the application-wide default mime source factory. This
factory is used by rich text rendering classes such as
<a href="qsimplerichtext.html">QSimpleRichText</a>, <a href="qwhatsthis.html">QWhatsThis</a> and <a href="qmessagebox.html">QMessageBox</a> to resolve named
references within rich text documents. It serves also as the
initial factory for the more complex render widgets, <a href="qtextedit.html">QTextEdit</a> and
<a href="qtextbrowser.html">QTextBrowser</a>.
<p> <p>See also <a href="#setDefaultFactory">setDefaultFactory</a>().
<p>Examples: <a href="qaction-application-example.html#x1140">action/application.cpp</a> and <a href="simple-application-example.html#x1558">application/application.cpp</a>.
<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="filePath"></a>QMimeSourceFactory::filePath () const<tt> [virtual]</tt>
</h3>
Returns the currently set search paths.
<h3 class=fn><a href="qstring.html">QString</a> <a name="makeAbsolute"></a>QMimeSourceFactory::makeAbsolute ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_or_rel_name, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;context ) const<tt> [virtual]</tt>
</h3>
Converts the absolute or relative data item name <em>abs_or_rel_name</em> to an absolute name, interpreted within the
context (path) of the data item named <em>context</em> (this must be an
absolute name).
<h3 class=fn>void <a name="removeFactory"></a>QMimeSourceFactory::removeFactory ( <a href="qmimesourcefactory.html">QMimeSourceFactory</a>&nbsp;*&nbsp;f )<tt> [static]</tt>
</h3>
Removes the mimesource factory <em>f</em> from the list of available
mimesource factories.
<p> <p>See also <a href="#addFactory">addFactory</a>().
<h3 class=fn>void <a name="setData"></a>QMimeSourceFactory::setData ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_name, <a href="qmimesource.html">QMimeSource</a>&nbsp;*&nbsp;data )<tt> [virtual]</tt>
</h3>
Sets <em>data</em> to be the data item associated with
the absolute name <em>abs_name</em>. Note that the ownership of <em>data</em> is
transferred to the factory: do not delete or access the pointer after
passing it to this function.
<p> Passing 0 for data removes previously stored data.
<h3 class=fn>void <a name="setDefaultFactory"></a>QMimeSourceFactory::setDefaultFactory ( <a href="qmimesourcefactory.html">QMimeSourceFactory</a>&nbsp;*&nbsp;factory )<tt> [static]</tt>
</h3>
Sets the default <em>factory</em>, destroying any previously set mime
source provider. The ownership of the factory is transferred to
Qt.
<p> <p>See also <a href="#defaultFactory">defaultFactory</a>().
<h3 class=fn>void <a name="setExtensionType"></a>QMimeSourceFactory::setExtensionType ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;ext, const&nbsp;char&nbsp;*&nbsp;mimetype )<tt> [virtual]</tt>
</h3>
Sets the mime-type to be associated with the file name extension,
<em>ext</em> to <em>mimetype</em>. This determines the mime-type for files
found via the paths set by <a href="#setFilePath">setFilePath</a>().
<h3 class=fn>void <a name="setFilePath"></a>QMimeSourceFactory::setFilePath ( const&nbsp;<a href="qstringlist.html">QStringList</a>&nbsp;&amp;&nbsp;path )<tt> [virtual]</tt>
</h3>
Sets the list of directories that will be searched when named data
is requested to the those given in the string list <em>path</em>.
<p> <p>See also <a href="#filePath">filePath</a>().
<h3 class=fn>void <a name="setImage"></a>QMimeSourceFactory::setImage ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_name, const&nbsp;<a href="qimage.html">QImage</a>&nbsp;&amp;&nbsp;image )<tt> [virtual]</tt>
</h3>
Sets <em>image</em> to be the data item associated with the absolute
name <em>abs_name</em>.
<p> Equivalent to <a href="#setData">setData</a>(abs_name, new <a href="qimagedrag.html">QImageDrag</a>(image)).
<h3 class=fn>void <a name="setPixmap"></a>QMimeSourceFactory::setPixmap ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_name, const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap )<tt> [virtual]</tt>
</h3>
Sets <em>pixmap</em> to be the data item associated with the absolute
name <em>abs_name</em>.
<h3 class=fn>void <a name="setText"></a>QMimeSourceFactory::setText ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;abs_name, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text )<tt> [virtual]</tt>
</h3>
Sets <em>text</em> to be the data item associated with the absolute name
<em>abs_name</em>.
<p> Equivalent to <a href="#setData">setData</a>(abs_name, new <a href="qtextdrag.html">QTextDrag</a>(text)).
<h3 class=fn><a href="qmimesourcefactory.html">QMimeSourceFactory</a>&nbsp;* <a name="takeDefaultFactory"></a>QMimeSourceFactory::takeDefaultFactory ()<tt> [static]</tt>
</h3>
Sets the <a href="#defaultFactory">defaultFactory</a>() to 0 and returns the previous one.
<!-- eof -->
<hr><p>
This file is part of the <a href="index.html">Qt toolkit</a>.
Copyright &copy; 1995-2007
<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright &copy; 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt 3.3.8</div>
</table></div></address></body>
</html>