summaryrefslogtreecommitdiffstats
path: root/libkdegames/kgame/kgamepropertyhandler.h
blob: 29a57cf1d2a4b3163b740186ea0efc64b05d6bb9 (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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
/*
    This file is part of the KDE games library
    Copyright (C) 2001 Andreas Beckermann (b_mann@gmx.de)
    Copyright (C) 2001 Martin Heni (martin@heni-online.de)

    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 __KGAMEPROPERTYHANDLER_H_
#define __KGAMEPROPERTYHANDLER_H_

#include <tqobject.h>
#include <tqintdict.h>

#include "kgameproperty.h"
#include <kdemacros.h>

class TQDataStream;
class KGame;
class KPlayer;
//class KGamePropertyBase;

class KGamePropertyHandlerPrivate; // wow - what a name ;-)

/**
 * @short A collection class for KGameProperty objects
 *
 * The KGamePropertyHandler class is some kind of a collection class for
 * KGameProperty. You usually don't have to create one yourself, as both
 * KPlayer and KGame provide a handler. In most cases you do not even have
 * to care about the KGamePropertHandler. KGame and KPlayer implement
 * all features of KGamePropertyHandler so you will rather use it there.
 *
 * You have to use the KGamePropertyHandler as parent for all KGameProperty
 * objects but you can also use KPlayer or KGame as parent - then
 * KPlayer::dataHandler or KGame::dataHandler will be used. 
 *
 * Every KGamePropertyHandler must have - just like every KGameProperty -
 * a unique ID. This ID is provided either in the constructor or in
 * registerHandler. The ID is used to assign an incoming message (e.g. a changed
 * property) to the correct handler. Inside the handler the property ID is used
 * to change the correct property. 
 *
 * The constructor or registerHandler takes 3 addittional arguments: a
 * receiver and two slots. The first slot is connected to
 * signalSendMessage, the second to signalPropertyChanged. You must provide
 * these in order to use the KGamePropertyHandler. 
 *
 * The most important function of KGamePropertyHandler is processMessage
 * which assigns an incoming value to the correct property. 
 *
 * A KGamePropertyHandler is also used - indirectly using emitSignal - to
 * emit a signal when the value of a property changes. This is done this way
 * because a KGameProperty does not inherit TQObject because of memory
 * advantages. Many games can have dozens or even hundreds of KGameProperty
 * objects so every additional variable in KGameProperty would be
 * multiplied. 
 *
 **/
class KDE_EXPORT KGamePropertyHandler : public QObject
{
	Q_OBJECT

public:
	/**
	 * Construct an unregistered KGamePropertyHandler
	 *
	 * You have to call registerHandler before you can use this
	 * handler!
	 **/
	KGamePropertyHandler(TQObject* parent = 0);

	/**
	 * Construct a registered handler. 
	 *
	 * @see registerHandler
	 **/
	KGamePropertyHandler(int id, const TQObject* receiver, const char* sendf, const char* emitf, TQObject* parent = 0);
	~KGamePropertyHandler();

	/**
	 * Register the handler with a parent. This is to use
	 * if the constructor without arguments has been chosen.
	 * Otherwise you need not call this.
	 *
	 * @param id The id of the message to listen for
	 * @param receiver The object that will receive the signals of
	 * KGamePropertyHandler
	 * @param send A slot that is being connected to signalSendMessage
	 * @param emit A slot that is being connected to signalPropertyChanged
	 **/
	void registerHandler(int id, const TQObject *receiver, const char * send, const char *emit); 

	/**
	 * Main message process function. This has to be called by
	 * the parent's message event handler. If the id of the message
	 * agrees with the id of the handler, the message is extracted 
	 * and processed. Otherwise false is returned.
	 * Example:
	 * \code
	 *   if (mProperties.processMessage(stream,msgid,sender==gameId())) return ;
	 * \endcode
	 * 
	 * @param stream The data stream containing the message
	 * @param id the message id of the message
	 * @param isSender Whether the receiver is also the sender
	 * @return true on message processed otherwise false
	 **/
	bool processMessage(TQDataStream &stream, int id, bool isSender );
	
	/**
	 * @return the id of the handler
	 **/
	int id() const;
	
	/**
	 * Adds a KGameProperty property to the handler
	 * @param data the property
	 * @param name A description of the property, which will be returned by
	 * propertyName. This is used for debugging, e.g. in KGameDebugDialog
	 * @return true on success
	 **/
	bool addProperty(KGamePropertyBase *data, TQString name=0);

	/**
	 * Removes a property from the handler
	 * @param data the property
	 * @return true on success
	 **/
	bool removeProperty(KGamePropertyBase *data);

	/**
	 * returns a unique property ID starting called usually with a base of
	 * KGamePropertyBase::IdAutomatic. This is used internally by
	 * the property base to assign automtic id's. Not much need to
	 * call this yourself.
	 **/
	int uniquePropertyId();


	/**
	 * Loads properties from the datastream
	 *
	 * @param stream the datastream to load from
	 * @return true on success otherwise false
	 **/
	virtual bool load(TQDataStream &stream);

	/**
	 * Saves properties into the datastream
	 *
	 * @param stream the datastream to save to
	 * @return true on success otherwise false
	 **/
	virtual bool save(TQDataStream &stream);
	
	/**
	 * called by a property to send itself into the
	 * datastream. This call is simply forwarded to
	 * the parent object
	 **/ 
	bool sendProperty(TQDataStream &s);

	void sendLocked(bool l);

	/**
	 * called by a property to emit a signal 
	 * This call is simply forwarded to
	 * the parent object
	 **/ 
	void emitSignal(KGamePropertyBase *data);

	/**
	 * @param id The ID of the property
	 * @return A name of the property which can be used for debugging. Don't
	 * depend on this function! It it possible not to provide a name or to
	 * provide the same name for multiple properties!
	 **/
	TQString propertyName(int id) const;

	/**
	 * @param id The ID of the property. See KGamePropertyBase::id
	 * @return The KGameProperty this ID is assigned to
	 **/
	KGamePropertyBase *find(int id);

	/**
	 * Clear the KGamePropertyHandler. Note that the properties are
	 * <em>not</em> deleted so if you created your KGameProperty
	 * objects dynamically like
	 * \code
	 * KGamePropertyInt* myProperty = new KGamePropertyInt(id, dataHandler());
	 * \endcode
	 * you also have to delete it:
	 * \code
	 * dataHandler()->clear();
	 * delete myProperty;
	 * \endcode
	 **/
	void clear();

	/**
	 * Use id as new ID for this KGamePropertyHandler. This is used
	 * internally only.
	 **/
	void setId(int id);//AB: TODO: make this protected in KGamePropertyHandler!!

	/**
	 * Calls KGamePropertyBase::setReadOnly(false) for all properties of this
	 * player. See also lockProperties
	 **/
	void unlockProperties();

	/**
	 * Set the policy for all kgame variables which are currently registerd in
	 * the KGame proeprty handler. See KGamePropertyBase::setPolicy
	 *
	 * @param p is the new policy for all properties of this handler
	 * @param userspace if userspace is true (default) only user properties are changed.
	 * Otherwise the system properties are also changed.
	 **/
	void setPolicy(KGamePropertyBase::PropertyPolicy p, bool userspace=true);

	/**
	 * Called by the KGame or KPlayer object or the handler itself to delay
	 * emmiting of signals. Lockign keeps a counter and unlock is only achieved
	 * when every lock is canceld by an unlock.
	 * While this is set signals are  quequed and only emmited after this
	 * is reset. Its deeper meaning is to prevent inconsistencies in a game
	 * load or network transfer where a emit could access a property not
	 * yet loaded or transmitted. Calling this by yourself you better know
	 * what your are doing.
	 **/
	void lockDirectEmit();

	/**
	 * Removes the lock from the emitting of property signals. Corresponds to
	 * the lockIndirectEmits
	 **/
	void unlockDirectEmit();
  
	/**
	 * Returns the default policy for this property handler. All properties
	 * registered newly, will have this property.
	 **/
	KGamePropertyBase::PropertyPolicy policy();

	/**
	 * Calls KGamePropertyBase::setReadOnly(true) for all properties of this
	 * handler
	 *
	 * Use with care! This will even lock the core properties, like name,
	 * group and myTurn!!
	 *
	 * @see unlockProperties
	 **/
	void lockProperties();

	/**
	 * Sends all properties which are marked dirty over the network. This will
	 * make a forced synchornisation of the properties and mark them all not dirty.
	 **/
	void flush();

	/**
	 * Reference to the internal dictionary
	 **/
	TQIntDict<KGamePropertyBase> &dict() const;

	/**
	 * In several situations you just want to have a TQString of a
	 * KGameProperty object. This is the case in the 
	 * KGameDebugDialog where the value of all properties is displayed. This
	 * function will provide you with such a TQString for all the types
	 * used inside of all KGame classes. If you have a non-standard
	 * property (probably a self defined class or something like this) you
	 * also need to connect to signalRequestValue to make this function
	 * useful.
	 * @param property Return the value of this KGameProperty 
	 * @return The value of a KGameProperty
	 **/
	TQString propertyValue(KGamePropertyBase* property);


	/**
	 * Writes some debug output to the console.
	 **/ 
	void Debug();


signals:
	/**
	 * This is emitted by a property. KGamePropertyBase::emitSignal
	 * calls emitSignal which emits this signal. 
	 *
	 * This signal is emitted whenever the property is changed. Note that
	 * you can switch off this behaviour using 
	 * KGamePropertyBase::setEmittingSignal in favor of performance. Note
	 * that you won't experience any performance loss using signals unless
	 * you use dozens or hundreds of properties which change very often.
	 **/
	void signalPropertyChanged(KGamePropertyBase *);

	/**
	 * This signal is emitted when a property needs to be sent. Only the
	 * parent has to react to this.
	 * @param msgid The id of the handler
	 * @param sent set this to true if the property was sent successfully -
	 * otherwise don't touch
	 **/
	void signalSendMessage(int msgid, TQDataStream &, bool* sent); // AB shall we change bool* into bool& again?

	/**
	 * If you call propertyValue with a non-standard KGameProperty
	 * it is possible that the value cannot automatically be converted into a
	 * TQString. Then this signal is emitted and asks you to provide the
	 * correct value. You probably want to use something like this to achieve
	 * this:
	 * \code
	 * #include <typeinfo>
	 * void slotRequestValue(KGamePropertyBase* p, TQString& value)
	 * {
	 * 	if (*(p->typeinfo()) == typeid(MyType) {
	 * 		value = TQString(((KGameProperty<MyType>*)p)->value());
	 * 	}
	 * }
	 * \endcode
	 *
	 * @param property The KGamePropertyBase the value is requested for
	 * @param value The value of this property. You have to set this.
	 **/
	void signalRequestValue(KGamePropertyBase* property, TQString& value);

private:
	void init();

private:
	KGamePropertyHandlerPrivate* d;
};

#endif