home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kgame / kgamepropertyhandler.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  11.3 KB  |  354 lines
  1. /*
  2.     This file is part of the KDE games library
  3.     Copyright (C) 2001 Andreas Beckermann (b_mann@gmx.de)
  4.     Copyright (C) 2001 Martin Heni (martin@heni-online.de)
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License version 2 as published by the Free Software Foundation.
  9.  
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public License
  16.     along with this library; see the file COPYING.LIB.  If not, write to
  17.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.     Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef __KGAMEPROPERTYHANDLER_H_
  22. #define __KGAMEPROPERTYHANDLER_H_
  23.  
  24. #include <qobject.h>
  25. #include <qintdict.h>
  26.  
  27. #include "kgameproperty.h"
  28. #include <kdemacros.h>
  29.  
  30. class QDataStream;
  31. class KGame;
  32. class KPlayer;
  33. //class KGamePropertyBase;
  34.  
  35. class KGamePropertyHandlerPrivate; // wow - what a name ;-)
  36.  
  37. /**
  38.  * @short A collection class for KGameProperty objects
  39.  *
  40.  * The KGamePropertyHandler class is some kind of a collection class for
  41.  * KGameProperty. You usually don't have to create one yourself, as both
  42.  * KPlayer and KGame provide a handler. In most cases you do not even have
  43.  * to care about the KGamePropertHandler. KGame and KPlayer implement
  44.  * all features of KGamePropertyHandler so you will rather use it there.
  45.  *
  46.  * You have to use the KGamePropertyHandler as parent for all KGameProperty
  47.  * objects but you can also use KPlayer or KGame as parent - then
  48.  * KPlayer::dataHandler or KGame::dataHandler will be used. 
  49.  *
  50.  * Every KGamePropertyHandler must have - just like every KGameProperty -
  51.  * a unique ID. This ID is provided either in the constructor or in
  52.  * registerHandler. The ID is used to assign an incoming message (e.g. a changed
  53.  * property) to the correct handler. Inside the handler the property ID is used
  54.  * to change the correct property. 
  55.  *
  56.  * The constructor or registerHandler takes 3 addittional arguments: a
  57.  * receiver and two slots. The first slot is connected to
  58.  * signalSendMessage, the second to signalPropertyChanged. You must provide
  59.  * these in order to use the KGamePropertyHandler. 
  60.  *
  61.  * The most important function of KGamePropertyHandler is processMessage
  62.  * which assigns an incoming value to the correct property. 
  63.  *
  64.  * A KGamePropertyHandler is also used - indirectly using emitSignal - to
  65.  * emit a signal when the value of a property changes. This is done this way
  66.  * because a KGameProperty does not inherit QObject because of memory
  67.  * advantages. Many games can have dozens or even hundreds of KGameProperty
  68.  * objects so every additional variable in KGameProperty would be
  69.  * multiplied. 
  70.  *
  71.  **/
  72. class KDE_EXPORT KGamePropertyHandler : public QObject
  73. {
  74.     Q_OBJECT
  75.  
  76. public:
  77.     /**
  78.      * Construct an unregistered KGamePropertyHandler
  79.      *
  80.      * You have to call registerHandler before you can use this
  81.      * handler!
  82.      **/
  83.     KGamePropertyHandler(QObject* parent = 0);
  84.  
  85.     /**
  86.      * Construct a registered handler. 
  87.      *
  88.      * @see registerHandler
  89.      **/
  90.     KGamePropertyHandler(int id, const QObject* receiver, const char* sendf, const char* emitf, QObject* parent = 0);
  91.     ~KGamePropertyHandler();
  92.  
  93.     /**
  94.      * Register the handler with a parent. This is to use
  95.      * if the constructor without arguments has been chosen.
  96.      * Otherwise you need not call this.
  97.      *
  98.      * @param id The id of the message to listen for
  99.      * @param receiver The object that will receive the signals of
  100.      * KGamePropertyHandler
  101.      * @param send A slot that is being connected to signalSendMessage
  102.      * @param emit A slot that is being connected to signalPropertyChanged
  103.      **/
  104.     void registerHandler(int id, const QObject *receiver, const char * send, const char *emit); 
  105.  
  106.     /**
  107.      * Main message process function. This has to be called by
  108.      * the parent's message event handler. If the id of the message
  109.      * agrees with the id of the handler, the message is extracted 
  110.      * and processed. Otherwise false is returned.
  111.      * Example:
  112.      * \code
  113.      *   if (mProperties.processMessage(stream,msgid,sender==gameId())) return ;
  114.      * \endcode
  115.      * 
  116.      * @param stream The data stream containing the message
  117.      * @param id the message id of the message
  118.      * @param isSender Whether the receiver is also the sender
  119.      * @return true on message processed otherwise false
  120.      **/
  121.     bool processMessage(QDataStream &stream, int id, bool isSender );
  122.     
  123.     /**
  124.      * @return the id of the handler
  125.      **/
  126.     int id() const;
  127.     
  128.     /**
  129.      * Adds a KGameProperty property to the handler
  130.      * @param data the property
  131.      * @param name A description of the property, which will be returned by
  132.      * propertyName. This is used for debugging, e.g. in KGameDebugDialog
  133.      * @return true on success
  134.      **/
  135.     bool addProperty(KGamePropertyBase *data, QString name=0);
  136.  
  137.     /**
  138.      * Removes a property from the handler
  139.      * @param data the property
  140.      * @return true on success
  141.      **/
  142.     bool removeProperty(KGamePropertyBase *data);
  143.  
  144.     /**
  145.      * returns a unique property ID starting called usually with a base of
  146.      * KGamePropertyBase::IdAutomatic. This is used internally by
  147.      * the property base to assign automtic id's. Not much need to
  148.      * call this yourself.
  149.      **/
  150.     int uniquePropertyId();
  151.  
  152.  
  153.     /**
  154.      * Loads properties from the datastream
  155.      *
  156.      * @param stream the datastream to load from
  157.      * @return true on success otherwise false
  158.      **/
  159.     virtual bool load(QDataStream &stream);
  160.  
  161.     /**
  162.      * Saves properties into the datastream
  163.      *
  164.      * @param stream the datastream to save to
  165.      * @return true on success otherwise false
  166.      **/
  167.     virtual bool save(QDataStream &stream);
  168.     
  169.     /**
  170.      * called by a property to send itself into the
  171.      * datastream. This call is simply forwarded to
  172.      * the parent object
  173.      **/ 
  174.     bool sendProperty(QDataStream &s);
  175.  
  176.     void sendLocked(bool l);
  177.  
  178.     /**
  179.      * called by a property to emit a signal 
  180.      * This call is simply forwarded to
  181.      * the parent object
  182.      **/ 
  183.     void emitSignal(KGamePropertyBase *data);
  184.  
  185.     /**
  186.      * @param id The ID of the property
  187.      * @return A name of the property which can be used for debugging. Don't
  188.      * depend on this function! It it possible not to provide a name or to
  189.      * provide the same name for multiple properties!
  190.      **/
  191.     QString propertyName(int id) const;
  192.  
  193.     /**
  194.      * @param id The ID of the property. See KGamePropertyBase::id
  195.      * @return The KGameProperty this ID is assigned to
  196.      **/
  197.     KGamePropertyBase *find(int id);
  198.  
  199.     /**
  200.      * Clear the KGamePropertyHandler. Note that the properties are
  201.      * <em>not</em> deleted so if you created your KGameProperty
  202.      * objects dynamically like
  203.      * \code
  204.      * KGamePropertyInt* myProperty = new KGamePropertyInt(id, dataHandler());
  205.      * \endcode
  206.      * you also have to delete it:
  207.      * \code
  208.      * dataHandler()->clear();
  209.      * delete myProperty;
  210.      * \endcode
  211.      **/
  212.     void clear();
  213.  
  214.     /**
  215.      * Use id as new ID for this KGamePropertyHandler. This is used
  216.      * internally only.
  217.      **/
  218.     void setId(int id);//AB: TODO: make this protected in KGamePropertyHandler!!
  219.  
  220.     /**
  221.      * Calls KGamePropertyBase::setReadOnly(false) for all properties of this
  222.      * player. See also lockProperties
  223.      **/
  224.     void unlockProperties();
  225.  
  226.     /**
  227.      * Set the policy for all kgame variables which are currently registerd in
  228.      * the KGame proeprty handler. See KGamePropertyBase::setPolicy
  229.      *
  230.      * @param p is the new policy for all properties of this handler
  231.      * @param userspace if userspace is true (default) only user properties are changed.
  232.      * Otherwise the system properties are also changed.
  233.      **/
  234.     void setPolicy(KGamePropertyBase::PropertyPolicy p, bool userspace=true);
  235.  
  236.     /**
  237.      * Called by the KGame or KPlayer object or the handler itself to delay
  238.      * emmiting of signals. Lockign keeps a counter and unlock is only achieved
  239.      * when every lock is canceld by an unlock.
  240.      * While this is set signals are  quequed and only emmited after this
  241.      * is reset. Its deeper meaning is to prevent inconsistencies in a game
  242.      * load or network transfer where a emit could access a property not
  243.      * yet loaded or transmitted. Calling this by yourself you better know
  244.      * what your are doing.
  245.      **/
  246.     void lockDirectEmit();
  247.  
  248.     /**
  249.      * Removes the lock from the emitting of property signals. Corresponds to
  250.      * the lockIndirectEmits
  251.      **/
  252.     void unlockDirectEmit();
  253.   
  254.     /**
  255.      * Returns the default policy for this property handler. All properties
  256.      * registered newly, will have this property.
  257.      **/
  258.     KGamePropertyBase::PropertyPolicy policy();
  259.  
  260.     /**
  261.      * Calls KGamePropertyBase::setReadOnly(true) for all properties of this
  262.      * handler
  263.      *
  264.      * Use with care! This will even lock the core properties, like name,
  265.      * group and myTurn!!
  266.      *
  267.      * @see unlockProperties
  268.      **/
  269.     void lockProperties();
  270.  
  271.     /**
  272.      * Sends all properties which are marked dirty over the network. This will
  273.      * make a forced synchornisation of the properties and mark them all not dirty.
  274.      **/
  275.     void flush();
  276.  
  277.     /**
  278.      * Reference to the internal dictionary
  279.      **/
  280.     QIntDict<KGamePropertyBase> &dict() const;
  281.  
  282.     /**
  283.      * In several situations you just want to have a QString of a
  284.      * KGameProperty object. This is the case in the 
  285.      * KGameDebugDialog where the value of all properties is displayed. This
  286.      * function will provide you with such a QString for all the types
  287.      * used inside of all KGame classes. If you have a non-standard
  288.      * property (probably a self defined class or something like this) you
  289.      * also need to connect to signalRequestValue to make this function
  290.      * useful.
  291.      * @param property Return the value of this KGameProperty 
  292.      * @return The value of a KGameProperty
  293.      **/
  294.     QString propertyValue(KGamePropertyBase* property);
  295.  
  296.  
  297.     /**
  298.      * Writes some debug output to the console.
  299.      **/ 
  300.     void Debug();
  301.  
  302.  
  303. signals:
  304.     /**
  305.      * This is emitted by a property. KGamePropertyBase::emitSignal
  306.      * calls emitSignal which emits this signal. 
  307.      *
  308.      * This signal is emitted whenever the property is changed. Note that
  309.      * you can switch off this behaviour using 
  310.      * KGamePropertyBase::setEmittingSignal in favor of performance. Note
  311.      * that you won't experience any performance loss using signals unless
  312.      * you use dozens or hundreds of properties which change very often.
  313.      **/
  314.     void signalPropertyChanged(KGamePropertyBase *);
  315.  
  316.     /**
  317.      * This signal is emitted when a property needs to be sent. Only the
  318.      * parent has to react to this.
  319.      * @param msgid The id of the handler
  320.      * @param sent set this to true if the property was sent successfully -
  321.      * otherwise don't touch
  322.      **/
  323.     void signalSendMessage(int msgid, QDataStream &, bool* sent); // AB shall we change bool* into bool& again?
  324.  
  325.     /**
  326.      * If you call propertyValue with a non-standard KGameProperty
  327.      * it is possible that the value cannot automatically be converted into a
  328.      * QString. Then this signal is emitted and asks you to provide the
  329.      * correct value. You probably want to use something like this to achieve
  330.      * this:
  331.      * \code
  332.      * #include <typeinfo>
  333.      * void slotRequestValue(KGamePropertyBase* p, QString& value)
  334.      * {
  335.      *     if (*(p->typeinfo()) == typeid(MyType) {
  336.      *         value = QString(((KGameProperty<MyType>*)p)->value());
  337.      *     }
  338.      * }
  339.      * \endcode
  340.      *
  341.      * @param property The KGamePropertyBase the value is requested for
  342.      * @param value The value of this property. You have to set this.
  343.      **/
  344.     void signalRequestValue(KGamePropertyBase* property, QString& value);
  345.  
  346. private:
  347.     void init();
  348.  
  349. private:
  350.     KGamePropertyHandlerPrivate* d;
  351. };
  352.  
  353. #endif
  354.