KGamePropertyBase Class Reference

#include <kgameproperty.h>

Inheritance diagram for KGamePropertyBase:

[legend]Collaboration diagram for KGamePropertyBase:


Public Types
enum	PropertyDataIds { IdGroup = 1, IdUserId = 2, IdAsyncInput = 3, IdTurn = 4, IdName = 5, IdGameStatus = 6, IdMaxPlayer = 7, IdMinPlayer = 8, IdGrabInput = 16, IdReleaseInput = 17, IdCommand, IdUser = 256, IdAutomatic = 0x7000 }
enum	PropertyCommandIds { CmdLock = 1, CmdAt = 51, CmdResize = 52, CmdFill = 53, CmdSort = 54, CmdInsert = 61, CmdAppend = 62, CmdRemove = 63, CmdClear = 64 }
	Commands for advanced properties (Q_INT8). More...
enum	PropertyPolicy { PolicyUndefined = 0, PolicyClean = 1, PolicyDirty = 2, PolicyLocal = 3 }
	The policy of the property. More...
Public Member Functions
	KGamePropertyBase (int id, KGamePropertyHandler *owner)
	Constructs a KGamePropertyBase object and calls registerData.
	KGamePropertyBase (int id, KGame *parent)
	KGamePropertyBase (int id, KPlayer *parent)
	KGamePropertyBase ()
	Creates a KGamePropertyBase object without an owner.
virtual	~KGamePropertyBase ()
void	setPolicy (PropertyPolicy p)
	Changes the consistency policy of a property.
PropertyPolicy	policy () const
void	setEmittingSignal (bool p)
	Sets this property to emit a signal on value changed.
bool	isEmittingSignal () const
	See also setEmittingSignal.
void	setOptimized (bool p)
	Sets this property to try to optimize signal and network handling by not sending it out when the property value is not changed.
bool	isOptimized () const
	See also setOptimize.
bool	isDirty () const
bool	isLocked () const
	A locked property can only be changed by the player who has set the lock.
bool	lock ()
	A locked property can only be changed by the player who has set the lock.
bool	unlock (bool force=false)
	A locked property can only be changed by the player who has set the lock.
virtual void	load (QDataStream &s)=0
	This will read the value of this property from the stream.
virtual void	save (QDataStream &s)=0
	Write the value into a stream.
virtual void	command (QDataStream &stream, int msgid, bool isSender=false)
	send a command to advanced properties like arrays
int	id () const
virtual const type_info *	typeinfo ()
int	registerData (int id, KGamePropertyHandler *owner, PropertyPolicy p, QString name=0)
	You have to register a KGamePropertyBase before you can use it.
int	registerData (int id, KGamePropertyHandler *owner, QString name=0)
	This is an overloaded member function, provided for convenience.
int	registerData (int id, KGame *owner, QString name=0)
	This is an overloaded member function, provided for convenience.
int	registerData (int id, KPlayer *owner, QString name=0)
	This is an overloaded member function, provided for convenience.
int	registerData (KGamePropertyHandler *owner, PropertyPolicy p=PolicyUndefined, QString name=0)
	This is an overloaded member function, provided for convenience.
void	unregisterData ()
Protected Member Functions
void	setLock (bool l)
	A locked property can only be changed by the player who has set the lock.
void	setDirty (bool d)
	Sets the "dirty" flag of the property.
bool	sendProperty ()
	Forward the data to the owner of this property which then sends it over network.
bool	sendProperty (const QByteArray &b)
	Forward the data to the owner of this property which then sends it over network.
void	emitSignal ()
	Causes the parent object to emit a signal on value change.
Protected Attributes
KGamePropertyHandler *	mOwner
KGamePropertyBase::Flags	mFlags
Friends
class	KGamePropertyHandler
Classes
union	Flags

Detailed Description

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>

Definition at line 42 of file kgameproperty.h.

Member Enumeration Documentation

enum KGamePropertyBase::PropertyCommandIds

Commands for advanced properties (Q_INT8).

Enumerator:

CmdLock

CmdAt

CmdResize

CmdFill

CmdSort

CmdInsert

CmdAppend

CmdRemove

CmdClear

Definition at line 71 of file kgameproperty.h.

enum KGamePropertyBase::PropertyDataIds

Enumerator:

IdGroup

IdUserId

IdAsyncInput

IdTurn

IdName

IdGameStatus

IdMaxPlayer

IdMinPlayer

IdGrabInput

IdReleaseInput

IdCommand

IdUser

IdAutomatic

Definition at line 45 of file kgameproperty.h.

enum KGamePropertyBase::PropertyPolicy

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.
Enumerator:

PolicyUndefined

PolicyClean

PolicyDirty

PolicyLocal

Definition at line 109 of file kgameproperty.h.

Constructor & Destructor Documentation

KGamePropertyBase::KGamePropertyBase ( int id,

KGamePropertyHandler * owner

)

Constructs a KGamePropertyBase object and calls registerData.

Parameters:

