summaryrefslogtreecommitdiffstats
path: root/kjsembed/xmlactionclient.h
blob: 3f78fa3faf53348d8e781b43a5ba38f992d05099 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
// -*- c++ -*-

/*
 *  Copyright (C) 2002-2003, Richard J. Moore <rich@kde.org>
 *
 *  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 <tqobject.h>
#include <tqxml.h>
#include <tqmap.h>

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 TQObject
{
    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 = TTQString::null; }

	TTQString src;
	TTQString type;
	TTQString text;
    };

    /** Creates an XMLActionClient. */
    XMLActionClient( TTQObject *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 TTQString &filename );

    /** Loads actions from the named XML file. Returns true on success. */
    bool load( XMLActionHandler *handler, const TTQString &filename );

    /** Runs the named script. */
    bool run( const TTQString &name );

    /** Returns the named script. */
    XMLActionScript script( const TTQString &name ) const { return scripts[name]; }

    /** Calls XMLActionRunner::run(). */
    bool run( const XMLActionScript &script );

    /** Binds a name to a script. */
    virtual bool bind( const TTQString &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;
    TTQMap<TTQString, XMLActionScript> 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:
 * <pre>
 *    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)
 * </pre>
 *
 * 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 TQXmlDefaultHandler
{
public:
    XMLActionHandler( XMLActionClient *actclient );

    virtual bool startElement( const TTQString &ns, const TTQString &ln, const TTQString &qn,
			       const TTQXmlAttributes &attrs );
    virtual bool endElement( const TTQString &ns, const TTQString &ln, const TTQString &qn );
    virtual bool characters( const TTQString &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 = TTQString::null;
	    exclusive = false;
	    script.clear();
	}

	TTQString type;
	TTQString text;
	TTQString icons;
	TTQString keys;
	TTQString name;
	TTQString group;
	bool exclusive;
	TTQString status;
	TTQString whatsthis;
	XMLActionClient::XMLActionScript script;
	TTQStringList items;
    };

    XMLActionData *actionData() { return &ad; }

private:
    XMLActionClient *actclient;
    TTQString cdata;
    bool inAction;
    XMLActionData ad;
    class XMLActionHandlerPrivate *d;
};

} // namespace KJSEmbed

#endif // XMLACTIONCLIENT_H