<HTML>
<HEAD>
<TITLE>class KTrader</TITLE>
<META NAME="Generator" CONTENT="KDOC ">
</HEAD>
<BODY bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#000099" alink= "#ffffff">
<TABLE WIDTH="100%" BORDER="0">
<TR>
<TD>
<TABLE BORDER="0">
<TR><TD valign="top" align="left" cellspacing="10">
<h1>class KTrader</h1>
</TD>
<TD valign="top" align="right" colspan="1">Provides a way to query the KDE infrastructure for specific
applications or components.
<small><A HREF="#longdesc">More...</A></small></TD></TR>
</TABLE>
<HR>
<TABLE BORDER="0">
<TR><TH>Definition</TH><TD><code>#include <<A HREF="ktrader_h.html">ktrader.h</A>></code></TD></TR>
<TR><TH>Inherits</TH><TD><A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qobject.html">QObject</A> <small>(qt)</small> <small>[public ]</small></TD></TR>
<TR><TH><A HREF="full-list-KTrader.html">List of all Methods</A></TH></TR>
</TABLE>
</TD>
<TD align="right"><TABLE BORDER="0"><TR><TD><small><A HREF="index-long.html">Annotated List</A></small></TD></TR>
<TR><TD><small><A HREF="header-list.html">Files</A></small></TD></TR>
<TR><TD><small><A HREF="all-globals.html">Globals</A></small></TD></TR>
<TR><TD><small><A HREF="hier.html">Hierarchy</A></small></TD></TR>
<TR><TD><small><A HREF="index.html">Index</A></small></TD></TR>
</TABLE></TD></TR></TABLE>
<h4>Public Types</h4><ul><LI>typedef QValueList<KService::Ptr> <A HREF="#ref1">OfferList</A>
</LI>
</ul><h4>Public Methods</h4><ul><LI>virtual <b><A HREF="#ref2">~KTrader</A></b> ()
</LI>
<LI>virtual OfferList <b><A HREF="#ref3">query</A></b> ( const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& servicetype,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& constraint = QString::null,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& preferences = QString::null) const
</LI>
<LI>OfferList <b><A HREF="#ref4">query</A></b> ( const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& servicetype, const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& genericServiceType,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& constraint ,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& preferences ) const
</LI>
</ul><h4>Public Static Methods</h4><ul><LI>static <A HREF="KTrader.html">KTrader</A>* <b><A HREF="#ref5">self</A></b> ()
</LI>
</ul><h4>Protected Methods</h4><ul><LI> <b><A HREF="#ref6">KTrader</A></b> ()
</LI>
</ul><HR><H2><A NAME="longdesc">Detailed Description</A></H2><p>
A Trader interface, similar to the CORBA Trader.
</p>
<p> Basically, it provides a way for an application to query
all KDE services (that is, applications and components) that match
a specific set of requirements. This allows you to find an
application in real-time without you having to hard-code the name
and/or path of the application. It is mostly used when you want to
do complex queries that <A HREF="KServiceTypeProfile.html">KServiceTypeProfile</A> can't handle.
</p>
<p></p>
<H3>Examples
</H3>
<p>
</p>
<p> A few examples will make this a lot more clear.
</p>
<p> Say you have an application that will display HTML. In this
example, you don't want to link to khtml... and furthermore, you
really don't care if the HTML browser is ours or not, as long as
it works. The way that you formulate your query as well as the way
that you execute the browser depends on whether or not you want the
browser to run stand-alone or embedded.
</p>
<p> If you want the browser to run standalone, then you will limit the
query to search for all services that handle 'text/html' <em>and</em>,
furthermore, they must be applications (Type=Application). You
then will use <A HREF="KRun.html#run">KRun::run</A>() to invoke the application. In "trader-speak",
this looks like so:
</p><table border="0" width="100%">
<tr>
<td bgcolor="#BEEAE0">
<pre>
KTrader::OfferList offers = KTrader::self()-><A HREF="KTrader.html#query">query</A>("text/plain", "Type == 'Application'");
<A HREF="KService.html#Ptr">KService::Ptr</A> ptr = offers.first();
<A HREF="../kdecore/KURL__List.html">KURL::List</A> lst;
lst.append("http://www.kde.org/index.html");
<A HREF="KRun.html#run">KRun::run</A>(*ptr, lst);
</pre>
</td></tr>
</table> <p>
</p>
<p> It should be noted that in the above example, using
<A HREF="KServiceTypeProfile.html">KServiceTypeProfile</A> would be the better choice since you would
probably want the preferred service and the trader doesn't take
this into account. The trader does allow you to do more complex
things, though. Say, for instance, you want to only choose
Netscape. You can do it with the constraint: "(Type ==
'Application') and (Name == 'Netscape')"
</p>
<p> More the likely, though, you will only use the trader for such
things as finding components. In our continuing example, we say
that we want to load any KParts component that can handle HTML. We
will need to use the <A HREF="../kdecore/KLibFactory.html">KLibFactory</A> and <A HREF="../kdecore/KLibLoader.html">KLibLoader</A> to
actually do something with our query, then. Our code would look
like so:
</p><table border="0" width="100%">
<tr>
<td bgcolor="#BEEAE0">
<pre>
KTrader::OfferList offers = KTrader::self()-><A HREF="KTrader.html#query">query</A>("text/html", "'KParts/ReadOnlyPart' in ServiceTypes");
<A HREF="KService.html#Ptr">KService::Ptr</A> ptr = offers.first();
<A HREF="../kdecore/KLibFactory.html">KLibFactory</A> *factory = <A HREF="../kdecore/KLibLoader.html#self">KLibLoader::self</A>()->factory( ptr->library() );
if (factory)
part = static_cast<KParts::ReadOnlyPart *>(factory->create(this, ptr->name(), "KParts::ReadOnlyPart"));
</pre>
</td></tr>
</table> <p>
</p>
<p> Please note that when including property names containing arithmetic operators like - or +, then you have
to put brackets around the property name, in order to correctly separate arithmetic operations from
the name. So for example a constraint expression like
X-KDE-Blah < 4
needs to be written as
[X-KDE-Blah] < 4
otherwise it could also be interpreted as
Substract the numeric value of the property "KDE" and "Blah" from the property "X" and make sure it
is less than 4.
Instead of the other meaning, make sure that the numeric value of "X-KDE-Blah" is less than 4.
</p>
<p></p>
<A NAME="OfferList"></A><A NAME="ref1"></A><table width="100%"><tr bgcolor="#eeeeee"><td>typedef <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qvaluelist.html">QValueList</A><<A HREF="KService.html#Ptr">KService::Ptr</A>> <strong>OfferList</strong></td><td align="right"><h3><strong>OfferList</strong></h3></td></tr></table><p></p><p>
A list of services.
</p>
<A NAME="~KTrader"></A><A NAME="ref2"></A><table width="100%"><tr bgcolor="#eeeeee"><td> <strong>~KTrader</strong> ()
<br></td><td align="right"><h3><strong>~KTrader</strong></h3></td></tr></table><p> <small>[virtual]</small></p><p>
Standard destructor
</p>
<A NAME="query"></A><A NAME="ref3"></A><table width="100%"><tr bgcolor="#eeeeee"><td> OfferList <strong>query</strong> ( const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& servicetype,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& constraint = QString::null,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& preferences = QString::null)
<br></td><td align="right"><h3><strong>query</strong></h3></td></tr></table><p> <small>[const virtual]</small></p><p>
The main function in the KTrader class.
</p>
<p> It will return a list of services that match your
specifications. The only required parameter is the service
type. This is something like 'text/plain' or 'text/html'. The
constraint parameter is used to limit the possible choices
returned based on the constraints you give it.
</p>
<p> The constraint language is rather full. The most common
keywords are AND, OR, NOT, IN, and EXIST.. all used in an
almost spoken-word form. An example is:
</p><table border="0" width="100%">
<tr>
<td bgcolor="#BEEAE0">
<pre>
(Type == 'Service') and (('KPart::ReadOnlyPart in 'ServiceType') or (exist Exec))
</pre>
</td></tr>
</table> <p>
</p>
<p> The keys used in the query (Type, ServiceType, Exec) are all
fields found in the .desktop files.
</p>
<p></p>
<p></p>
<p><b>Parameters</b>:<TABLE BORDER="0" CELLPADDING="5">
<TR><TD align="left" valign="top"><i>servicetype</i></TD><TD align="left" valign="top">A service type like 'text/plain', 'text/html', or 'KOfficePlugin'.
</TD></TR>
<TR><TD align="left" valign="top"><i>constraint</i></TD><TD align="left" valign="top">A constraint to limit the choices returned.
</TD></TR>
<TR><TD align="left" valign="top"><i>preferences</i></TD><TD align="left" valign="top">Indicates a particular preference to return.
</TD></TR>
</TABLE></P>
<p><b>Returns</b>: A list of services that satisfy the query.
</p>
<A NAME="query"></A><A NAME="ref4"></A><table width="100%"><tr bgcolor="#eeeeee"><td>OfferList <strong>query</strong> ( const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& servicetype, const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& genericServiceType,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& constraint ,
const <A HREF="../../../../../../../../../usr/share/doc/qt-2.3.1/html/qstring.html">QString</A>& preferences )
<br></td><td align="right"><h3><strong>query</strong></h3></td></tr></table><p> <small>[const]</small></p><p>
A variant of query, that takes two service types as an input.
It is not exactly the same as adding the second service type
in the constraints of the other query call, because this one
takes into account user preferences for this combination of service types.
</p>
<p> Typically, this is used for getting the list of embeddable components
that can handle a given mimetype.
In that case, <code>servicetype</code> is the mimetype and <code>genericServiceType</code> is "KParts/ReadOnlyPart".
</p>
<A NAME="self"></A><A NAME="ref5"></A><table width="100%"><tr bgcolor="#eeeeee"><td> <A HREF="KTrader.html">KTrader</A>* <strong>self</strong> ()
<br></td><td align="right"><h3><strong>self</strong></h3></td></tr></table><p> <small>[static]</small></p><p>
This is a static pointer to a <A HREF="KTrader.html#KTrader">KTrader</A> instance.
</p>
<p> You will need
to use this to access the KTrader functionality since the
constuctors are protected.
</p>
<p></p>
<p><b>Returns</b>: Static KTrader instance
</p>
<A NAME="KTrader"></A><A NAME="ref6"></A><table width="100%"><tr bgcolor="#eeeeee"><td> <strong>KTrader</strong> ()
<br></td><td align="right"><h3><strong>KTrader</strong></h3></td></tr></table><p> <small>[protected]</small></p><p>
</p>
<HR><UL><LI><i>Author</i>: Torben Weis <weis@kde.org>
</LI><LI><i>Generated</i>: qateam on updates.mandrakesoft.com on Mon Dec 30 16:09:14 2002, using kdoc 2.0a53.</LI></UL></BODY></HTML>