id The id of this property. MUST be UNIQUE! Used to send and receive changes in the property of the playere automatically via network.

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

Definition at line 44 of file kgameproperty.cpp.
References registerData().
Here is the call graph for this function:

KGamePropertyBase::KGamePropertyBase ( int id,

KGame * parent

)

Definition at line 32 of file kgameproperty.cpp.
References registerData().
Here is the call graph for this function:

KGamePropertyBase::KGamePropertyBase ( int id,

KPlayer * parent

)

Definition at line 38 of file kgameproperty.cpp.
References registerData().
Here is the call graph for this function:

KGamePropertyBase::KGamePropertyBase ( )

Creates a KGamePropertyBase object without an owner.
Remember to call registerData!
Definition at line 50 of file kgameproperty.cpp.

KGamePropertyBase::~KGamePropertyBase ( ) [virtual]

Definition at line 55 of file kgameproperty.cpp.
References unregisterData().
Here is the call graph for this function:

Member Function Documentation

void KGamePropertyBase::command ( QDataStream & stream,

int msgid,

bool isSender = false

) [virtual]

send a command to advanced properties like arrays

Parameters:

stream The stream containing the data of the comand

msgid The ID of the command - see PropertyCommandIds

isSender whether this client is also the sender of the command

Reimplemented in KGamePropertyArray< type >, and KGamePropertyList< type >.
Definition at line 195 of file kgameproperty.cpp.
References KGamePropertyBase::Flags::bits, CmdLock, KGamePropertyBase::Flags::locked, and mFlags.
Referenced by KGamePropertyList< type >::command(), KGamePropertyArray< type >::command(), and KGamePropertyHandler::processMessage().

void KGamePropertyBase::emitSignal ( ) [protected]

Causes the parent object to emit a signal on value change.

Definition at line 185 of file kgameproperty.cpp.
References KGamePropertyHandler::emitSignal(), id(), and mOwner.
Referenced by KGameProperty< type >::load(), and KGameProperty< type >::setLocal().
Here is the call graph for this function:

int KGamePropertyBase::id ( ) const [inline]

Returns:
The id of this property

Definition at line 238 of file kgameproperty.h.
Referenced by KGamePropertyHandler::addProperty(), KPlayer::emitSignal(), emitSignal(), KGamePropertyHandler::propertyValue(), KGamePropertyHandler::removeProperty(), KGameProperty< type >::setValue(), KGameDialogConnectionConfig::slotPropertyChanged(), KGameDialogGeneralConfig::slotPropertyChanged(), and KGameChat::slotPropertyChanged().

bool KGamePropertyBase::isDirty ( ) const [inline]

Returns:
Whether this property is "dirty". See also setDirty

Definition at line 180 of file kgameproperty.h.

bool KGamePropertyBase::isEmittingSignal ( ) const [inline]

See also setEmittingSignal.

Returns:
Whether this property emits a signal on value change

Definition at line 163 of file kgameproperty.h.
Referenced by KGameProperty< type >::load(), and KGameProperty< type >::setLocal().

bool KGamePropertyBase::isLocked ( ) const [inline]

A locked property can only be changed by the player who has set the lock.
See also setLocked
Returns:
Whether this property is currently locked.

Definition at line 187 of file kgameproperty.h.
Referenced by lock(), KGameProperty< type >::send(), KGameProperty< type >::setLocal(), and unlock().

bool KGamePropertyBase::isOptimized ( ) const [inline]

See also setOptimize.

Returns:
Whether the property optimizes access (signals,network traffic)

Definition at line 175 of file kgameproperty.h.
Referenced by KGameProperty< type >::send(), and KGameProperty< type >::setLocal().

virtual void KGamePropertyBase::load ( QDataStream & s ) [pure virtual]

This will read the value of this property from the stream.
You MUST overwrite this method in order to use this class
Parameters:

s The stream to read from

Implemented in KGameProperty< type >, KGamePropertyArray< type >, and KGamePropertyList< type >.

bool KGamePropertyBase::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.

Returns:
returns false if the property can not be locked, i.e. it is already locked

Definition at line 152 of file kgameproperty.cpp.
References isLocked(), and setLock().
Here is the call graph for this function:

PropertyPolicy KGamePropertyBase::policy ( ) const [inline]

Returns:
The default policy of the property

Definition at line 150 of file kgameproperty.h.
Referenced by KGamePropertyArray< type >::assign(), KGamePropertyArray< type >::duplicate(), KGamePropertyArray< type >::fill(), KGamePropertyHandler::processMessage(), KGamePropertyArray< type >::resize(), KGamePropertyArray< type >::setAt(), KGamePropertyArray< type >::setRawData(), KGameProperty< type >::setValue(), and KGamePropertyArray< type >::sort().

