/***************************************************************************
* Copyright (C) 2004 - 2005 by Raphael Langerhorst *
* raphael-langerhorst@gmx.at *
* *
* Permission is hereby granted, free of charge, to any person obtaining *
* a copy of this software and associated documentation files (the *
* "Software"), to deal in the Software without restriction, including *
* without limitation the rights to use, copy, modify, merge, publish, *
* distribute, sublicense, and/or sell copies of the Software, and to *
* permit persons to whom the Software is furnished to do so, subject to *
* the following conditions: *
* *
* The above copyright notice and this permission notice shall be *
* included in all copies or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, *
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*
* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR *
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
* OTHER DEALINGS IN THE SOFTWARE. *
***************************************************************************/
#ifndef GWECONTROLLERH
#define GWECONTROLLERH
#include <qobject.h>
#include <qvaluelist.h>
namespace GCS
{
class GElement;
class GElementID;
class GElementInfluence;
class GEnergy;
}
namespace GWE
{
//QPtrList<GElement> (this way we don't need to include <GElement.h>
// - GweController is a public interface, should not have additional #include dependencies
class QPtrListGElement;
class GDataController;
/**
\Interface GweController GweController.h
\brief Base class for G World Engine (GWE) controller implementations
@author Raphael Langerhorst
GweController defines the interface for the GWE controller implementation.
The GWEs single purpose is persistent element management and thus
has a very slim and effective interface definition. Whether this
implementation is a dynamic network distributed hierarchical
server structure with database backend or a simple local implementation
does not matter.
@note Some documentation given here on this class (or interface)
depends on the actual implementation that is used; the implementation
is "supposed" to do what the documentation of the method says.
@todo use exceptions as they provide a better way for failure description.(??)
talk about this on the mailing list first!!
*/
class GweController : public QObject
{
Q_OBJECT
protected:
/**
* Every GWE Controller needs to have a data controller anyway,
* so it is already present in this base class and can be used
* be derived controllers.
* @note the data controller is passed in the constructor
*/
GDataController* Data;
public:
/**
* Constructor.
* @param data the GDataController used
*/
GweController(GDataController* data, QObject *parent = 0, const char *name = 0);
/**
* Virtual destructor to allow clean memory management
* with derived classes.
*/
virtual ~GweController();
// HELPER OBJECTS //
/**
* @Returns The data controller used.
*/
virtual GDataController* getDataController();
/**
* @Returns The data controller used, read-only.
*/
virtual const GDataController* getDataController() const;
protected:
// USEFUL MANAGEMENT ROUTINES //
protected slots:
/**
* Connects the following element signals in a standard way,
* data is the GDataController that is used.
* - connect(element,SIGNAL(childElementCreated(GCS::GElement*)),
* Data,SLOT(add(GCS::GElement*)));
* - connect(element,SIGNAL(radiateInfluence(const GCS::GElementInfluence&)),
* this,SLOT(radiateInfluence(const GCS::GElementInfluence& )));
* - connect(element,SIGNAL(sendInfluence(const GCS::GElementID&, const GCS::GElementInfluence& )),
* this,SLOT(routeInfluence(const GCS::GElementID&, const GCS::GElementInfluence& )));
* - connect(element,SIGNAL(formChanged(const GCS::GForm& )),
* this,SLOT(handleReparenting()));
* - connect(element,SIGNAL(energyChanged(const GCS::GEnergy& )),
* this,SLOT(removeElementWithNoEnergyLeft(const GCS::GEnergy& )));
*/
virtual void connectBasicElementSignals(const GCS::GElementID& id);
protected:
/**
* Uses the data controller to find all elements that are
* in the range of the given source element. Elements in
* range are simply all elements that touch each other.
*
* This method is usually used to find all elements that are
* affected by an influence.
*
* If the source element has no form, the form of the parent
* element is used as boundary, until a element with a form
* is found or traversal count reaches max_depth_parent.
*
* Normally max_traverse_parents is not set to anything larger than
* 1. If it is necessary it most likely because of a bad element design.
* Still, it can be useful in some cases.
*
* @param source The element that defines the range of affected elements.
* @param max_traverse_children Sets the maximum element hierarchy traversal
* limit in the direction of children; 0 means no children at all,
* 1 means all direct children, ...
* @param max_traverse_parents Sets the maximum element hierarchy traversal limit
* in the direction of parents; 0 means no parents (not even the parent
* of the source element!), 1 means including the direct parent; a higher
* value than 1 only makes sense if neither the source nor the parent
* element have a form attribute. The real maximum of parent traverses is
* defined by the minimum of this parameter and the number of traversals to
* the first parent with a form and the number of traversals to the root
* element.
*
* @returns List of elements that overlap with their form with the source element.
*/
virtual QPtrListGElement findInRange(GCS::GElement* source, unsigned max_traverse_children = 0, unsigned max_traverse_parents = 1);
public slots:
virtual void executeOpenElement(const GCS::GElementID& id);
// INFLUENCE MANAGEMENT //
/**
* Forwards given influence to all elements that are near to the
* sender() of this signal.
*
* @see GElement::radiateInfluence()
*/
virtual void radiateInfluence(const GCS::GElementInfluence& influence);
/**
* Routes an influence from an element to given destination.
*
* @see GElement::routeInfluence()
*/
virtual void routeInfluence(const GCS::GElementID& destination, const GCS::GElementInfluence& influence);
/**
* Checks if given element (sender()) leaves it's current
* parent or enters a sibling element.
* In case any of this applies, reparenting is performed.
*
* Usually this slot can be connected to the formChanged() signal of
* an element.
*/
virtual void handleReparenting();
/**
* Checks if given element (sender()) has an energy amount of 0
* in which case it is deleted.
*
* Usually this slot can be connected to the energyChanged() signal of
* an element.
*/
virtual void removeElementWithNoEnergyLeft(const GCS::GEnergy& changedEnergy);
/**
* Shuts down the whole World Engine and does all required
* cleanup beforehand. It is highly recommended to call
* this slot before shutting down the application.
*
* At the end the quit signal is emitted. In this
* state all cleanup and shutdown is down and the
* application can safely quit.
* @see quit()
*/
virtual void shutdown();
signals:
/**
* Emitted when the GWE Server should shutdown.
* @see shutdown()
*/
void quit();
};
}
#endif
syntax highlighted by Code2HTML, v. 0.9.1