KGamePropertyHandler Class Reference

A collection class for KGameProperty objects. More...

#include <kgamepropertyhandler.h>

Collaboration diagram for KGamePropertyHandler:

Collaboration graph
[legend]
List of all members.

Signals

void signalPropertyChanged (KGamePropertyBase *)
 This is emitted by a property.
void signalSendMessage (int msgid, QDataStream &, bool *sent)
 This signal is emitted when a property needs to be sent.
void signalRequestValue (KGamePropertyBase *property, QString &value)
 If you call propertyValue with a non-standard KGameProperty it is possible that the value cannot automatically be converted into a QString.

Public Member Functions

 KGamePropertyHandler (QObject *parent=0)
 Construct an unregistered KGamePropertyHandler.
 KGamePropertyHandler (int id, const QObject *receiver, const char *sendf, const char *emitf, QObject *parent=0)
 Construct a registered handler.
 ~KGamePropertyHandler ()
void registerHandler (int id, const QObject *receiver, const char *send, const char *emit)
 Register the handler with a parent.
bool processMessage (QDataStream &stream, int id, bool isSender)
 Main message process function.
int id () const
bool addProperty (KGamePropertyBase *data, QString name=0)
 Adds a KGameProperty property to the handler.
bool removeProperty (KGamePropertyBase *data)
 Removes a property from the handler.
int uniquePropertyId ()
 returns a unique property ID starting called usually with a base of KGamePropertyBase::IdAutomatic.
virtual bool load (QDataStream &stream)
 Loads properties from the datastream.
virtual bool save (QDataStream &stream)
 Saves properties into the datastream.
bool sendProperty (QDataStream &s)
 called by a property to send itself into the datastream.
void sendLocked (bool l)
void emitSignal (KGamePropertyBase *data)
 called by a property to emit a signal This call is simply forwarded to the parent object
QString propertyName (int id) const
KGamePropertyBase * find (int id)
void clear ()
 Clear the KGamePropertyHandler.
void setId (int id)
 Use id as new ID for this KGamePropertyHandler.
void unlockProperties ()
 Calls KGamePropertyBase::setReadOnly(false) for all properties of this player.
void setPolicy (KGamePropertyBase::PropertyPolicy p, bool userspace=true)
 Set the policy for all kgame variables which are currently registerd in the KGame proeprty handler.
void lockDirectEmit ()
 Called by the KGame or KPlayer object or the handler itself to delay emmiting of signals.
void unlockDirectEmit ()
 Removes the lock from the emitting of property signals.
KGamePropertyBase::PropertyPolicy policy ()
 Returns the default policy for this property handler.
void lockProperties ()
 Calls KGamePropertyBase::setReadOnly(true) for all properties of this handler.
void flush ()
 Sends all properties which are marked dirty over the network.
QIntDict< KGamePropertyBase > & dict () const
 Reference to the internal dictionary.
QString propertyValue (KGamePropertyBase *property)
 In several situations you just want to have a QString of a KGameProperty object.
void Debug ()
 Writes some debug output to the console.

Detailed Description

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 QObject because of memory advantages. Many games can have dozens or even hundreds of KGameProperty objects so every additional variable in KGameProperty would be multiplied.

Definition at line 72 of file kgamepropertyhandler.h.

Constructor & Destructor Documentation

KGamePropertyHandler::KGamePropertyHandler (  QObject *  parent = 0  ) 
 

Construct an unregistered KGamePropertyHandler.

You have to call registerHandler before you can use this handler!

Definition at line 60 of file kgamepropertyhandler.cpp.

KGamePropertyHandler::KGamePropertyHandler (  int  id,
const QObject *  receiver,
const char *  sendf,
const char *  emitf,
QObject *  parent = 0
) 
 

Construct a registered handler.

See also:
registerHandler

Definition at line 54 of file kgamepropertyhandler.cpp.

References registerHandler().

Here is the call graph for this function:

KGamePropertyHandler::~KGamePropertyHandler (   ) 
 

Definition at line 65 of file kgamepropertyhandler.cpp.

References clear().

Here is the call graph for this function:

Member Function Documentation

bool KGamePropertyHandler::addProperty (  KGamePropertyBase *  data,
QString  name = 0
) 
 

Adds a KGameProperty property to the handler.

Parameters:
data the property
name A description of the property, which will be returned by propertyName. This is used for debugging, e.g. in KGameDebugDialog
Returns:
true on success

Definition at line 151 of file kgamepropertyhandler.cpp.

References KGamePropertyBase::id(), KGamePropertyHandlerPrivate::mIdDict, and KGamePropertyHandlerPrivate::mNameMap.

Referenced by KGame::addProperty(), and KGamePropertyBase::registerData().

