All Frameworks Class Hierarchy This Framework Indexes Previous Next

VisualizationInterfaces CATPathElement

Usage: you must use this class as is. You should never derive it.

public class CATPathElement

Class representing a path of objects.
Role : provides a structure which is easy to use for manipulating pathes extracted from a tree structure of objects, which is one of the foundations of the CATIAV5 model.

For example when one selects an object thru one of its visualized graphical representations, it is interesting to retreive the whole path of graphical representations corresponding to the selection. Thereafter one wants to translate this path into a path of objects and hold this information for later usage.

Constructor and Destructor Index

o CATPathElement(CATBaseUnknown*): Constructs the class from an object.
o CATPathElement(CATPathElement&): Copy Constructor.
o ~CATPathElement()

Method Index

o AddBrotherElement(CATBaseUnknown*,CATBaseUnknown*): Adds one object as brother of the current position of the path or just at the right of a given object.
o AddChildElement(CATBaseUnknown*,CATBaseUnknown*): Adds one object at the end of the path or just beneath a given object.
o AddFatherElement(CATBaseUnknown*,CATBaseUnknown*): Adds one object at the top of the path or just above a given object.
o AddRef(): Increments the reference count for the given interface.
o BrotherList(CATBaseUnknown*): Retrieves a pointer to the brothers' list of the input object.
o ChildrenList(CATBaseUnknown*): Retrieves a new list enclosing the children list of the input object.
o Clone(): Returns a pointer to a new path of objects which is the clone of the current one.
o CurrentBigBrother(): Retrieves a pointer to the current big brother of the path.
o CurrentElement(): Retrieves a pointer to the current object of the path.
o FindElement(CATBaseUnknown*): Finds a given object anywhere into the path.
o FindElement(IID&): Finds one object in the path adhering to a given interface.
o GetInteractiveContext(): Retrieves the interactive context.
o GetPosition(int*,int*): Retrieves the current position.
o GetSize(): Retrieves the size of the path.
o GetSubPath(CATClassId): Retrieves a sub-path resulting from the search of one object in the path which adheres to a given interface.
o GetSubPath(CATListOfCATString,int&): Retrieves a sub-path resulting from the search of one object in the path which adheres at least to one interface of a given list of interfaces.
o InitToLeafElement(): Initialize a bottom-up run of the path.
o InitToTopElement(): Initialize a top-down run of the path.
o NextChildElement(): Retrieves the next object of the path from the current position in a top-down run of the path.
o NextFatherElement(): Retrieves the next object of the path from the current position in a bottom-up run of the path.
o NextLeftElement(): Retrieves the next right object of the path from the current position in a left-to-right run of the path.
o NextRightElement(): Retrieves the next right object of the path from the current position in a left-to-right run of the path.
o Release(): Decrements the reference count for the given interface.
o RemoveElement(CATBaseUnknown*): Removes one object from the path.
o Reverse(): Reverse the current path.
o Search(IID&,void**): Retrieves a TIE pointer of an object in the path adhering to a given interface.
o SetInteractiveContext(CATVisInteractiveContext): Sets the interactive context.
o SetOffsetForSearch(int): Sets the offset for next searches.
o operator =(CATPathElement&): Assignment operator.
o operator ==(CATPathElement&): Equality operator.
o operator [](int): Returns the (i+1)th object of the path.

Constructor and Destructor

o CATPathElement

public CATPathElement( const iObject = NULL )

Constructs the class from an object.

Parameters:

iObject: the object which will be the first object of the path. Notice that one

o CATPathElement

public CATPathElement( const iPath)

Copy Constructor.
Role: This method creates a new CATPathElement which is a copy of the input CATPathElement.
But, if an interactive context had been put on the input CATPathElement, with the method, it will not be copied onto the new CATPathElement.

Parameters:

iPath: path to copy.

o ~CATPathElement

public virtual ~CATPathElement(

)

Methods

o AddBrotherElement

public virtual AddBrotherElement(	const	`iObject`,
	const	`iLeftObject`	`=NULL`)

Adds one object as brother of the current position of the path or just at the right of a given object. The cursor position is set to the position of the added object if the operation succeeds, otherwise it does not change.

Parameters:

iObject: the object to add. It is added at the end of the brother's list of the current Bigbrother.
iLeftObject: the given object which precises the position where to add iObject. If iLeftObject is not found in the current path, iObject is added at the end of the brother's list of the current Bigbrother.

o AddChildElement

