libkdegames Library API Documentation

KGamePropertyHandler Class Reference

A collection class for KGameProperty objects. More...

#include <kgamepropertyhandler.h>

Inheritance diagram for KGamePropertyHandler:

QObject List of all members.

Signals

void signalPropertyChanged (KGamePropertyBase *)
void signalSendMessage (int msgid, QDataStream &, bool *sent)
void signalRequestValue (KGamePropertyBase *property, QString &value)

Public Methods

 KGamePropertyHandler (QObject *parent=0)
 KGamePropertyHandler (int id, const QObject *receiver, const char *sendf, const char *emitf, QObject *parent=0)
 ~KGamePropertyHandler ()
void registerHandler (int id, const QObject *receiver, const char *send, const char *emit)
bool processMessage (QDataStream &stream, int id, bool isSender)
int id () const
bool addProperty (KGamePropertyBase *data, QString name=0)
bool removeProperty (KGamePropertyBase *data)
int uniquePropertyId ()
virtual bool load (QDataStream &stream)
virtual bool save (QDataStream &stream)
bool sendProperty (QDataStream &s)
void sendLocked (bool l)
void emitSignal (KGamePropertyBase *data)
QString propertyName (int id) const
KGamePropertyBasefind (int id)
void clear ()
void setId (int id)
void unlockProperties ()
void setPolicy (KGamePropertyBase::PropertyPolicy p, bool userspace=true)
void lockDirectEmit ()
void unlockDirectEmit ()
KGamePropertyBase::PropertyPolicy policy ()
void lockProperties ()
void flush ()
QIntDict< KGamePropertyBase > & dict () const
QString propertyValue (KGamePropertyBase *property)
void Debug ()

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 71 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 id(), and registerHandler().


Member Function Documentation

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 QObject::connect(), id(), setId(), signalPropertyChanged(), and signalSendMessage().

Referenced by KGamePropertyHandler().

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(), id(), KGamePropertyBase::load(), and KGamePropertyBase::policy().

Referenced by load().

int KGamePropertyHandler::id   const
 

Returns:
the id of the handler

Definition at line 83 of file kgamepropertyhandler.cpp.

Referenced by clear(), find(), KGamePropertyHandler(), load(), processMessage(), propertyName(), propertyValue(), registerHandler(), sendProperty(), and setId().

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(), and QString::isNull().

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

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().

Referenced by clear().

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.

Referenced by KGamePropertyBase::registerData().

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 id(), lockDirectEmit(), processMessage(), and unlockDirectEmit().

Referenced by KGame::loadgame().

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 QIntDictIterator::current(), KGamePropertyBase::id(), and KGamePropertyBase::save().

Referenced by KGame::savegame().

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 id(), and signalSendMessage().

Referenced by KGamePropertyBase::sendProperty(), and KGamePropertyBase::setLock().

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 signalPropertyChanged().

Referenced by KGamePropertyBase::emitSignal().

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 QString::arg(), and id().

Referenced by propertyValue().

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 id().

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 KGamePropertyBase::id(), id(), removeProperty(), QIntDictIterator::toFirst(), and KGamePropertyBase::unregisterData().

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 id().

Referenced by registerHandler().

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 QIntDictIterator::current().

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 QIntDictIterator::current(), and KGamePropertyBase::PropertyPolicy.

Referenced by KGame::setPolicy().

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.

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

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 QObject::prop(), and signalPropertyChanged().

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

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

Referenced by KGamePropertyBase::registerData().

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 QIntDictIterator::current().

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 QIntDictIterator::current().

QIntDict< KGamePropertyBase > & KGamePropertyHandler::dict   const
 

Reference to the internal dictionary.

Definition at line 349 of file kgamepropertyhandler.cpp.

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(), id(), QString::isNull(), QObject::name(), QString::number(), propertyName(), signalRequestValue(), and KGamePropertyBase::typeinfo().

void KGamePropertyHandler::Debug  
 

Writes some debug output to the console.

Definition at line 387 of file kgamepropertyhandler.cpp.

References QIntDictIterator::current(), KGamePropertyBase::id(), KGamePropertyBase::isDirty(), KGamePropertyBase::isEmittingSignal(), KGamePropertyBase::isLocked(), KGamePropertyBase::isOptimized(), and KGamePropertyBase::policy().

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::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().

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().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for libkdegames Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 10:06:39 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003