Here is the call graph for this function:

void KGamePropertyHandler::clear (   ) 
 

Clear the KGamePropertyHandler.

Note that the properties are not deleted so if you created your KGameProperty objects dynamically like 

 KGamePropertyInt* myProperty = new KGamePropertyInt(id, dataHandler());
you also have to delete it: 
 dataHandler()->clear();
 delete myProperty;

Definition at line 334 of file kgamepropertyhandler.cpp.

References id(), KGamePropertyHandlerPrivate::mIdDict, and removeProperty().

Referenced by ~KGamePropertyHandler().

Here is the call graph for this function:

void KGamePropertyHandler::Debug (   ) 
 

Writes some debug output to the console.

Definition at line 387 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

QIntDict< KGamePropertyBase > & KGamePropertyHandler::dict (   )  const
 

Reference to the internal dictionary.

Definition at line 349 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

Referenced by KGameDebugDialog::slotUpdateGameData(), and KGameDebugDialog::slotUpdatePlayerData().

void KGamePropertyHandler::emitSignal (  KGamePropertyBase *  data  ) 
 

called by a property to emit a signal This call is simply forwarded to the parent object

Definition at line 303 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIndirectEmit, KGamePropertyHandlerPrivate::mSignalQueue, and signalPropertyChanged().

Referenced by KGamePropertyBase::emitSignal().

KGamePropertyBase * KGamePropertyHandler::find (  int  id  ) 
 

Parameters:
id The ID of the property. See KGamePropertyBase::id
Returns:
The KGameProperty this ID is assigned to

Definition at line 329 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

Referenced by KGame::findProperty().

void KGamePropertyHandler::flush (   ) 
 

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.

Definition at line 269 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

int KGamePropertyHandler::id (   )  const
 

Returns:
the id of the handler

Definition at line 83 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mId.

Referenced by clear().

bool KGamePropertyHandler::load (  QDataStream &  stream  )  [virtual]
 

Loads properties from the datastream.

Parameters:
stream the datastream to load from
Returns:
true on success otherwise false

Definition at line 188 of file kgamepropertyhandler.cpp.

References lockDirectEmit(), and processMessage().

Here is the call graph for this function:

void KGamePropertyHandler::lockDirectEmit (   ) 
 

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.

Definition at line 283 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIndirectEmit.

Referenced by load(), and KGame::loadgame().

void KGamePropertyHandler::lockProperties (   ) 
 

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 also:
unlockProperties

Definition at line 255 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

KGamePropertyBase::PropertyPolicy KGamePropertyHandler::policy (   ) 
 

Returns the default policy for this property handler.

All properties registered newly, will have this property.

Definition at line 227 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mDefaultPolicy.

Referenced by KGamePropertyBase::registerData().

bool KGamePropertyHandler::processMessage (  QDataStream &  stream,
int  id,
bool  isSender
) 
 

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: 

   if (mProperties.processMessage(stream,msgid,sender==gameId())) return ;

Parameters:
stream The data stream containing the message
id the message id of the message
isSender Whether the receiver is also the sender
Returns:
true on message processed otherwise false

Definition at line 106 of file kgamepropertyhandler.cpp.

References KGamePropertyBase::command(), KGameMessage::extractPropertyCommand(), KGameMessage::extractPropertyHeader(), KGamePropertyBase::IdCommand, KGamePropertyHandlerPrivate::mId, KGamePropertyHandlerPrivate::mIdDict, KGamePropertyBase::policy(), and KGamePropertyBase::PolicyClean.

Referenced by load().

Here is the call graph for this function:

QString KGamePropertyHandler::propertyName (  int  id  )  const
 

Parameters:
id The ID of the property
Returns:
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!

Definition at line 172 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict, and KGamePropertyHandlerPrivate::mNameMap.

Referenced by propertyValue().

QString KGamePropertyHandler::propertyValue (  KGamePropertyBase *  property  ) 
 

In several situations you just want to have a QString 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 QString 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.

Parameters:
property Return the value of this KGameProperty
Returns:
The value of a KGameProperty

Definition at line 354 of file kgamepropertyhandler.cpp.

References KGamePropertyBase::id(), propertyName(), signalRequestValue(), and KGamePropertyBase::typeinfo().

Here is the call graph for this function:

void KGamePropertyHandler::registerHandler (  int  id,
const QObject *  receiver,
const char *  send,
const char *  emit
) 
 

Register the handler with a parent.

This is to use if the constructor without arguments has been chosen. Otherwise you need not call this.

Parameters:
id The id of the message to listen for
receiver The object that will receive the signals of KGamePropertyHandler
send A slot that is being connected to signalSendMessage
emit A slot that is being connected to signalPropertyChanged