public virtual AddChildElement(	const	`iObject`,
	const	`iFatherObject`	`=NULL` )

Adds one object at the end of the path or just beneath a given object. The cursor position is set to the position of the added object if the operation succeeds, otherwise it does not change.

Parameters:

iObject: the object to add.
iFatherObject: the given object which precises the position where to add iObject. If iFatherObject is not found in the current path, nothing is added.

o AddFatherElement

public virtual AddFatherElement(	const	`iObject`,
	const	`iChildoObject`	`=NULL` )

Adds one object at the top of the path or just above a given object. The cursor position is set to the position of the added object if the operation succeeds, otherwise it does not change.

Parameters:

iObject: the object to add.
iChildObject: the given object which precises the position where to add iObject. If iChildObject is not found in the current path, nothing is added.

o AddRef

public virtual AddRef(

)

Increments the reference count for the given interface.

Returns:: The reference count value.
This information is meant to be used for diagnostic/testing purposes only, because, in some situations, the value may be unstable.

o BrotherList

public BrotherList( const iObject)

Retrieves a pointer to the brothers' list of the input object.

Parameters:

iObject: the object from which we want to retrieve the brothers' list.

Returns:

The brother list.
NULL is returned is the input object is not found.
Lifecycle rules deviation: No AddRef is done on iObject. The returned list must not be deleted or released.

o ChildrenList

public ChildrenList( const iObject)

Retrieves a new list enclosing the children list of the input object.
Role : the returned list holds the child along with all of its brothers of the input parameter. It's up to the user to destroy the returned list.

Parameters:

iObject: The object from which we want to retrieve its children.
Lifecycle rules deviation: No AddRef is done on the objects
contained in the list. They must not be destroyed or released.
The returned list has to be destroyed by the caller.

o Clone

public virtual Clone(

)

Returns a pointer to a new path of objects which is the clone of the current one.

o CurrentBigBrother

public CurrentBigBrother(

)

Retrieves a pointer to the current big brother of the path.

Returns:: The big brother object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o CurrentElement

public CurrentElement(

)

Retrieves a pointer to the current object of the path.

Returns:: The current object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o FindElement

public FindElement( const iObject)

Finds a given object anywhere into the path.
Role: Searches the input object and sets the internal cursor positions if the search succeeds.

Parameters:

iObject: a pointer to the object to find.

Returns:

an integer embodying the result of the search.
Legal Values:

1 if the input object is found
0 otherwise

o FindElement

public virtual FindElement( const iIid)

Finds one object in the path adhering to a given interface.
Role: Searches from leaf to top an object which adheres to a given interface and sets the internal cursor positions if the search succeeds.

Returns:: A pointer to the TIE interface of the found object if the search succeeds, NULL otherwise.

o GetInteractiveContext

public virtual GetInteractiveContext(

)

Retrieves the interactive context.
Role : This method gives the interactive context that
will be use to draw the graphic representation.

Returns:: The context.

o GetPosition

public GetPosition(		`BBpos`,
		`Bpos`)

Retrieves the current position.

o GetSize

public GetSize(

)

Retrieves the size of the path.

Returns:: The count of element in the path.

o GetSubPath

public GetSubPath( const iIid)

Retrieves a sub-path resulting from the search of one object in the path which adheres to a given interface.
Role: Search into the current path, an object adhering to a given interface. And it is a bottom-up search, that is we look for objects from leaf to top and from right to left. If we succeed, we extract and return a 1D sub-path holding the found object.If the search fails, NULL is returned.

Parameters:

iIid: the interface IID.

Returns:

a 1D sub-path of the current path if the search succeeds, NULL otherwise.

o GetSubPath

public virtual GetSubPath(	const	`iList_Interfaces`,
		`oPos`)

Retrieves a sub-path resulting from the search of one object in the path which adheres at least to one interface of a given list of interfaces.
Role: Search into the current path, an object adhering to one of the given interfaces. And it is a bottom-up search, that is we look for objects from leaf to top and from right to left. Then we extract and return a 1D sub-path holding the found object.If the search fails, NULL is returned.

Because one object can adhere to more than one of the given interfaces, you should notice that this is the first successful encountered interface which is choosen. Notice that at each position in the path, the search is also performed by looking at the first interface, then the second and so on till the last interface of the input list. And search is stopped whenever one interface suits. So you have to put interfaces into the list carefully : the order may lead to different results as far as the elected interface is concerned!

Parameters:

