/* This file is part of the KDE project Copyright (C) 1998, 1999, 2000 Torben Weis Copyright (C) 2001 David Faure This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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 KDATATOOL_H #define KDATATOOL_H #include #include #include #include class KDataTool; class TQPixmap; class TQStringList; class KInstance; // If you're only looking at implementing a data-tool, skip directly to the last // class definition, KDataTool. /** * This is a convenience class for KService. You can use it if you have * a KService describing a KDataTool. In this case the KDataToolInfo class * is more convenient to work with. * * Especially useful is the method createTool which creates the datatool * described by the service. * @see KDataTool */ class KIO_EXPORT KDataToolInfo { public: /** * Create an invalid KDataToolInfo. */ KDataToolInfo(); /** * Create a valid KDataToolInfo. * @param service the corresponding service * @param instance the instance to use */ KDataToolInfo( const KService::Ptr& service, KInstance* instance ); /** * Copy constructor. */ KDataToolInfo( const KDataToolInfo& info ); /** * Assignment operator. */ KDataToolInfo& operator= ( const KDataToolInfo& info ); /** * Returns the data type that the DataTool can accept. * @return the C++ data type that this DataTool accepts. * For example "TQString" or "TQImage" or something more * complicated. */ TQString dataType() const; /** * Returns a list of mime type that will be accepted by the DataTool. * The mimetypes are only used if the dataType can be used to store * different mimetypes. For example in a "TQString" you could save "text/plain" * or "text/html" or "text/xml". * * @return the mime types accepted by this DataTool. For example * "image/gif" or "text/plain". In some cases the dataType * determines the accepted type of data perfectly. In this cases * this list may be empty. */ TQStringList mimeTypes() const; /** * Checks whether the DataTool is read-only. * @return true if the DataTool does not modify the data passed to it by KDataTool::run. */ bool isReadOnly() const; /** * Returns the icon of this data tool. * @return a large pixmap for the DataTool. * @deprecated, use iconName() */ TQPixmap icon() const KDE_DEPRECATED; /** * Returns the mini icon of this data tool. * @return a mini pixmap for the DataTool. * @deprecated, use iconName() */ TQPixmap miniIcon() const KDE_DEPRECATED; /** * Returns the icon name for this DataTool. * @return the name of the icon for the DataTool */ TQString iconName() const; /** * Returns a list of strings that you can put in a TQPopupMenu item, for example to * offer the DataTools services to the user. The returned value * is usually something like "Spell checking", "Shrink Image", "Rotate Image" * or something like that. * This list comes from the Comment field of the tool's desktop file * (so that it can be translated). * * Each of the strings returned corresponds to a string in the list returned by * commands. * * @return a list of strings that you can put in a TQPopupMenu item */ TQStringList userCommands() const; /** * Returns the list of commands the DataTool can execute. The application * passes the command to the KDataTool::run method. * * This list comes from the Commands field of the tool's desktop file. * * Each of the strings returned corresponds to a string in the list returned by * userCommands. * @return the list of commands the DataTool can execute, suitable for * the KDataTool::run method. */ TQStringList commands() const; /** * Creates the data tool described by this KDataToolInfo. * @param parent the parent of the TQObject (or 0 for parent-less KDataTools) * @param name the name of the TQObject, can be 0 * @return a pointer to the created data tool or 0 on error. */ KDataTool* createTool( TQObject* parent = 0, const char* name = 0 ) const; /** * The KDataToolInfo's service that is represented by this class. * @return the service */ KService::Ptr service() const; /** * The instance of the service. * @return the instance */ KInstance* instance() const { return m_instance; } /** * A DataToolInfo may be invalid if the KService passed to its constructor does * not feature the service type "KDataTool". * @return true if valid, false otherwise */ bool isValid() const; /** * Queries the KTrader about installed KDataTool implementations. * @param datatype a type that the application can 'export' to the tools (e.g. TQString) * @param mimetype the mimetype of the data (e.g. text/plain) * @param instance the application (or the part)'s instance (to check if a tool is excluded from this part, * and also used if the tool wants to read its configuration in the app's config file). * @return the list of results */ static TQValueList query( const TQString& datatype, const TQString& mimetype, KInstance * instance ); private: KService::Ptr m_service; KInstance* m_instance; private: class KDataToolInfoPrivate* d; }; /** * This class helps applications implement support for KDataTool. * The steps to follow are simple: * @li query for the available tools using KDataToolInfo::query * @li pass the result to KDataToolAction::dataToolActionList (with a slot) * @li plug the resulting actions, either using KXMLGUIClient::plugActionList, or by hand. * * The slot defined for step 2 is called when the action is activated, and * that's where the tool should be created and run. */ class KIO_EXPORT KDataToolAction : public KAction { Q_OBJECT public: /** * Constructs a new KDataToolAction. * * @param text The text that will be displayed. * @param info the corresponding KDataToolInfo * @param command the command of the action * @param parent This action's parent. * @param name An internal name for this action. */ KDataToolAction( const TQString & text, const KDataToolInfo & info, const TQString & command, TQObject * parent = 0, const char * name = 0); /** * Creates a list of actions from a list of information about data-tools. * The slot must have a signature corresponding to the toolActivated signal. * * Note that it's the caller's responsibility to delete the actions when they're not needed anymore. * @param tools the list of data tool descriptions * @param receiver the receiver for toolActivated() signals * @param slot the slot that will receive the toolActivated() signals * @return the KActions */ static TQPtrList dataToolActionList( const TQValueList & tools, const TQObject *receiver, const char* slot ); signals: /** * Emitted when a tool has been activated. * @param info a description of the activated tools * @param command the command for the tool */ void toolActivated( const KDataToolInfo & info, const TQString & command ); protected: virtual void slotActivated(); private: TQString m_command; KDataToolInfo m_info; protected: virtual void virtual_hook( int id, void* data ); private: class KDataToolActionPrivate* d; }; /** * A generic tool that processes data. * * A data-tool is a "plugin" for an application, that acts (reads/modifies) * on a portion of the data present in the document (e.g. a text document, * a single word or paragraph, a KSpread cell, an image, etc.) * * The application has some generic code for presenting the tools in a popupmenu * @see KDataToolAction, and for activating a tool, passing it the data * (and possibly getting modified data from it). */ class KIO_EXPORT KDataTool : public TQObject { Q_OBJECT public: /** * Constructor * The data-tool is only created when a menu-item, that relates to it, is activated. * @param parent the parent of the TQObject (or 0 for parent-less KDataTools) * @param name the name of the TQObject, can be 0 */ KDataTool( TQObject* parent = 0, const char* name = 0 ); /** * @internal. Do not use under any circumstance (including bad weather). */ void setInstance( KInstance* instance ) { m_instance = instance; } /** * Returns the instance of the part that created this tool. * Usually used if the tool wants to read its configuration in the app's config file. * @return the instance of the part that created this tool. */ KInstance* instance() const; /** * Interface for 'running' this tool. * This is the method that the data-tool must implement. * * @param command is the command that was selected (see KDataToolInfo::commands()) * @param data the data provided by the application, on which to run the tool. * The application is responsible for setting that data before running the tool, * and for getting it back and updating itself with it, after the tool ran. * @param datatype defines the type of @p data. * @param mimetype defines the mimetype of the data (for instance datatype may be * TQString, but the mimetype can be text/plain, text/html etc.) * @return true if successful, false otherwise */ virtual bool run( const TQString& command, void* data, const TQString& datatype, const TQString& mimetype) = 0; private: KInstance * m_instance; protected: virtual void virtual_hook( int id, void* data ); private: class KDataToolPrivate; KDataToolPrivate * d; }; #endif