coriolis/hurricane/doc/hurricane/Path.dox

249 lines
8.0 KiB
C++

// -*- C++ -*-
namespace Hurricane {
/*! \class Path
* \brief Path description (\b API)
*
* \section secPathIntro Introduction
*
* Pathes are objects representing an ordered sequence of
* instances through the hierarchy.
*
* They are represented by a head instance which defines the
* path start and tail path which defines the remaining path
* with respect to the cell model referenced by the head
* instance.
*
* terminology A non void path begins by an instance : this
* instance pertains to the top caller cell, named OwnerCell. On
* the other hand the path ends by an instance (which may be the
* same) : this instance refers to its model which will be named
* the MasterCell.
*
*
* \section secPathRemarks Remarks
*
* The different constructors (appart the one which analyses the
* names of the path) as welle as the destructor and the
* different operators are very efficient because the tail
* pathes being shared, only pointer assignments and pointer
* comparisons are realized.
*/
/*! \name Constructors
*/
// \{
/*! \function Path::Path(SharedPath* sharedPath=NULL);
* Default constructor : the path is then void.
*
* \remark This path has no instance and will be the tail terminal path
* of any other path.
*/
/*! \function Path::Path(Instance* instance);
* Builds the path made up of this unique instance.
*
* \caution If the instance is null an exception is thrown.
*/
/*! \function Path::Path(Instance* headInstance, const Path& tailPath);
* Builds the path with head instance \c \<headInstance\> and
* tail path \c \<tailPath\>.
*
* \caution If the instance is null, or if the tail path is not
* compatible with this head instance, an exception is thrown.
*
* \remark The head instance and the tail path are compatible if the
* tail path is void or if the owner cell of the tail path is
* the model cell referenced by the head instance.
*/
/*! \function Path::Path(const Path& headPath, Instance* tailInstance);
* Builds the path with head path \c \<headPath\> and tail
* instance \c \<tailInstance\>.
*
* \caution If the tail instance is null, or if the head path is not
* compatible with this tail instance, an exception is thrown.
*
* \remark The tail instance and the head path are compatible if the
* owner cell of the tail instance is the master cell of the
* head path (which is recall it, the model cell referenced by
* the last instance of the head path) or if the head path is
* empty (then compatible with any non null instance).
*/
/*! \function Path::Path(Cell* cell, const string& pathName);
* Builds the path representing the logic sequence of instance
* names described as a character string. Each instance name is
* separated from the preceeding one by a special delimiter
* (which can be defined with the function
* <b>setPathNameSeparator</b> to be defined later). The cell
* given in argument defines where sarts the search (at each new
* instance identified, we go to its model cell to pursue the
* search within the \c \<pathName\>).
*
* \caution If the cell is null or if the name doesn't correspond to an
* existing hierarchical instanciation path an exception is
* thrown.
*/
/*! \function Path::Path(const Path& path);
* Copy constructor.
*/
// \}
/*! \name Destructors
*/
// \{
/*! \function Path::~Path();
* No description.
*/
// \}
/*! \name Operators
*/
// \{
/*! \function Path& Path::operator=(const Path& path);
* Assignment operator.
*/
/*! \function bool Path::operator==(const Path& path) const;
* Two pathes are equal if they have the same head instance and
* if their tail pathes are equal.
*/
/*! \function bool Path::operator!=(const Path& path) const;
* Two pathes are differents either if they have different head
* instance or if the tail pathes differ.
*/
/*! \function bool Path::operator<(const Path& path) const;
* This comparator has no particular signification. It is just
* defined to be abble to use a STL set of pathes which need a
* comparator.
*/
// \}
/*! \name Accessors
*/
// \{
/*! \function Instance* Path::getHeadInstance() const;
* \Return the head instance or NULL if the path is void.
*/
/*! \function Path Path::getTailPath() const;
* \Return the tail path or a void path if the path has 1 or 0
* hierarchical depth.
*/
/*! \function Path Path::getHeadPath() const;
* \Return the head path or a void path if the path has 1 or 0
* hierarchical depth.
*/
/*! \function Instance* Path::getTailInstance() const;
* \Return the tail instance or NULL if the path is void.
*/
/*! \function string Path::getName() const;
* \Return a string defined by the concatenation of instance names
* separated by a special character (which can be set up by the
* function <b>setPathNameSeparator</b>).
*
* \Return the string <b>""</b> when the path is void.
*/
/*! \function Cell* Path::getOwnerCell() const;
* Retruns the cell owning the head instance or NULL if the path
* is void.
*/
/*! \function Cell* Path::getMasterCell() const;
* \Return the master cell referenced by the last instance of the path
* or NULL if the path is void.
*/
/*! \function Instances Path::getInstances() const;
* \Return the collection of instances defining the path.
*/
/*! \function Transformation Path::getTransformation(const Transformation& transformation = Transformation()) const;
* \Return the transform resulting of the composition of all transforms
* associated with the different instances of the path, applied
* to the given \c \<transformation\>.
*/
// \}
/*! \name Predicates
*/
// \{
/*! \function bool Path::isEmpty() const;
* \Return \true if the path is void and else \false.
*/
// \}
/*! \name Path Functions
*/
// \{
/*! \function char Path::getNameSeparator();
* \Return the special character used as a separator between the
* instance names of a path. By default it is the '.' (point).
*/
/*! \function void Path::setNameSeparator(char separator);
* This function sets the special character used as a separator
* between the instance names of a path (choose it carrefully,
* it must not appear in any instance name).
*/
// \}
/*! \name Path Collection
*/
// \{
/*! \typedef Pathes
* Collection representing a set of pathes.
*/
/*! \typedef PathLocator
* Locator for traversing a collection of pathes.
*/
/*! \typedef PathFilter
* Filter for selecting a subset of pathes matching some
* criteria.
*/
/*! \def for_each_path(path, pathes)
* Macro for visiting all pathes of a path collection.
*/
// \}
}