iList_Interfaces: the list of interface names.
oPos: the index of the found interface from the input list.
Legal Values: a non zero positive integer if the search succeeds, -1 otherwise.

Returns:

a 1D sub-path of the current path if the search succeeds, NULL otherwise.

o InitToLeafElement

public InitToLeafElement(

)

Initialize a bottom-up run of the path. To get the last object of the path, one should call the method.

o InitToTopElement

public InitToTopElement(

)

Initialize a top-down run of the path. To get the first object of the path, one should call the method.

o NextChildElement

public NextChildElement(

)

Retrieves the next object of the path from the current position in a top-down run of the path.
Role: it goes from the curremt positon to the its 'child' object, that is the object which is the child of the current object's BigBrother. The cursor is updated to the next child object. If the cursor is set to the last object, the call of this method will return NULL.

Returns:: The next child object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o NextFatherElement

public NextFatherElement(

)

Retrieves the next object of the path from the current position in a bottom-up run of the path.
Role: it goes from the curremt positon to the its 'father' object, that is the object which is the father of the current object's BigBrother. The cursor is updated to the next father object. If the cursor is set to the first object, the call of this method will return NULL.

Returns:: The next parent object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o NextLeftElement

public NextLeftElement(

)

Retrieves the next right object of the path from the current position in a left-to-right run of the path.
Role: it goes from the curremt positon to the next left object, that is the object which is the next left brother of the current object or the most right brother of the next father object. The cursor is updated to the next left object. If the cursor is set to the first object, the call of this method will return NULL.

Returns:: The next left object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o NextRightElement

public NextRightElement(

)

Retrieves the next right object of the path from the current position in a left-to-right run of the path.
Role: it goes from the curremt positon to the next right object, that is the object which is the next right brother of the current object or the next child object. The cursor is updated to the next right object. If the cursor is set to the last object, the call of this method will return NULL.

Returns:: The next right object.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o Release

public virtual Release(

)

Decrements the reference count for the given interface.

Returns:: The reference count value.
This information is meant to be used for diagnostic/testing purposes only, because, in some situations, the value may be unstable.

o RemoveElement

public virtual RemoveElement( const iObject)

Removes one object from the path.
Role: the object to remove can be either a Bigbrother or a brother of a given Bigbrother. In the first case we remove the Bigbrother and all its brothers and in the second case we remove the object and all its right brothers. The cursor's position is not changed if the object to remove is different from the current position and if the current position is a left brother of the removed object. Otherwise, the position is set to the next existing left object.

Parameters:

iObject: the object to remove.

o Reverse

public Reverse(

)

Reverse the current path.

o Search

public virtual Search(	const	`iIid`,
		`oPtr`)

Retrieves a TIE pointer of an object in the path adhering to a given interface.
Role: Searches from leaf to top an object which adheres to a given interface and sets the internal cursor positions if the search succeeds. If search is successful, given the found object and the input interface, the TIE pointer of the found object is returned.

Parameters:

oPtr: the TIE pointer.

Returns:

an HRESULT value
Legal Values:

S_OK if the search succeeds
E_FAIL otherwise

o SetInteractiveContext

public virtual SetInteractiveContext( iContext)

Sets the interactive context.
Role : This method precises if the graphic representation
must be drawn taking account the context defined in parameter.

Parameters:

iContext: The context

o SetOffsetForSearch

public virtual SetOffsetForSearch( iOffset)

Sets the offset for next searches.

Parameters:

iOffset: the offset.

o operator =

public operator =( const iPath)

Assignment operator.
Role: The values of the input CATPathElement are assigned to this. However, if an interactive context had been put on the input CATPathElement, with the method, it will not be kept through the assignment.

Parameters:

iPath: path to assign.

o operator ==

public operator ==( const iPath)

Equality operator.
Role:This method compares one by one the elements of the two paths. As soon as there is a difference, the comparison failed.

Parameters:

iPath: Path to compare with the current path.

Returns:

An integer value whose legal values are:

1: if the paths are equal
0: else

o operator []

public operator []( i)

Returns the (i+1)th object of the path.

Parameters:

i: index in the path.

Returns:

a pointer to an object, or NULL if the input parameter is out of the scope of the path.

This object is included in the file: CATPathElement.h
If needed, your Imakefile.mk should include the module: CATVisItf

VisualizationInterfaces writeClassCharacteristic(); CATPathElement

Constructor and Destructor Index

Method Index

Constructor and Destructor

Methods

VisualizationInterfaces CATPathElement