/* This file is part of the KDE libraries Copyright (C) 2000 Torben Weis This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License version 2 as published by the Free Software Foundation. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ #ifndef __ktrader_h__ #define __ktrader_h__ #include #include #include /** * A Trader interface, similar to the CORBA Trader. * * 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. * * \par Examples * * A few examples will make this a lot more clear. * * Say you have an application that will display HTML. In this * example, you don't want to link to tdehtml... 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. * * 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, * furthermore, they must be applications (Type=Application). You * then will use KRun::run() to invoke the application. In "trader-speak", * this looks like this: * \code * TDETrader::OfferList offers = TDETrader::self()->query("text/html", "Type == 'Application'"); * KService::Ptr ptr = offers.first(); * KURL::List lst; * lst.append("http://www.kde.org/index.html"); * KRun::run(*ptr, lst); * \endcode * * Now, say that you want to list all KParts component that can handle HTML. * \code * TDETrader::OfferList offers = TDETrader::self()->query("text/html", "KParts/ReadOnlyPart"); * \endcode * * If you want to get the preferred KParts component for text/html you could use * KServiceTypeProfile::preferredService("text/html", "KParts/ReadOnlyPart"), although if this is about * loading that component you would rather use KParts::ComponentFactory directly. * * * 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-TDE-Blah < 4 * needs to be written as * [X-TDE-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-TDE-Blah" is less than 4. * * See also the formal syntax defined in @ref tradersyntax . * * @short Provides a way to query the KDE infrastructure for specific * applications or components. * @author Torben Weis */ class TDEIO_EXPORT TDETrader : public TQObject { Q_OBJECT public: /** * A list of services. */ typedef TQValueList OfferList; typedef TQValueListIterator OfferListIterator; /** * Standard destructor */ virtual ~TDETrader(); /** * The main function in the TDETrader class. * * 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. * * The @p 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: * \code * (Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec)) * \endcode * * The keys used in the query (Type, ServiceType, Exec) are all * fields found in the .desktop files. * * @param servicetype A service type like 'text/plain', 'text/html', or 'KOfficePlugin'. * @param constraint A constraint to limit the choices returned, TQString::null to * get all services of the given @p servicetype * @param preferences Indicates a particular preference to return, TQString::null to ignore. * Uses an expression in the constraint language that must return * a number * * @return A list of services that satisfy the query * @see http://developer.kde.org/documentation/library/3.5-api/tdelibs-apidocs/tdeio/tdeio/html/tradersyntax.html */ virtual OfferList query( const TQString& servicetype, const TQString& constraint = TQString::null, const TQString& preferences = TQString::null) const; /** * 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. * * Example usage: * To get list of applications that can handle a given mimetype, * set @p servicetype to the mimetype and @p genericServiceType is "Application". * To get list of embeddable components that can handle a given mimetype, * set @p servicetype to the mimetype and @p genericServiceType is "KParts/ReadOnlyPart". * * @param servicetype A service type like 'text/plain', 'text/html', or 'KOfficePlugin'. * @param genericServiceType a basic service type, like 'KParts/ReadOnlyPart' or 'Application' * @param constraint A constraint to limit the choices returned, TQString::null to * get all services of the given @p servicetype * @param preferences Indicates a particular preference to return, TQString::null to ignore. * Uses an expression in the constraint language that must return * a number * * @return A list of services that satisfy the query * @see http://developer.kde.org/documentation/library/kdeqt/tradersyntax.html */ OfferList query( const TQString& servicetype, const TQString& genericServiceType, const TQString& constraint /*= TQString::null*/, const TQString& preferences /*= TQString::null*/) const; /** * This is a static pointer to a TDETrader instance. * * You will need * to use this to access the TDETrader functionality since the * constuctors are protected. * * @return Static TDETrader instance */ static TDETrader* self(); protected: /** * @internal */ TDETrader(); private: static TDETrader* s_self; protected: virtual void virtual_hook( int id, void* data ); }; /** @page tradersyntax Trader Syntax * * * @section Literals * * As elementary atoms of the constraint language, TDETrader supports * booleans, integers, floats and strings. Boolean literals are * @a TRUE and @a FALSE . Integers can be positive or negative, * i.e. @a 42 and @a -10 are legal values. Floating point * numbers are @a 3.141592535 or @a -999.999 . Scientific notation * like @a 1.5e-2 is not supported. Character literals are delimited * by single quotation marks, e.g. @a 'Bernd' . * * * @section Symbols * * Identifiers in query string are interpreted as property names, which * are listed in the service's .desktop file. For example, * Name is the name of the service, ServiceTypes is a * list of the service types it supports. Note that only properties can * be written as-is which start with an alphabetical character and contain * only alphanumerical characters. Other properties have to be enclosed in * brackets, e.g. [X-TDE-Init]. Properties must not contain any * special characters other than -. * * Special property names: * - DesktopEntryName stands for the filename of the service * desktop entry without any extension. This can be useful to * exclude some specific services. * - DesktopEntryPath stands for the relative or full path * to the .desktop file, see KService::desktopEntryPath. Mentionned * here for completeness, better not use it (things can be moved * around). * - Library is the property whose value is set by * X-TDE-Library in the .desktop file. This renaming * happened to conform to the desktop file standard, but the * property name didn't change. * * * @section Comparison * * Supported comparison operators are: * * - == * - != * - < * - <= * - > * - >= * * * @section Arithmetic Arithmetic and boolean expressions * * - + * - - * - * * - / * - and * - or * - not * * Note that the arithmetic operators are possible for integers and * floating point numbers. - is both a unary and binary operator, * not is a unary operator. * * * @section Other Other operators * * - ~ * - in * - exist * - () * * The tilde operator stands for a substring match. For example, * KParts ~ 'KParts/ReadOnlyPart' is TRUE. The membership * operator in tests whether a value is in a list. A list is a * string with semi-colon- or comma-separated entries, depending on the * type. An example for the membership operator is * 'text/plain' in ServiceTypes. * The exist tests whether a certain property is defined in the * .desktop file. Subexpressions are written in parentheses. * * Warning, testing the contents of a property only works if the property * is specified. There is not support for default values. If the property * might be missing, and you still want such services to be included, you * have to check for existence before testing it. For instance, to say * that MyProp is a boolean that defaults to true, and that you want the * services that have it set to true, use: * not exist MyProp or MyProp * Simply testing for MyProp would * exclude the services without the property at all. * * * @section Examples * * The following examples show filters for .desktop files. * Type, ServiceTypes and MimeType are * properties in .desktop files. Be aware that within TDETrader MimeType * properties are understood as ServiceTypes ones. * * * - Type == 'Application'@n * All services that are applications. * - 'KParts/ReadOnlyPart' in ServiceTypes@n * All read-only KParts. * - ('KParts/ReadOnlyPart' in ServiceTypes) and ('text/plain' in ServiceTypes)@n * All read-only KParts that handle the mime type 'text/plain'. * * @author Bernd Gehrmann bernd@kdevelop.org */ #endif