This reference page is linked to from the following overview topics: Reference Hierarchy Functions.
Detailed Description
A callback class for ReferenceMaker::EnumRefHierarchy.
This is the callback object for ReferenceMaker::EnumRefHierarchy. This class's proc() method is called for each element in the reference hierarchy. When enumerating indirect references, it is possible to enter an infinite recursive loop unless references are not processed more than once. The system prevents processing duplicates by either maintaining a list of all references processed, or by clearing a flag bit on all references and then testing/setting the flag bit as references are processed. In the ReferenceMaker::EnumRefHierarchy method, this object's BeginEnumeration method is called before starting an enumeration, and EndEnumeration at the end. These methods increment and decrement an internal counter. When the counter is decremented to 0, the list of visited references is cleared. This ensures that the list of visited references is maintained during recursive calls to EnumRefHierarchy, but cleared when the outer most call is exited. In some cases however, it is desirable to maintain the list of visited references across calls to EnumRefHierarchy. In these cases, call this object's BeginEnumeration method prior to the calls to EnumRefHierarchy, and EndEnumeration when done. For example:
FreeMapsRefEnum freeEnum(this);
for ( rmaker = <enum over some refmaker set> )
-- list of visited references cleared after each call
EnumRefHierarchy(rmaker, freeEnum);
versus
FreeMapsRefEnum freeEnum(this);
freeEnum.BeginEnumeration()
for ( rmaker = <enum over some refmaker set> )
-- list of visited references maintained across each call
EnumRefHierarchy(rmaker, freeEnum);
freeEnum.EndEnumeration()
#include <ref.h>
Public Member Functions |
|
| virtual int | proc (ReferenceMaker *rm)=0 |
| This method is called once for each element
in the reference hierarchy. |
|
| virtual CoreExport bool | CheckIfAndSetAsVisited (ReferenceMaker *rmaker) |
| This method sets and checks whether a
ReferenceMaker was visited. |
|
| CoreExport void | BeginEnumeration (bool preventDuplicatesViaFlag=true) |
| This method prepares the RefEnumProc
instance for enumeration. |
|
| CoreExport void | EndEnumeration () |
| This method finalizes the RefEnumProc
instance after enumeration. |
|
Protected Member Functions |
|
| CoreExport | RefEnumProc () |
| virtual CoreExport | ~RefEnumProc () |
| RefEnumProc (const RefEnumProc &) | |
| RefEnumProc & | operator= (const RefEnumProc &rhs) |
Friends |
|
| class | ReferenceTarget |
Constructor & Destructor Documentation
| CoreExport RefEnumProc | ( | ) | [protected] |
| virtual CoreExport ~RefEnumProc | ( | ) | [protected, virtual] |
| RefEnumProc | ( | const RefEnumProc & | ) | [protected] |
Member Function Documentation
| RefEnumProc& operator= | ( | const RefEnumProc & | rhs | ) | [protected] |
| virtual int proc | ( | ReferenceMaker * | rm | ) | [pure virtual] |
This method is called once for each element in the reference hierarchy.
This method is called once for each element in the reference hierarchy. The return value specifies whether continue processing the references, indirect references, and custom attributes of the refmaker; whether to skip processing of those and continue to the next element, or whether to terminate enumeration. Typically the return value will be REF_ENUM_CONTINUE.
- Parameters:
-
rm - A pointer to the reference maker to this item.
- Returns:
- One of the following values:
- REF_ENUM_CONTINUE: This continues the enumeration
- REF_ENUM_HALT: This stops the enumeration.
- REF_ENUM_SKIP: Reference Makers can hold multiple References. In certain instances you may not want to travel down all of the "branches". By returning REF_ENUM_SKIP from this method you tell the enumerator to not enumerate the current Reference Maker's references but not to halt the enumeration completely.
| virtual CoreExport bool CheckIfAndSetAsVisited | ( | ReferenceMaker * | rmaker | ) | [virtual] |
This method sets and checks whether a ReferenceMaker was visited.
Implemented by system. This method is used to check whether a ReferenceMaker was previously visited by this callback object, and registers it as having been visited if not. This method is used to ensure we call the proc only once on each ReferenceMaker.
- Parameters:
-
rmaker - A pointer to the reference maker
- Returns:
- Returns true of the rmaker was previously visited, false if not.
| CoreExport void BeginEnumeration | ( | bool | preventDuplicatesViaFlag =
true |
) |
This method prepares the RefEnumProc instance for enumeration.
Implemented by system. This method is used to initialize the RefEnumProc instance for tracking the reference makers that have been visited. Normally, you do not need to call this method as ReferenceMaker::EnumRefHierarchy calls this method prior to enumerating the specified reference maker. In some cases though, you may want to have RefEnumProc instance track the reference makers visited over multiple calls to EnumRefHierarchy. For example, you may want to call RefEnumProc::proc() on each node in a selection set, tracking the reference makers that have been visited across the entire selection set. Note that each call this method must be paired with a call to EndEnumeration.
- Parameters:
-
preventDuplicatesViaFlag - Defaults to true. With preventDuplicatesViaFlag set to true, processing of a duplicate reference is detected by requesting and clearing a flag bit on all animatables, and then testing/setting the flag bit prior to calling the proc on each reference maker. When set to false, a list of reference makers visited is maintained. If you expect to enumerate only a small number of references, this argument should be set to false. Note however that you do not know what references are held by the references you may enumerate into, so in most cases this argument should be true. Note that the setting specified here overrides the preventDuplicatesViaFlag argument setting in the EnumRefHierarchy call.
- See also:
- ReferenceMaker::EnumRefHierarchy
| CoreExport void EndEnumeration | ( | ) |
This method finalizes the RefEnumProc instance after enumeration.
Implemented by system. This method is used to finalize the RefEnumProc instance after enumeration, freeing any memory or max system resources used to track the reference makers that have been visited. This method should only, and must be, called if you called the BeginEnumeration method.
Friends And Related Function Documentation
friend class ReferenceTarget
[friend] |
