// -*- C++ -*- namespace Hurricane { /*! \class Query * \brief Query description (\b API) * * \section secQueryIntro Introduction * * The Query is a part of the trans-hierarchical mechanism. * A Query performs a walktrough over all the Occurrences * of objects under a determined area, thus providing a * virtual flattening service. Please note that only placed * objects (i.e. inserted in a QuadTree) are took into account. * * To use the Query class the user has to create derived classes * and overload the various callbacks. At least the following * pure virtual methods must be overloaded: * - Query::masterCellCallback(). * - Query::goCallback(). * - Query::extensionGoCallback(). * * * \section secQueryParameters * * A query walkthrough is defined by the following parameters: * - The starting hierarchical level: only objects with a * hierarchical depth greater or equal will be explored. * The top level Cell has a depth of \e zero, the master * Cell of the instances a depth of \e one and so on. * - The stoping hierarchical level: only objects with a * hierarchical depth lesser or equal will be considered. * - The top Cell on which to start. * - The area to consider on the top Cell. * - A transformation to apply on the top Cell. * - A BasicLayer to select only the Gos containing it. * - An ExtensionSlice::Mask to select which user-defined slice * to process. * - A Mask, to select which kind of Go to process. */ //! \enum Query::QueryFilter //! Set of flags to specify on which types of objects the Query //! must iterate. //! \var Query::DoMasterCells //! Activate the call of the Query::masterCellCallback(). //! \var Query::DoTerminalCells //! Activate the call of the Query::masterCellCallback(), but only on //! leaf Cell of the hierarchy. //! \var Query::DoComponents //! Activate the call of the Query::goCallback(). //! \var Query::DoMarkers //! Activate the call of the Query::markerCallback(). //! \var Query::DoRubbers //! Activate the call of the Query::rubberCallback(). //! \var Query::DoExtensionGos //! Activate the call of the Query::extensionGoCallback(). //! \var Query::DoAll //! Activate all the callbacks at once. //! \function Query::Query (); //! Default constructor. Initialisation is done through Query::setQuery(). //! \function Query::~Query (); //! Default destructor. //! \function unsigned int Query::getStartLevel () const; //! \sreturn The hierarchical level from which we start to consider objects. //! \function unsigned int Query::getStopLevel () const; //! \sreturn The hierarchical level from which we stop to consider objects. //! \function size_t Query::getDepth () const; //! \sreturn The hierarchical depth of the current Query walkthrough. //! \function const Transformation& Query::getTransformation () const; //! \sreturn The cumulative transformation of the master cell currently under exploration. //! \function const Box& Query::getArea () const; //! \sreturn The area to explore, expressed in the coordinates system of the //! current master cell under exploration. This is the starting area with //! the inverse of the current transformation applied. //! \function const BasicLayer* Query::getBasicLayer () const; //! \sreturn The BasicLayer we are filtering with. //! \function Cell* Query::getMasterCell (); //! \sreturn The master Cell currently under exploration. //! \function Instance* Query::getInstance (); //! \sreturn The Instance currently under exploration. //! \function Path Query::getPath () const; //! \sreturn The instanciation path between the instance currently under inspection //! and the top cell. //! \function bool Query::hasGoCallback () const; //! \sreturn Tells wether the Go callback is present and should be called. //! \function bool Query::hasMarkerCallback () const; //! \sreturn Tells wether the Marker callback is present and should be called. //! \function bool Query::hasRubberCallback () const; //! \sreturn Tells wether the Rubber callback is present and should be called. //! \function bool Query::hasExtensionGoCallback () const; //! \sreturn Tells wether the ExtensionGo callback is present and should be called. //! \function bool Query::hasMasterCellCallback () const; //! \sreturn Tells wether the master Cell callback is present and should be called. //! \function void Query::goCallback ( Go* ); //! \sreturn The method called on each encountered Go. This is a pure virtual //! method which must be overloaded in derived classes. //! \function void Query::markerCallback ( Marker* ); //! \sreturn The method called on each encountered Marker. A default implementation //! is provided, which does absolutely nothing. //! \function void Query::rubberCallback ( Rubber* ); //! \sreturn The method called on each encountered Rubber. A default implementation //! is provided, which does absolutely nothing. //! \function void Query::extensionGoCallback ( Go* ); //! \sreturn The method called on each encountered ExtensionGo. This is a pure virtual //! method which must be overloaded in derived classes. //! \function void Query::masterCellCallback (); //! \sreturn The method called on each encountered master Cell. The Cell is not //! passed as parameter as it is directly accessible through Query::getCell(). //! This is a pure virtual method which must be overloaded in derived classes. //! \function void Query::setQuery ( Cell* cell, const Box& area, const Transformation& transformation, const BasicLayer* basicLayer, ExtensionSlice::Mask extensionMask, Mask filter ); //! \param cell The top Cell on which to start the Query. //! \param area The area under which objects are queried. //! \param transformation An initial transformation to apply to \c cell. //! \param basicLayer Consider only objects containing this BasicLayer. //! \param extensionMask Consider only ExtensionGo matching this mask. //! \param filter Consider only objects of certain types, as defined in //! QueryFilter. //! //! Initialize the basic parameters of the Query. Those parameters can //! be changed individually afterwards with specific mutators. //! \function void Query::setCell ( Cell* cell ); //! Change the top Cell on which to perform the Query. //! \function void Query::setArea ( const Box& box ); //! Change the top area to query. //! \function void Query::setTransformation ( const Transformation& transformation ); //! Change the transformation applied to the top level Cell. //! \function void Query::setBasicLayer ( const BasicLayer* ); //! Change the BasicLayer selector. //! \function void Query::setExtensionMask ( ExtensionSlice::Mask ); //! Change the filtering mask for ExtensionSlice. //! \function void Query::setFilter ( Mask ); //! Change the filtering mask for object types. //! \function void Query::setStartLevel ( unsigned int ); //! Change the starting depth level. //! \function void Query::setStopLevel ( unsigned int ); //! Change the stoping depth level. //! \function void Query::doQuery (); //! Perform the actual Query. // \} }