// -*- c++ -*- /* * Copyright (C) 2002-2003, Richard J. Moore * * 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 XMLACTIONCLIENT_H #define XMLACTIONCLIENT_H #include #include #include class KActionCollection; class KAction; namespace KJSEmbed { class XMLActionHandler; class XMLActionRunner; class XMLActionScript; /** * Loads actions from an XML file using SAX. * * @author Richard Moore, rich@kde.org */ class XMLActionClient : public QObject { Q_OBJECT public: /** * Represents a script. */ struct XMLActionScript { XMLActionScript() {} XMLActionScript( const XMLActionScript &self ) : src(self.src), type(self.type), text(self.text) {} ~XMLActionScript() {} /** Returns true iff this instance holds a valid script. */ bool isValid() const { return !type.isEmpty(); } /** * Clears this script object. After this method has been called, * isValid() will return false. */ void clear() { src = type = text = QString::null; } QString src; QString type; QString text; }; /** Creates an XMLActionClient. */ XMLActionClient( QObject *parent=0, const char *name=0 ); /** * Cleans up. When the object is deleted, any actions it has created will * also be deleted. */ virtual ~XMLActionClient(); /** Returns the KActionCollection that the actions will be added to. */ KActionCollection *actionCollection() const { return ac; } /** Sets the KActionCollection that the actions will be added to. */ void setActionCollection( KActionCollection *acts ) { ac = acts; } /** Returns the runner for this XMLActionClient. */ XMLActionRunner *runner() const { return actrun; } /** Sets the runner for this XMLActionClient. */ void setRunner( XMLActionRunner *r ) { actrun = r; } /** Loads actions from the named XML file. Returns true on success. */ bool load( const QString &filename ); /** Loads actions from the named XML file. Returns true on success. */ bool load( XMLActionHandler *handler, const QString &filename ); /** Runs the named script. */ bool run( const QString &name ); /** Returns the named script. */ XMLActionScript script( const QString &name ) const { return scripts[name]; } /** Calls XMLActionRunner::run(). */ bool run( const XMLActionScript &script ); /** Binds a name to a script. */ virtual bool bind( const QString &name, const XMLActionScript &script ); /** Binds an action to a script. */ virtual bool bind( KAction *act, const XMLActionScript &script ); protected slots: /** * Called when a bound action is activated to invoke the script with the * sender's name. */ void action_activated(); private: KActionCollection *ac; XMLActionRunner *actrun; QMap scripts; class XMLActionClientPrivate *d; }; /** * Abstract class implemented by classes that can run scripts. * * @see XMLActionClient * @author Richard Moore, rich@kde.org */ class XMLActionRunner { public: /** * This method should be reimplemented to execute the specified script. * * @return true if the script was executed successfully, false otherwise. */ virtual bool run( XMLActionClient *client, const XMLActionClient::XMLActionScript &script ); }; /** * SAX handler for loading actions from XML. * * The following tags are supported: *
 *    actionset ( header? action* )
 *    header ( name | label | icons | script )
 *    action ( (header | name | label | icons | shortcut | group | 
 *              whatsthis | statustext | type | script | data)+ )
 *    type ( #CDATA )
 *    label ( #CDATA | text )
 *    icons ( #CDATA )
 *    shortcut ( #CDATA | text )
 *    whatsthis ( #CDATA | text )
 *    group ( #CDATA )
 *        exclusive    defaults to false
 *    name ( #CDATA )
 *    text ( #CDATA )
 *    data ( item+ )
 *    item ( #CDATA | text )
 *    script ( #CDATA )
 *        type    type of script
 *        src     url of script file (optional)
 * 
* * Unknown tags are ignored, so subclasses can define new ones if they * want to store additional data. * * @author Richard Moore, rich@kde.org */ class XMLActionHandler : public QXmlDefaultHandler { public: XMLActionHandler( XMLActionClient *actclient ); virtual bool startElement( const QString &ns, const QString &ln, const QString &qn, const QXmlAttributes &attrs ); virtual bool endElement( const QString &ns, const QString &ln, const QString &qn ); virtual bool characters( const QString &chars ); /** Called when an action tag is closed. */ void defineAction(); XMLActionClient *client() const { return actclient; } /** Creates a KAction based on the values read from the XML. */ virtual KAction *createAction( KActionCollection *parent ); private: /** * Structure containing information gathered about an action. */ struct XMLActionData { XMLActionData() { clear(); } void clear() { text = icons = keys = name = group = whatsthis = status = QString::null; exclusive = false; script.clear(); } QString type; QString text; QString icons; QString keys; QString name; QString group; bool exclusive; QString status; QString whatsthis; XMLActionClient::XMLActionScript script; QStringList items; }; XMLActionData *actionData() { return &ad; } private: XMLActionClient *actclient; QString cdata; bool inAction; XMLActionData ad; class XMLActionHandlerPrivate *d; }; } // namespace KJSEmbed #endif // XMLACTIONCLIENT_H