int KGamePropertyBase::registerData ( KGamePropertyHandler * owner,

PropertyPolicy p = PolicyUndefined,

QString 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.
Definition at line 85 of file kgameproperty.cpp.
References registerData().
Here is the call graph for this function:

int KGamePropertyBase::registerData ( int id,

KPlayer * owner,

QString name = 0

)

This is an overloaded member function, provided for convenience.
It differs from the above function only in what argument(s) it accepts.
Definition at line 82 of file kgameproperty.cpp.
References KPlayer::dataHandler(), and registerData().
Here is the call graph for this function:

int KGamePropertyBase::registerData ( int id,

KGame * owner,

QString name = 0

)

This is an overloaded member function, provided for convenience.
It differs from the above function only in what argument(s) it accepts.
Definition at line 79 of file kgameproperty.cpp.
References KGame::dataHandler(), and registerData().
Here is the call graph for this function:

int KGamePropertyBase::registerData ( int id,

KGamePropertyHandler * owner,

QString name = 0

)

This is an overloaded member function, provided for convenience.
It differs from the above function only in what argument(s) it accepts.
Definition at line 88 of file kgameproperty.cpp.
References PolicyUndefined, and registerData().
Here is the call graph for this function:

int KGamePropertyBase::registerData ( int id,

KGamePropertyHandler * owner,

PropertyPolicy p,

QString name = 0

)

You have to register a KGamePropertyBase before you can use it.
You MUST call this before you can use KGamePropertyBase!

Parameters:

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!

owner The owner of this data. This will send the data using KPropertyHandler::sendProperty whenever you call send

p If not 0 you can set the policy of the property here

name if not 0 you can assign a name to this property

Definition at line 91 of file kgameproperty.cpp.
References KGamePropertyHandler::addProperty(), mOwner, KGamePropertyHandler::policy(), PolicyUndefined, setPolicy(), and KGamePropertyHandler::uniquePropertyId().
Referenced by KGamePropertyBase(), and registerData().
Here is the call graph for this function:

virtual void KGamePropertyBase::save ( QDataStream & s ) [pure virtual]

Write the value into a stream.
MUST be overwritten
Implemented in KGameProperty< type >, KGamePropertyArray< type >, and KGamePropertyList< type >.
Referenced by sendProperty().

bool KGamePropertyBase::sendProperty ( const QByteArray & b ) [protected]

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 not send the current value but the explicitly given value.

Returns:
TRUE if the message could be sent successfully, otherwise FALSE

Definition at line 138 of file kgameproperty.cpp.
References KGameMessage::createPropertyHeader(), mOwner, and KGamePropertyHandler::sendProperty().
Here is the call graph for this function:

bool KGamePropertyBase::sendProperty ( ) [protected]

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 current property!
Might be obsolete - KGamePropertyArray still uses it. Is this a bug or correct?
Definition at line 124 of file kgameproperty.cpp.
References KGameMessage::createPropertyHeader(), mOwner, save(), and KGamePropertyHandler::sendProperty().
Referenced by KGamePropertyArray< type >::assign(), KGamePropertyArray< type >::duplicate(), KGameProperty< type >::send(), and KGamePropertyArray< type >::setRawData().
Here is the call graph for this function:

void KGamePropertyBase::setDirty ( bool d ) [inline, protected]

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.
Definition at line 316 of file kgameproperty.h.
Referenced by KGameProperty< type >::load(), and KGameProperty< type >::setLocal().

void KGamePropertyBase::setEmittingSignal ( bool p ) [inline]

Sets this property to emit a signal on value changed.
As the proerties do not inehrit QObject for optimisation this signal is emited via the KPlayer or KGame object
Definition at line 157 of file kgameproperty.h.

void KGamePropertyBase::setLock ( bool l ) [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
Definition at line 170 of file kgameproperty.cpp.
References CmdLock, KGameMessage::createPropertyCommand(), IdCommand, and mOwner.
Referenced by lock(), and unlock().
Here is the call graph for this function:

void KGamePropertyBase::setOptimized ( bool p ) [inline]

Sets this property to try to optimize signal and network handling by not sending it out when the property value is not changed.

Definition at line 169 of file kgameproperty.h.

void KGamePropertyBase::setPolicy ( PropertyPolicy p ) [inline]

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.
Definition at line 145 of file kgameproperty.h.
Referenced by registerData().

virtual const type_info* KGamePropertyBase::typeinfo ( ) [inline, virtual]

Returns:
a type_info of the data this property contains. This is used e.g. by KGameDebugDialog

Reimplemented in KGameProperty< type >.
Definition at line 244 of file kgameproperty.h.
Referenced by KGamePropertyHandler::propertyValue().

bool KGamePropertyBase::unlock ( bool force = false )

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.

Returns:
returns false if the property can not be locked, i.e. it is already locked

Definition at line 161 of file kgameproperty.cpp.
References isLocked(), and setLock().
Here is the call graph for this function:

void KGamePropertyBase::unregisterData ( )

Definition at line 115 of file kgameproperty.cpp.
References mOwner, and KGamePropertyHandler::removeProperty().
Referenced by ~KGamePropertyBase().
Here is the call graph for this function: