276 lines
11 KiB
C++
276 lines
11 KiB
C++
|
|
// -*- C++ -*-
|
|
|
|
|
|
namespace Hurricane {
|
|
|
|
/*! \class Hook
|
|
* \brief Hook description (\b API)
|
|
*
|
|
* \section secHookIntro Introduction
|
|
*
|
|
* The hook is an object which is nested inside a component and
|
|
* which represents some specific part of this component (like
|
|
* its body, its origin or its extremity ...).
|
|
*
|
|
* The Hook class is an abstract one, that means that for any
|
|
* new type of <b>part</b> a new hook subclass must be derived.
|
|
* Each hook specialization will be described altogether with
|
|
* the component which includes it.
|
|
*
|
|
* The Component for instance introduces the concept of
|
|
* <b>BodyHook</b> representing the body of the component (which
|
|
* can be assimilated to the component itself).
|
|
*
|
|
*
|
|
* \section secHookRings Rings
|
|
*
|
|
* Hooks are assembled into a <b>ring</b> (circular link) thanks
|
|
* to a special field pointing to the next hook within the ring.
|
|
*
|
|
* This field is never NULL, by default it points to itself,
|
|
* generating a minimal ring.
|
|
*
|
|
*
|
|
* \section secHookMasterAndSlaveHookTypes Master and Slave hook types
|
|
*
|
|
* There are two kinds of hooks : the <b>masters</b> and the
|
|
* <b>slaves</b>.
|
|
*
|
|
* Rings are organized such that all slave hooks of a master
|
|
* hook are placed in the ring immediately before it (the
|
|
* ordering of slaves is not significant).
|
|
*
|
|
* Therefore, to find the master of a given slave, it's enough
|
|
* to follow the ring pointers, starting from the slave, until a
|
|
* master is found.
|
|
*
|
|
*
|
|
* \section secHookExplicitConnections Explicit connections
|
|
*
|
|
* This dependency between a slave and its master means that the
|
|
* part of the component represented by the slave is anchored on
|
|
* the part of the component represented by the master.
|
|
*
|
|
* This dependence relationship is indeed an explicit
|
|
* connection.
|
|
*
|
|
*
|
|
* \section secHookImplicitConnections Implicit connections
|
|
*
|
|
* Within a ring many relationships master-slaves can cohabit.
|
|
*
|
|
* This cohabitation has a specific meaning for the different
|
|
* masters of the ring. In fact, the ring must be considered as
|
|
* a connection request between the different masters of the
|
|
* ring.
|
|
*
|
|
* In other words, this means that the different masters remains
|
|
* to be connected together, or more generaly stated, that the
|
|
* different connected subsets of components associated to those
|
|
* masters remains to be connected together.
|
|
*
|
|
* The ordering of masters within a ring has no particular
|
|
* signification.
|
|
*
|
|
*
|
|
* \section secHookConceptsOfHyperhooksAndHyperrings Concepts of HyperHooks and HyperRings
|
|
*
|
|
* We can imagine the master-slaves relation as a kind of
|
|
* hyper-hook representing the associated sub-ring, and the ring
|
|
* containing multiple master-slaves relations as an hyper-ring
|
|
* made up of hyper-hooks needing to be connected.
|
|
*
|
|
* Therefore there will be two different levels of ring
|
|
* processing functions depending on wether we handle hooks
|
|
* stricktly speaking or we handle hyper-hooks representing
|
|
* multiple master hooks.
|
|
*
|
|
* \section secHookConstructorAndDestructor Constructor and Destructor
|
|
*
|
|
* There is no Hook constructor available because they are created by
|
|
* the components themselves.
|
|
*
|
|
* On the same way, hooks disapear automatically with their owner.
|
|
*/
|
|
|
|
|
|
/*! \function Component* Hook::getComponent() const;
|
|
* \Return the component whose hook represents a part.
|
|
*
|
|
* \remark The result is never NULL because hooks are byforce nested
|
|
* objects in their component.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::getNextHook() const;
|
|
* \Return the next hook within the ring.
|
|
*
|
|
* \remark The result is never NULL because every hook has by
|
|
* construction its next one (which may be itself is the ring is
|
|
* empty).
|
|
*/
|
|
|
|
/*! \function Hook* Hook::getPreviousHook() const;
|
|
* \Return the previous hook within the ring.
|
|
*
|
|
* \remark Less efficient than getNextHook because it requires a
|
|
* complete ring loop.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::getMasterHook() const;
|
|
* \Return the master of the relation master-slaves identified by the
|
|
* hook.
|
|
*
|
|
* \remark May return itself if the hook is a master and return NULL if
|
|
* the hook is a slave and has no associated master.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::getNextMasterHook() const;
|
|
* \Return the first master found when starting the search immediately
|
|
* after the given hook.
|
|
*
|
|
* \remark May return NULL if there is no master within the ring or
|
|
* return the hook itself if it is a master and the only one in
|
|
* the ring.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::getPreviousMasterHook() const;
|
|
* \Return the first master found when starting a backwards search
|
|
* immediately before the given hook.
|
|
*
|
|
* \remark May return NULL if there is no master within the ring or
|
|
* return the hook itself if it is a master and the only one in
|
|
* the ring.
|
|
*
|
|
* \remark Of course the search is done in the natural forward direction
|
|
* (else it would be trully inefficient).
|
|
*/
|
|
|
|
/*! \function Hooks Hook::getHooks() const;
|
|
* \Return the collection of hooks of the ring containing the given
|
|
* hook.
|
|
*
|
|
* \remarks Hooks are always visited in the natural order starting from
|
|
* the hook itself.
|
|
*/
|
|
|
|
/*! \function Hooks Hook::getSlaveHooks() const;
|
|
* \Return the hook collection which are slaves of the given hook.
|
|
*
|
|
* \remarks This collection will be empty if the given hook is not a
|
|
* master or if it has no attached slaves.
|
|
*
|
|
* When visiting the slaves of a master, those are accessed in
|
|
* the assembly order : the first one is the oldest inserted
|
|
* (they are accessed starting from the first slave found when
|
|
* starting a ring loop from the master itself).
|
|
*
|
|
* The master is not included in this collection.
|
|
*/
|
|
|
|
|
|
/*! \function bool Hook::isMaster() const;
|
|
* \Return \true if the hook must be considered as a master, else
|
|
* \false.
|
|
*
|
|
* \remark For any new kind of hook this predicate must be overloaded.
|
|
*/
|
|
|
|
/*! \function bool Hook::isAttached() const;
|
|
* If the hook is a slave :
|
|
*
|
|
* \Return \true if the hook has an associated master, else \false.
|
|
*
|
|
* \remark You can't find two slaves in the same ring without at least a
|
|
* master.
|
|
*
|
|
* If the hook is a master :
|
|
*
|
|
* Let us consider the hyper-ring made upon hyper-hooks. Then
|
|
* the function returns \true if the ring contains at least an
|
|
* other master else \false.
|
|
*
|
|
* \caution The meaning here is very different than for a slave hook!
|
|
*/
|
|
|
|
|
|
/*! \function Hook* Hook::detach();
|
|
* If the hook is a slave :
|
|
*
|
|
* detaches the hook from its ring and returns its old
|
|
* predecessor.
|
|
*
|
|
* \remark Will return NULL if the hook is the only one in the ring.
|
|
*
|
|
* If the hook is a master :
|
|
*
|
|
* Let us consider the hyper-ring made upon hyper-hooks. Then,
|
|
* the function detaches the hyper-hook (the sub-ring made up of
|
|
* the master and its slaves, if any) from the hyper-ring and
|
|
* returns the old predecessor of the hyper-hook.
|
|
*
|
|
* Within the detached hyper-hook, the relationship master hook
|
|
* - slave hooks remains unaltered and forms a new ring.
|
|
*
|
|
* \remarks May return NULL if the hook is the only master of the ring.
|
|
*
|
|
* The returned hook, if not NULL, is byforce a master.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::attach(Hook* masterHook);
|
|
* If the hook (this) is a slave :
|
|
*
|
|
* The function inserts the hook immediately before
|
|
* \c \<masterHook\> and returns this masterHook.
|
|
*
|
|
* \caution Might throw an exception if the hook already has a master or
|
|
* if \c \<masterHook\> is not a master hook.
|
|
*
|
|
* If the hook (this) is a master :
|
|
*
|
|
* Let us consider the hyper-ring made upon hyper-hooks. Then,
|
|
* the function attaches the the hyper-hook (the sub-ring made
|
|
* up of this master hook and its slaves, if any) before the
|
|
* \c \<masterHook\> and returns this masterHook.
|
|
*
|
|
* \caution Might throw an exception if the hyper-hook is already
|
|
* attached within a ring including an other master or if
|
|
* \c \<masterHook\> is not a master hook.
|
|
*/
|
|
|
|
/*! \function Hook* Hook::merge(Hook* masterHook);
|
|
* merges the rings represented by the two hooks which both must
|
|
* be masters, returns \c \<masterHook\>.
|
|
*
|
|
* \remark Throws an exception if both hooks are not masters.
|
|
*
|
|
* This function doesn't change the two relatioships
|
|
* master-slaves but modifies the connection request between
|
|
* corresponding hyper-hooks.
|
|
*/
|
|
|
|
|
|
//! \name Hook Collection
|
|
// \{
|
|
|
|
/*! \typedef Hooks
|
|
* Collection representing a set of hooks.
|
|
*/
|
|
|
|
/*! \typedef HookLocator
|
|
* Locator for traversing a collection of hooks.
|
|
*/
|
|
|
|
/*! \typedef HookFilter
|
|
* Fiter for selecting a sub-set of hooks matching a given
|
|
* criteria.
|
|
*/
|
|
|
|
/*! \def for_each_hook(hook, hooks)
|
|
* Macro for visiting the set of all hooks of a hook collection.
|
|
*/
|
|
|
|
// \}
|
|
|
|
}
|