summaryrefslogtreecommitdiffstats
path: root/libtdegames/kgame/kgameproperty.h
blob: f02c4db0815d2c289f7b903b778c390d4fd66b43 (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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
/*
    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 __KGAMEPROPERTY_H_
#define __KGAMEPROPERTY_H_

#include <tqdatastream.h>

#include <kdebug.h>
#include <typeinfo>
#include <kdemacros.h>
class KGame;
class KPlayer;
class KGamePropertyHandler;
using namespace std;

/**
 * @short Base class of KGameProperty
 *
 * The KGamePropertyBase class is the base class of KGameProperty. See
 * KGameProperty for further information.
 * 
 * @author Andreas Beckermann <b_mann@gmx.de>
 **/
class KDE_EXPORT KGamePropertyBase
{
public:
	enum PropertyDataIds  { // these belong to KPlayer/KGame!
		//KPlayer
		IdGroup=1,
		IdUserId=2,
		IdAsyncInput=3,
		IdTurn=4,
		IdName=5,

		//KGame
		IdGametqStatus=6,
		IdMaxPlayer=7,
		IdMinPlayer=8,

    // Input Grabbing
    IdGrabInput=16,
    IdReleaseInput=17,

		IdCommand, // Reserved for internal use
		IdUser=256,

		IdAutomatic=0x7000  // Id's from here on are automatically given (16bit)
	};

	/**
	 * Commands for advanced properties (TQ_INT8)
	 **/
	enum PropertyCommandIds 
	{
		// General
		CmdLock=1,
		
		// Array
		CmdAt=51,
		CmdResize=52,
		CmdFill=53,
		CmdSort=54,
		// List (could be the same id's actually)
		CmdInsert=61,
		CmdAppend=62,
		CmdRemove=63,
		CmdClear=64
	};

	/**
	 * The policy of the property. This can be PolicyClean (setValue uses
	 * send), PolicyDirty (setValue uses changeValue) or
	 * PolicyLocal (setValue uses setLocal).
	 *
	 * A "clean" policy means that the property is always the same on every
	 * client. This is achieved by calling send which actually changes
	 * the value only when the message from the MessageServer is received.
	 *
	 * A "dirty" policy means that as soon as setValue is called the
	 * property is changed immediately. And additionally sent over network.
	 * This can sometimes lead to bugs as the other clients do not 
	 * immediately have the same value. For more information see 
	 * changeValue.
	 *
	 * PolicyLocal means that a KGameProperty behaves like ever
	 * "normal" variable. Whenever setValue is called (e.g. using "=")
	 * the value of the property is changes immediately without sending it
	 * over network. You might want to use this if you are sure that all
	 * clients set the property at the same time.
	 **/
	enum PropertyPolicy
	{
		PolicyUndefined = 0,
		PolicyClean = 1,
		PolicyDirty = 2,
		PolicyLocal = 3
	};


	/**
	 * Constructs a KGamePropertyBase object and calls registerData.
	 * @param id The id of this property. MUST be UNITQUE! Used to send and
	 * receive changes in the property of the playere automatically via
	 * network. 
	 * @param owner The owner of the object. Must be a KGamePropertyHandler which manages
	 * the changes made to this object, i.e. which will send the new data
	 **/
	KGamePropertyBase(int id, KGamePropertyHandler* owner);

	KGamePropertyBase(int id, KGame* parent);
	KGamePropertyBase(int id, KPlayer* parent);

	/**
	 * Creates a KGamePropertyBase object without an owner. Remember to call
	 * registerData!
	 **/
	KGamePropertyBase();

	virtual ~KGamePropertyBase();

	/**
	 * Changes the consistency policy of a property. The  
	 * PropertyPolicy is one of PolicyClean (defaulz), PolicyDirty or PolicyLocal.
	 *
	 * It is up to you to decide how you want to work. 
	 **/
	void setPolicy(PropertyPolicy p) { mFlags.bits.policy = p; } 

	/**
	 * @return The default policy of the property
	 **/
	PropertyPolicy policy() const { return (PropertyPolicy)mFlags.bits.policy; }

	/**
	 * Sets this property to emit a signal on value changed.
	 * As the proerties do not inehrit TQObject for optimisation
	 * this signal is emited via the KPlayer or KGame object
	 **/
	void setEmittingSignal(bool p)	{ mFlags.bits.emitsignal=p; }

	/**
	 * See also setEmittingSignal
	 * @return Whether this property emits a signal on value change
	 **/
	bool isEmittingSignal()	const { return mFlags.bits.emitsignal; }

	/**
	 * Sets this property to try to optimize signal and network handling
	 * by not sending it out when the property value is not changed.
	 **/
	void setOptimized(bool p) { mFlags.bits.optimize = p ; }

	/**
	 * See also setOptimize
	 * @return Whether the property optimizes access (signals,network traffic)
	 **/
	bool isOptimized() const { return mFlags.bits.optimize; }

	/**
	 * @return Whether this property is "dirty". See also setDirty
	 **/
	bool isDirty() const { return mFlags.bits.dirty; }

	/**
	 * A locked property can only be changed by the player who has set the
	 * lock. See also setLocked
	 * @return Whether this property is currently locked. 
	 **/
	bool isLocked() const { return mFlags.bits.locked; }

	/**
	 * A locked property can only be changed by the player who has set the
	 * lock.
	 *
	 * You can only call this if isLocked is false. A message is sent
	 * over network so that the property is locked for all players except
	 * you.
	 *
	 * @return returns false if the property can not be locked, i.e. it is already locked
	 *
	 **/
	bool lock();

	/**
	 * A locked property can only be changed by the player who has set the
	 * lock.
	 *
	 * You can only call this if isLocked is false. A message is sent
	 * over network so that the property is locked for all players except
	 * you.
	 *
	 * @return returns false if the property can not be locked, i.e. it is already locked
	 *
	 **/
	bool unlock(bool force=false);

	/**
	 * This will read the value of this property from the stream. You MUST
	 * overwrite this method in order to use this class
	 * @param s The stream to read from
	 **/
	virtual void load(TQDataStream& s) = 0;

	/**
	 * Write the value into a stream. MUST be overwritten
	 **/
	virtual void save(TQDataStream& s) = 0;

	/** 
	 * send a command to advanced properties like arrays
	 * @param stream The stream containing the data of the comand
	 * @param msgid The ID of the command - see PropertyCommandIds
	 * @param isSender whether this client is also the sender of the command
	 **/
	virtual void command(TQDataStream &stream, int msgid, bool isSender=false);

	/**
	 * @return The id of this property
	 **/
	int id() const { return mId; }

	/**
	 * @return a type_info of the data this property contains. This is used
	 * e.g. by KGameDebugDialog
	 **/
	virtual const type_info* typeinfo() { return &typeid(this); }

	/**
	 * You have to register a KGamePropertyBase before you can use it.
	 *
	 * You MUST call this before you can use KGamePropertyBase!
	 *
	 * @param id the id of this KGamePropertyBase object. The id MUST be
	 * unique, i.e. you cannot have two properties with the same id for one
	 * player, although (currently) nothing prevents you from doing so. But
	 * you will get strange results!
	 *
	 * @param owner The owner of this data. This will send the data
	 * using KPropertyHandler::sendProperty whenever you call send
	 *
	 * @param p If not 0 you can set the policy of the property here
	 *
	 * @param name if not 0 you can assign a name to this property
	 *
	 **/
	int registerData(int id, KGamePropertyHandler* owner,PropertyPolicy p, TQString name=0);

	/** 
	 * This is an overloaded member function, provided for convenience.
	 * It differs from the above function only in what argument(s) it accepts.
	 **/
	int registerData(int id, KGamePropertyHandler* owner, TQString name=0);

	/** 
	 * This is an overloaded member function, provided for convenience.
	 * It differs from the above function only in what argument(s) it accepts.
	 **/
	int registerData(int id, KGame* owner, TQString name=0);

	/** 
	 * This is an overloaded member function, provided for convenience.
	 * It differs from the above function only in what argument(s) it accepts.
	 **/
	int registerData(int id, KPlayer* owner, TQString name=0);

	/** 
	 * This is an overloaded member function, provided for convenience.
	 * It differs from the above function only in what argument(s) it accepts.
	 * In particular you can use this function to create properties which
	 * will have an automatic id assigned. The new id is returned.
	 **/
	int registerData(KGamePropertyHandler* owner,PropertyPolicy p=PolicyUndefined, TQString name=0);

	void unregisterData();

 
protected:
	/**
	 * A locked property can only be changed by the player who has set the
	 * lock.
	 *
	 * You can only call this if isLocked is false. A message is sent
	 * over network so that the property is locked for all players except
	 * you. 
	 * Usually you use lock and unlock to access this property
	 *
	 **/
	void setLock(bool l);

	/**
	 * Sets the "dirty" flag of the property. If a property is "dirty" i.e.
	 * KGameProperty::setLocal has been called there is no guarantee
	 * that all clients share the same value. You have to ensure this
	 * yourself e.g. by calling KGameProperty::setLocal on every
	 * client. You can also ignore the dirty flag and continue working withe
	 * the property depending on your situation.
	 **/
	void setDirty(bool d) { mFlags.bits.dirty = d ; }

	/**
	 * Forward the data to the owner of this property which then sends it
	 * over network. save is used to store the data into a stream so
	 * you have to make sure that function is working properly if you
	 * implement your own property!
	 *
	 * Note: this sends the <em>current</em> property!
	 *
	 * Might be obsolete - KGamePropertyArray still uses it. Is this a bug
	 * or correct?
	 **/
	bool sendProperty();
	
	/**
	 * Forward the data to the owner of this property which then sends it
	 * over network. save is used to store the data into a stream so
	 * you have to make sure that function is working properly if you
	 * implement your own property!
	 *
	 * This function is used by send to send the data over network.
	 * This does <em>not</em> send the current value but the explicitly
	 * given value. 
	 *
	 * @return TRUE if the message could be sent successfully, otherwise
	 * FALSE
	 **/
	bool sendProperty(const TQByteArray& b);
	
	/**
	 * Causes the parent object to emit a signal on value change
	 **/
	void emitSignal();

protected:
	KGamePropertyHandler* mOwner;
	
	// Having this as a union of the bitfield and the char
	// allows us to stream this quantity easily (if we need to)
	// At the moment it is not yet transmitted
	union Flags {
		char flag;
		struct {
			// unsigned char dosave : 1;   // do save this property
			// unsigned char delaytransmit : 1;   // do not send immediately on
                                             // change but a KPlayer:TQTimer
                                             // sends it later on - fast
                                             // changing variables
			unsigned char emitsignal : 1; // KPlayer notifies on variable change (true)
			//unsigned char readonly : 1; // whether the property can be changed (false)
			unsigned char optimize : 1; // whether the property tries to optimize send/emit (false)
			unsigned char dirty: 1; // whether the property dirty (setLocal() was used)
			unsigned char policy : 2; // whether the property is always consistent (see PropertyPolicy)
			unsigned char locked: 1; // whether the property is locked (true)
		} bits;
	} mFlags;
	
private:
	friend class KGamePropertyHandler;
	void init();
	
private:
	int mId;

};

/**
 * @short A class for network transparent games
 *
 * Note: The entire API documentation is obsolete!
 * 
 * The class KGameProperty can store any form of data and will transmit it via
 * network whenver you call send. This makes network transparent games
 * very easy. You first have to register the data to a KGamePropertyHandler
 * using KGamePropertyBase::registerData (which is called by the
 * constructor). For the KGamePropertyHandler you can use
 * KGame::dataHandler or KPlayer::dataHandler but you can also create your
 * own data handler.
 *
 * There are several concepts you can follow when writing network games. These
 * concepts differ completely from the way how data is transferred so you should
 * decide which one to use. You can also mix these concepts for a single
 * property but we do not recommend this. The concepts:
 * <ul>
 * <li> Always Consistent (clean)
 * <li> Not Always Consistent (dirty)
 * <li> A Mixture (very dirty)
 * </ul>
 * I repeat: we do <em>not</em> recommend the third option ("a mixture"). Unless
 * you have a good reason for this you will probably introduce some hard to find
 * (and to fix) bugs.
 *
 * @section Always consistent (clean):
 * 
 * This "policy" is default. Whenever you create a KGameProperty it is always
 * consistent. This means that consistency is the most important thing for the
 * property. This is achieved by using send to change the value of the
 * property. send needs a running KMessageServer and therefore
 * <em>MUST</em> be plugged into a KGamePropertyHandler using either
 * registerData or the constructor. The parent of the dataHandler must be able
 * to send messages (see above: the message server must be running). If you use
 * send to change the value of a property you won't see the effect
 * immediately: The new value is first transferred to the message server which
 * queues the message. As soon as <em>all</em> messages in the message server
 * which are before the changed property have been transferred the message
 * server delivers the new value of the KGameProperty to all clients. A
 * TQTimer::singleShot is used to queue the messages inside the
 * KMessageServer. 
 *
 * This means that if you do the following:
 * \code
 * KGamePropertyInt myProperty(id, dataHandler());
 * myProperty.initData(0);
 * myProperty = 10;
 * int value = myProperty.value();
 * \endcode
 * then "value" will be "0". initData is used to initialize the property
 * (e.g. when the KMessageServer is not yet running or can not yet be
 * reached). This is because "myProperty = 10" or "myProperty.send(10)" send a
 * message to the KMessageServer which uses TQTimer::singleShot to
 * queue the message. The game first has to go back into the event loop where
 * the message is received. The KGamePropertyHandler receives the new value
 * sets the property. So if you need the new value you need to store it in a
 * different variable (see setLocal which creates one for you until the
 * message is received). The KGamePropertyHandler emits a signal (unless
 * you called setEmitSignal with false) when the new value is received:
 * KGamePropertyHandler::signalPropertyChanged. You can use this to react
 * to a changed property.
 *
 * This may look quite confusing but it has a <em>big</em> advantage: all
 * KGameProperty objects are ensured to have the same value on all clients in
 * the game at every time. This way you will save you a lot of trouble as
 * debugging can be very difficult if the value of a property changes
 * immediately on client A but only after one or two additianal messages
 * (function calls, status changes, ...) on client B.
 *
 * The only disadvantage of this (clean) concept is that you cannot use a
 * changed variable immediately but have to wait for the KMessageServer to
 * change it. You probably want to use
 * KGamePropertyHandler::signalPropertyChanged for this.
 *
 * @section Not Always Consistent (dirty):
 * 
 * There are a lot of people who don't want to use the (sometimes quite complex)
 * "clean" way. You can use setAlwaysConsistent to change the default
 * behaviour of the KGameProperty. If a property is not always consistent
 * it will use changeValue to send the property.  changeValue also uses
 * send to send the new value over network but it also uses
 * setLocal to create a local copy of the property. This copy is created
 * dynamically and is deleted again as soon as the next message from the network
 * is received. To use the example above again:
 * \code
 * KGamePropertyInt myProperty(id, dataHandler());
 * myProperty.setAlwaysConsistent(false);
 * myProperty.initData(0);
 * myProperty = 10;
 * int value = myProperty.value();
 * \endcode
 * Now this example will "work" so value now is 10. Additionally the
 * KMessageServer receives a message from the local client (just as explained
 * above in "Always Consistent"). As soon as the message returns to the local
 * client again the local value is deleted, as the "network value" has the same
 * value as the local one. So you won't lose the ability to use the always
 * consistent "clean" value of the property if you use the "dirty" way. Just use
 * networkValue to access the value which is consistent among all clients. 
 *
 * The advantage of this concept is clear: you can use a KGameProperty as
 * every other variable as the changes value takes immediate effect.
 * Additionally you can be sure that the value is transferred to all clients.
 * You will usually not experience serious bugs just because you use the "dirty"
 * way. Several events have to happen at once to get these "strange errors"
 * which result in inconsistent properties (like "game running" on client A but
 * "game ended/paused" on client B).  But note that there is a very good reason
 * for the existence of these different concepts of KGameProperty. I have
 * myself experienced such a "strange error" and it took me several days to find
 * the reason until I could fix it. So I personally recommend the "clean" way.
 * On the other hand if you want to port a non-network game to a network game
 * you will probably start with "dirty" properties as it is you will not have to
 * change that much code...
 *
 * @section A Mixture (very dirty):
 * 
 * You can also mix the concepts above. Note that we really don't recommend
 * this. With a mixture I mean something like this:
 * \code
 * KGamePropertyInt myProperty(id, dataHandler());
 * myProperty.setAlwaysConsistent(false);
 * myProperty.initData(0);
 * myProperty = 10;
 * myProperty.setAlwaysConsistent(true);
 * myProperty = 20;
 * \endcode
 * (totally senseless example, btw) I.e. I am speaking of mixing both concepts
 * for a single property. Things like
 * \code
 * KGamePropertyInt myProperty1(id1, dataHandler());
 * KGamePropertyInt myProperty2(id2, dataHandler());
 * myProperty1.initData(0);
 * myProperty2.initData(0);
 * myProperty1.setAlwaysConsistent(false);
 * myProperty2.setAlwaysConsistent(true);
 * myProperty1 = 10;
 * myProperty2 = 20;
 * \endcode
 * are ok. But mixing the concepts for a single property will make it nearly
 * impossible to you to debug your game. 
 *
 * So the right thing to do(tm) is to decide in the constructor whether you want
 * a "clean" or "dirty" property. 
 *
 * Even if you have decided for one of the concepts you still can manually
 * follow another concept than the "policy" of your property. So if you use an
 * always consistent KGameProperty you still can manually call
 * changeValue as if it was not always consistent. Note that although this is
 * also kind of a "mixture" as described above this is very useful sometimes. In
 * contrast to the "mixture" above you don't have the problem that you don't
 * exactly know which concept you are currently following because you used the
 * function of the other concept only once. 
 *
 * @section Custom classes:
 *
 * If you want to use a custum class with KGameProperty you have to implement the
 * operators << and >> for TQDataStream:
 * \code
 * class Card
 * {
 * public:
 * int type;
 * int suite;
 * };
 * TQDataStream& operator<<(TQDataStream& stream, Card& card)
 * {
 * TQ_INT16 type = card.type;
 * TQ_INT16 suite = card.suite;
 * s << type;
 * s << suite;
 * return s;
 * }
 * TQDataStream& operator>>(TQDataStream& stream, Card& card)
 * {
 * TQ_INT16 type;
 * TQ_INT16 suite;
 * s >> type;
 * s >> suite;
 * card.type = (int)type;
 * card.suite = (int)suite;
 * return s;
 * }
 *
 * class Player : KPlayer
 * {
 * [...]
 * KGameProperty<Card> mCards;
 * };
 * \endcode
 *
 * Note: unlike most QT classes KGameProperty objects are *not* deleted
 * automatically! So if you create an object using e.g. KGameProperty<int>* data =
 * new KGameProperty(id, dataHandler()) you have to put a delete data into your
 * destructor!
 *
 * @author Andreas Beckermann <b_mann@gmx.de>
 **/
template<class type>
class KGameProperty  : public KGamePropertyBase
{
public:
	/**
	 * Constructs a KGameProperty object. A KGameProperty object will transmit
	 * any changes to the KMessageServer and then to all clients in the
	 * game (including the one that has sent the new value)
	 * @param id The id of this property. <em>MUST be UNITQUE</em>! Used to send and
	 * receive changes in the property of the playere automatically via
	 * network. 
	 * @param owner The parent of the object. Must be a KGame which manages
	 * the changes made to this object, i.e. which will send the new data.
	 * Note that in contrast to most KDE/QT classes KGameProperty objects
	 * are <em>not</em> deleted automatically!
	 **/
// TODO: ID: Very ugly - better use something like parent()->propertyId() or so which assigns a free id automatically.
	KGameProperty(int id, KGamePropertyHandler* owner) : KGamePropertyBase(id, owner) { init(); }

	/**
	 * This constructor does nothing. You have to call 
	 * KGamePropertyBase::registerData
	 * yourself before using the KGameProperty object.
	 **/
	KGameProperty() : KGamePropertyBase() { init(); }

	virtual ~KGameProperty() {}

	/**
	 * Set the value depending on the current policy (see 
	 * setConsistent). By default KGameProperty just uses send to set
	 * the value of a property. This behaviour can be changed by using
	 * setConsistent.
	 * @param v The new value of the property
	 **/
	void setValue(type v)
	{
		switch (policy()) {
			case PolicyClean:
				send(v);
				break;
			case PolicyDirty:
				changeValue(v);
				break;
			case PolicyLocal:
				setLocal(v);
				break;
			default: // NEVER!
				kdError(11001) << "Undefined Policy in property " << id() << endl;
				return;
		}
	}


	/**
	 * This function sends a new value over network.
	 *
	 * Note that the value DOES NOT change when you call this function. This
	 * function saves the value into a TQDataStream and calls
	 * sendProperty where it gets forwarded to the owner and finally the
	 * value is sent over network. The KMessageServer now sends the
	 * value to ALL clients - even the one who called this function. As soon
	 * as the value from the message server is received load is called
	 * and _then_ the value of the KGameProperty has been set.
	 *
	 * This ensures that a KGameProperty has _always_ the same value on
	 * _every_ client in the network. Note that this means you can NOT do
	 * something like
	 * \code
	 * myProperty.send(1);
	 * doSomething(myProperty);
	 * \endcode
	 * as myProperty has not yet been set when doSomething is being called.
	 *
	 * You are informed about a value change by a singal from the parent of
	 * the property which can be deactivated by setEmittingSignal because of
	 * performance (you probably don't have to deactivate it - except you
	 * want to write a real-time game like Command&Conquer with a lot of
	 * acitvity). See emitSignal
	 *
	 * Note that if there is no KMessageServer accessible - before
	 * the property has been registered to the KGamePropertyHandler (as
	 * it is the case e.g. before a KPlayer has been plugged into the
	 * KGame object) the property is *not* sent but set *locally* (see
	 * setLocal)!
	 * 
	 * @param v The new value of the property
	 * @return whether the property could be sent successfully
	 * @see setValue setLocal changeValue value
	 **/
	bool send(type v)
	{
		if (isOptimized() && mData == v) {
			return true;
		}
		if (isLocked()) {
			return false;
		}
		TQByteArray b;
		TQDataStream stream(b, IO_WriteOnly);
		stream << v;
		if (!sendProperty(b)) {
			setLocal(v);
			return false;
		}
		return true;
	}

	/**
	 * This function sets the value of the property directly, i.e. it
	 * doesn't send it to the network. 
	 *
	 * Int contrast to @see you change _only_ the local value when using
	 * this function. You do _not_ change the value of any other client. You
	 * probably don't want to use this if you are using a dedicated server
	 * (which is the only "client" which is allowed to change a value) but
	 * rather want to use send(). 
	 *
	 * But if you use your clients as servers (i.e. all clients receive a
	 * players turn and then calculate the reaction of the game theirselves)
	 * then you probably want to use setLocal as you can do things like
	 * \code
	 * myProperty.setLocal(1);
	 * doSomething(myProperty);
	 * \endcode
	 * on every client.
	 *
	 * If you want to set the value locally AND send it over network you
	 * want to call changeValue!
	 *
	 * You can also use setPolicy to set the default policy to
	 * PolicyLocal.
	 *
	 * @see setValue send changeValue value
	 **/
	bool setLocal(type v) 
	{
		if (isOptimized() && mData == v) {
			return false;
		}
		if (isLocked()) {
			return false;
		}
		mData = v;
		setDirty(true);
		if (isEmittingSignal()) {
			emitSignal();
		}
		return true;
	}

	/**
	 * This function does both, change the local value and change the
	 * network value. The value is sent over network first, then changed
	 * locally.
	 *
	 * This function is a convenience function and just calls send
	 * followed by setLocal
	 *
	 * Note that emitSignal is also called twice: once after
	 * setLocal and once when the value from send is received
	 *
	 * @see send setLocal setValue value 
	 **/
	void changeValue(type v)
	{
		send(v);
		setLocal(v);
	}

	/**
	 * Saves the object to a stream.
	 * @param stream The stream to save to
	 **/
	virtual void save(TQDataStream &stream)
	{
		stream << mData;
	}

	/**
	 * @return The local value (see setLocal) if it is existing,
	 * otherwise the network value which is always consistent on every
	 * client.
	 **/
	const type& value() const
	{
		return mData;
	}

	/**
	 * Reads from a stream and assigns the read value to this object.
	 *
	 * This function is called automatically when a new value is received
	 * over network (i.e. it has been sent using send on this or any
	 * other client) or when a game is loaded (and maybe on some other
	 * events).
	 *
	 * Also calls emitSignal if isEmittingSignal is TRUE.
	 * @param s The stream to read from
	 **/
	virtual void load(TQDataStream& s)
	{
		s >> mData;
		setDirty(false);
		if (isEmittingSignal()) {
			emitSignal();
		}
	}

	/**
	 * This calls setValue to change the value of the property. Note
	 * that depending on the policy (see setAlwaysConsistent) the
	 * returned value might be different from the assigned value!!
	 *
	 * So if you use setPolicy(PolicyClean):
	 * \code
	 * int a, b = 10;
	 * myProperty = b;
	 * a = myProperty.value();
	 * \endcode
	 * Here a and b would differ!
	 * The value is actually set as soon as it is received from the
	 * KMessageServer which forwards it to ALL clients in the network.
	 *
	 * If you use a clean policy (see setPolicy) then
	 * the returned value is the assigned value
	 **/
	const type& operator=(const type& t) 
	{ 
		setValue(t); 
		return value();
	}

	/**
	 * This copies the data of property to the KGameProperty object.
	 *
	 * Equivalent to setValue(property.value());
	 **/
	const type& operator=(const KGameProperty& property)
	{
		setValue(property.value());
		return value();
	}

	/**
	 * Yeah, you can do it!
	 * \code
	 * 	int a = myGamePropertyInt;
	 * \endcode
	 * If you don't see it: you don't have to use integerData.value()
	 **/
	operator type() const { return value(); }

	virtual const type_info* typeinfo() { return &typeid(type); }

private:
	void init() { }

private:
	type mData;
};


typedef KGameProperty<int>   KGamePropertyInt;
typedef KGameProperty<unsigned int>   KGamePropertyUInt;
typedef KGameProperty<TQString>   KGamePropertyTQString;
typedef KGameProperty<TQ_INT8>   KGamePropertyBool;

#endif