Definition at line 93 of file kgamepropertyhandler.cpp.

References setId(), signalPropertyChanged(), and signalSendMessage().

Referenced by KGamePropertyHandler().

Here is the call graph for this function:

bool KGamePropertyHandler::removeProperty (  KGamePropertyBase *  data  ) 
 

Removes a property from the handler.

Parameters:
data the property
Returns:
true on success

Definition at line 142 of file kgamepropertyhandler.cpp.

References KGamePropertyBase::id(), KGamePropertyHandlerPrivate::mIdDict, and KGamePropertyHandlerPrivate::mNameMap.

Referenced by clear(), and KGamePropertyBase::unregisterData().

Here is the call graph for this function:

bool KGamePropertyHandler::save (  QDataStream &  stream  )  [virtual]
 

Saves properties into the datastream.

Parameters:
stream the datastream to save to
Returns:
true on success otherwise false

Definition at line 210 of file kgamepropertyhandler.cpp.

References KGameMessage::createPropertyHeader(), and KGamePropertyHandlerPrivate::mIdDict.

Referenced by KGame::savegame().

Here is the call graph for this function:

void KGamePropertyHandler::sendLocked (  bool  l  ) 
 

bool KGamePropertyHandler::sendProperty (  QDataStream &  s  ) 
 

called by a property to send itself into the datastream.

This call is simply forwarded to the parent object

Definition at line 322 of file kgamepropertyhandler.cpp.

References signalSendMessage().

Referenced by KGamePropertyBase::sendProperty().

void KGamePropertyHandler::setId (  int  id  ) 
 

Use id as new ID for this KGamePropertyHandler.

This is used internally only.

Definition at line 88 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mId.

Referenced by registerHandler().

void KGamePropertyHandler::setPolicy (  KGamePropertyBase::PropertyPolicy  p,
bool  userspace = true
) 
 

Set the policy for all kgame variables which are currently registerd in the KGame proeprty handler.

See KGamePropertyBase::setPolicy

Parameters:
p is the new policy for all properties of this handler
userspace if userspace is true (default) only user properties are changed. Otherwise the system properties are also changed.

Definition at line 232 of file kgamepropertyhandler.cpp.

References KGamePropertyBase::IdUser, KGamePropertyHandlerPrivate::mDefaultPolicy, KGamePropertyHandlerPrivate::mDefaultUserspace, and KGamePropertyHandlerPrivate::mIdDict.

Referenced by KGame::setPolicy().

void KGamePropertyHandler::signalPropertyChanged (  KGamePropertyBase *   )  [signal]
 

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.

Referenced by emitSignal(), registerHandler(), and unlockDirectEmit().

void KGamePropertyHandler::signalRequestValue (  KGamePropertyBase *  property,
QString &  value
)  [signal]
 

If you call propertyValue with a non-standard KGameProperty it is possible that the value cannot automatically be converted into a QString.

Then this signal is emitted and asks you to provide the correct value. You probably want to use something like this to achieve this: 

 #include <typeinfo>
 void slotRequestValue(KGamePropertyBase* p, QString& value)
 {
        if (*(p->typeinfo()) == typeid(MyType) {
                value = QString(((KGameProperty<MyType>*)p)->value());
        }
 }

Parameters:
property The KGamePropertyBase the value is requested for
value The value of this property. You have to set this.

Referenced by propertyValue().

void KGamePropertyHandler::signalSendMessage (  int  msgid,
QDataStream &  ,
bool *  sent
)  [signal]
 

This signal is emitted when a property needs to be sent.

Only the parent has to react to this.

Parameters:
msgid The id of the handler
sent set this to true if the property was sent successfully - otherwise don't touch

Referenced by registerHandler(), and sendProperty().

int KGamePropertyHandler::uniquePropertyId (   ) 
 

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.

Definition at line 264 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mUniqueId.

Referenced by KGamePropertyBase::registerData().

void KGamePropertyHandler::unlockDirectEmit (   ) 
 

Removes the lock from the emitting of property signals.

Corresponds to the lockIndirectEmits

Definition at line 288 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIndirectEmit, KGamePropertyHandlerPrivate::mSignalQueue, and signalPropertyChanged().

void KGamePropertyHandler::unlockProperties (   ) 
 

Calls KGamePropertyBase::setReadOnly(false) for all properties of this player.

See also lockProperties

Definition at line 246 of file kgamepropertyhandler.cpp.

References KGamePropertyHandlerPrivate::mIdDict.

The documentation for this class was generated from the following files:
Generated on Wed Aug 23 18:05:50 2006 for libkdegames by  doxygen 1.4.6