#include <NIS_InteractiveContext.hxx>

Inheritance diagram for NIS_InteractiveContext:

Data Structures
struct	DetectedEnt
	Structure referencing one detected (picked) interactive entity. More...

Public Types
enum	SelectionMode { Mode_NoSelection = 0, Mode_Normal, Mode_Additive, Mode_Exclusive }

Public Member Functions
	NIS_InteractiveContext ()

virtual	~NIS_InteractiveContext ()

const Handle< NIS_InteractiveObject > &	GetObject (const Standard_Integer theID) const

Standard_Integer	NbObjects ()

Standard_Integer	NbDrawers ()

NCollection_Map< Handle< NIS_Drawer > >::Iterator	GetDrawers () const

Management of Views
void	AttachView (const Handle< NIS_View > &theView)

void	DetachView (const Handle< NIS_View > &theView)

Management of Objects
void	Display (Handle< NIS_InteractiveObject > &theObj, const Handle< NIS_Drawer > &theDrawer=NULL, const Standard_Boolean isUpdateViews=Standard_True)

void	DisplayOnTop (Handle< NIS_InteractiveObject > &theObj, const Handle< NIS_Drawer > &theDrawer=NULL, const Standard_Boolean isUpdateViews=Standard_True)

void	Erase (const Handle< NIS_InteractiveObject > &theObj, const Standard_Boolean isUpdateViews=Standard_True)

void	Remove (const Handle< NIS_InteractiveObject > &theObj, const Standard_Boolean isUpdateViews=Standard_True)

void	DisplayAll ()

void	EraseAll ()

void	RemoveAll ()

void	UpdateViews ()

void	RebuildViews ()

void	GetBox (Bnd_B3f &theBox, const NIS_View *theView) const

Selection API
const Handle< NIS_SelectFilter > &	GetFilter () const

void	SetFilter (const Handle< NIS_SelectFilter > &theFilter)

SelectionMode	GetSelectionMode () const

void	SetSelectionMode (const SelectionMode theMode)

Standard_Boolean	ProcessSelection (const Handle< NIS_InteractiveObject > &O, const Standard_Boolean isMultiple=Standard_False)

void	ProcessSelection (const TColStd_PackedMapOfInteger &map, const Standard_Boolean isMultiple=Standard_False)

Standard_Boolean	SetSelected (const Handle< NIS_InteractiveObject > &theObj, const Standard_Boolean isSelected=Standard_True)

void	SetSelected (const TColStd_PackedMapOfInteger &map, const Standard_Boolean isAdded=Standard_False)

Standard_Boolean	IsSelected (const Handle< NIS_InteractiveObject > &theOb)

void	ClearSelected ()

const TColStd_PackedMapOfInteger &	GetSelected ()

void	SetSelectable (const TColStd_PackedMapOfInteger &IDs, const Standard_Boolean isSelectable)

Standard_Boolean	IsSelectable (const Standard_Integer objID) const

void	SetShareDrawList (Standard_Boolean isShare)

Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor. More...

	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing. More...

Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter. More...

virtual	~Standard_Transient ()
	Destructor must be virtual. More...

virtual void	Delete () const
	Memory deallocator for transient classes. More...

virtual const Handle_Standard_Type &	DynamicType () const
	Returns a type information object about this object. More...

Standard_Boolean	IsInstance (const Handle_Standard_Type &theType) const
	Returns a true value if this is an instance of Type. More...

Standard_Boolean	IsInstance (const Standard_CString theTypeName) const
	Returns a true value if this is an instance of TypeName. More...

Standard_Boolean	IsKind (const Handle_Standard_Type &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...

Standard_Boolean	IsKind (const Standard_CString theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...

virtual Handle_Standard_Transient	This () const
	Returns a Handle which references this object. Must never be called to objects created in stack. More...

Standard_Integer	GetRefCount () const
	Get the reference counter of this object. More...

Protected Member Functions
void	redraw (const Handle< NIS_View > &theView, const NIS_Drawer::DrawType theType)

Standard_Real	selectObject (Handle< NIS_InteractiveObject > &theSel, NCollection_List< DetectedEnt > &theDet, const gp_Ax1 &theAxis, const Standard_Real theOver, const Standard_Boolean isOnlySelectable=Standard_True) const

Standard_Boolean	selectObjects (TColStd_PackedMapOfInteger &mapObj, const Bnd_B3f &theBox, const gp_Trsf &theTrf, const gp_Trsf &theTrfInv, const Standard_Boolean isFullyIn) const

Standard_Boolean	selectObjects (TColStd_PackedMapOfInteger &mapObj, const NCollection_List< gp_XY > &thePolygon, const Bnd_B2f &thePolygonBox, const gp_Trsf &theTrfInv, const Standard_Boolean isFullyIn) const

Detailed Description

InteractiveContext is the central NIS structure that stores and manages all NIS_InteractiveObject instances as well as the Drawers for their visualisation. There may be one or more Views referred by an InteractiveContext instance. Also there may be one or more InteractiveContext instances referring the same View. However the latter case is not typical (see NIS_View description). To add or remove a View in a Context, use methods AttachView() and DetachView().

Management of objects

The main purpose of class NIS_InteractiveContext is allocation and management of NIS_InteractiveObject instances.

An InteractiveObject should be added to the Context by a call to method Display() or DisplayOnTop(). After that (not before) it becomes possible to:

change the presentation of the InteractiveObject (e.g., modify the color)
make the InteractiveObject visible or invisible, selectable or unselectable;
set Transparency;
select InteractiveObject interactively, including the hilighting and the dynamic hilighting.

Methods that add/remove/display/hide NIS_InteractiveObject instances have the optional parameter 'isUpdateViews'. When it is set to True (default), the modification of the object brings about an immediate update of its presentation (the corresponding Drawer flagged to recompute presentations). Normally you do not have to worry about this parameter leaving it assigned to the default value; use the alternative value 'Standard_False' only for very special purposes, like animation – when many updates should be synchronized in time. For other methods like changing the transparency or color definition there is no parameter 'isUpdateViews', all changes mark the corresponding drawers immediately.

Typical scheme of usage:

const Handle(NIS_InteractiveContext) aContext = new NIS_InteractiveContext;
const Handle(NIS_View) aView = new NIS_View(...);
aContext->AttachView (aView);
....
for (; ;) {
  const Handle(MyIOClass) anObject = new MyIOClass();
  aContext->Display (anObject);
  anObject->SetColor(...);  // method of class MyIOClass
  ...
}

Method Display()

This method performs three important tasks, when called the first time for an object:

Copy its argument to the memory pool that is managed by the internal Allocator of NIS_InteractiveContext. Then the new instance of object is returned back in the same argument (in-out parameter);
Store the copied instance in the internal vector of objects, so that the displayed object receives its ID (sequential address in the vector);
Create a Drawer instance if necessary; attach the displayed interactive object to this instance (or to a relevant and already existing Drawer)

Thus any methods dealing with Drawer-related properties like color, line width, polygon offset, etc. can only be called following the necessary call of method Display().

Subsequent calls to Display() just revert previous calls of Erase() without any re-initialization of interactive object or its drawer.

Using the memory

As described in the sections above, all interactive objects should completely reside in the special memory pool managed by the InteractiveContext instance. This is a fast memory (NCollection_IncAllocator is used) but it has the drawback: when you destroy an object using method Remove() it is detached from NIS_InteractiveContext and its presentation is removed from all Views. But the memory allocated for that removed object is not released and it cannot be reused by new interactive objects. In time there may appear too many "dead" objects to hinder or even crash the application.

This problem is resolved by automatic keeping the record of the total size of both used and unused memory, in the instance of NIS_Allocator. When the amount of unused memory becomes too big then the method compactObjects() creates a new NIS_Allocator instance and copies there all interactive objects that are 'alive' then releasing the previous memory pool. All object IDs and their drawers remain intact, so nothing is changed except the greater amount of available memory in the system.

This mechanism works when either UpdateViews() or RebuildViews() is called from time to time, only these two methods can call compactObjects().

Member Enumeration Documentation

enum NIS_InteractiveContext::SelectionMode

Enumerator
Mode_NoSelection	Seelction is totally disabled.
Mode_Normal	Selected are added to or removed from list.
Mode_Additive	Selected are added to the list of selected.
Mode_Exclusive	Selected are removed from the list.

Constructor & Destructor Documentation

NIS_InteractiveContext::NIS_InteractiveContext ( )

Empty constructor.

virtual NIS_InteractiveContext::~NIS_InteractiveContext ( )

virtual

Destructor.

Member Function Documentation

void NIS_InteractiveContext::AttachView ( const Handle< NIS_View > & theView )

Associate this Context with the given View.

void NIS_InteractiveContext::ClearSelected ( )

Reset all previous selection.

void NIS_InteractiveContext::DetachView ( const Handle< NIS_View > & theView )

Stop the association of the Context with the given View.

void NIS_InteractiveContext::Display	(	Handle< NIS_InteractiveObject > &	theObj,
		const Handle< NIS_Drawer > &	theDrawer = `NULL`,
		const Standard_Boolean	isUpdateViews = `Standard_True`
	)

Make the given interactive object visible in the current context. If the object is not yet added to this context, it is added. Therefore this method should follow the creation of an InteractiveObject instance before it can be displayed.

Parameters

theObj	`[in/out]`Interactive object instance. If the object is displayed for the first time then the output value will be a new (cloned) object.
theDrawer	If this parameter is NULL, the default drawer is used for theObj, defined by the object type. Otherwise the given Drawer (must be present in this context) is used for theObj. Use the parameter to change the presentation of theObj.
isUpdateViews	If True, the drawer receives isUpdate flag, then it will recompute the presentations when Redraw event happens. You can leave the parameter to False if you have to make a number of similar calls, then you would call UpdateViews() in the end.

void NIS_InteractiveContext::DisplayAll ( )

Make all stored InteractiveObject instances visible, equivalent to calling method Display() for all contained objects.

void NIS_InteractiveContext::DisplayOnTop	(	Handle< NIS_InteractiveObject > &	theObj,
		const Handle< NIS_Drawer > &	theDrawer = `NULL`,
		const Standard_Boolean	isUpdateViews = `Standard_True`
	)

Make the given interactive object visible on top of other objects in the current context. If the object is not yet added to this context, it is added. Therefore this method should follow the creation of an InteractiveObject instance before it can be displayed.

Parameters

theObj	Interactive object instance.
theDrawer	If this parameter is NULL, the default drawer is used for theObj, defined by the object type. Otherwise the given Drawer (must be present in this context) is used for theObj. Use the parameter to change the presentation of theObj.
isUpdateViews	If True, the drawer receives isUpdate flag, then it will recompute the presentations when Redraw event happens. You can leave the parameter to False if you have to make a number of similar calls, then you would call UpdateViews() in the end.

void NIS_InteractiveContext::Erase	(	const Handle< NIS_InteractiveObject > &	theObj,
		const Standard_Boolean	isUpdateViews = `Standard_True`
	)

Make the given object invisible in the current InteractiveContext.

Parameters

theObj	Interactive object instance. Must be already added to this context.
isUpdateViews	If True, the drawer receives isUpdate flag, then it will recompute the presentations when Redraw event happens. You can leave the parameter to False if you have to make a number of similar calls, then you would call UpdateViews() in the end.

void NIS_InteractiveContext::EraseAll ( )

Make all stored InteractiveObject instances invisible, equivalent to calling method Erase() for all contained objects.

void NIS_InteractiveContext::GetBox	(	Bnd_B3f &	theBox,
		const NIS_View *	theView
	)		const

Find the bounding box of all Objects displayed (visible) in the given View.

Parameters

theBox	`[out]` Bounding box, updated (not reinitialized!) by the object boxes.
theView	View instance where the objects are displayed.

NCollection_Map<Handle< NIS_Drawer > >::Iterator NIS_InteractiveContext::GetDrawers ( ) const

inline

Access to Drawers, can be used for specific operations where it is not desirale to iterate InteractiveObjects.

const Handle< NIS_SelectFilter >& NIS_InteractiveContext::GetFilter ( ) const

inline

Query the current selection filter. Use the method SetFilter to install it. By default returns a NULL handle.

const Handle< NIS_InteractiveObject >& NIS_InteractiveContext::GetObject ( const Standard_Integer theID ) const

Query the InteractiveObject instance by its ID.

const TColStd_PackedMapOfInteger& NIS_InteractiveContext::GetSelected ( )

inline

Query the set of selected objects.

Returns: Map of integer IDs of objects.

SelectionMode NIS_InteractiveContext::GetSelectionMode ( ) const

inline

Query the current selection mode.

Standard_Boolean NIS_InteractiveContext::IsSelectable ( const Standard_Integer objID ) const

inline

Return True if the object can be selected (processing by SetSelected methods), or False if can not be.

Returns: Selectable state of the object.

Standard_Boolean NIS_InteractiveContext::IsSelected ( const Handle< NIS_InteractiveObject > & theOb )

Query if the given object is selected.

Standard_Integer NIS_InteractiveContext::NbDrawers ( )

inline

Query the total number of Drawers instances.

Standard_Integer NIS_InteractiveContext::NbObjects ( )

inline

Query the total number of InteractiveObject instances. This number can be smaller than the greatest object ID, therefore you should not iterate till this number using GetObject; use class NIS_ObjectsIterator instead.

Standard_Boolean NIS_InteractiveContext::ProcessSelection	(	const Handle< NIS_InteractiveObject > &	O,
		const Standard_Boolean	isMultiple = `Standard_False`
	)

Set or unset the selected state of the object, also changing its hilight status. If mySelectionMode == Mode_NoSelection this method does nothing (returns False always). If the given object is NULL (e.g., if the mouse was clicked on empty area), then the current selection is cleared (modes Normal and Additive only). The selection algorithm with respect to the given object is defined by the current selection mode:

Mode_Normal - the selection state is toggled
Mode_Additive - the object is always added to the selection
Mode_Exclusive - the object is always removed from the selection

This method does not update the views.

Parameters

O	Object to be selected or deselected
isMultiple	If True, then the objects are not automatically deselected.

Returns: True if the selection status has been changed, False if nothing changed

void NIS_InteractiveContext::ProcessSelection	(	const TColStd_PackedMapOfInteger &	map,
		const Standard_Boolean	isMultiple = `Standard_False`
	)

Process the selection of multiple objects. Equivalent to the other ProcessSelection method, on a set of objects. Particularly, the current selection mode is respected.

Parameters

map	Container of IDs of objects to be processed
isMultiple	If True, then the objects are not automatically deselected.

void NIS_InteractiveContext::RebuildViews ( )

Similar to UpdateViews but forces all presentations to be rebuilt whether the drawers are marked as updated or not.

void NIS_InteractiveContext::redraw	(	const Handle< NIS_View > &	theView,
		const NIS_Drawer::DrawType	theType
	)

protected

void NIS_InteractiveContext::Remove	(	const Handle< NIS_InteractiveObject > &	theObj,
		const Standard_Boolean	isUpdateViews = `Standard_True`
	)

Remove the given object from its Interactive context.

Parameters

theObj	Interactive object instance. Must be already added to this context.
isUpdateViews	If True, the drawer receives isUpdate flag, then it will recompute the presentations when Redraw event happens. You can leave the parameter to False if you have to make a number of similar calls, then you would call UpdateViews() in the end.

void NIS_InteractiveContext::RemoveAll ( )

Clean the context of its contained objects. Drawers are destroyed and all presentations become empty.

Standard_Real NIS_InteractiveContext::selectObject	(	Handle< NIS_InteractiveObject > &	theSel,
		NCollection_List< DetectedEnt > &	theDet,
		const gp_Ax1 &	theAxis,
		const Standard_Real	theOver,
		const Standard_Boolean	isOnlySelectable = `Standard_True`
	)		const

protected

Detect the object selected by the given ray.

Parameters

theSel	`[out]` The selected object that has the lowest ray distance.
theDet	`[out]` Sorted list of all detected objects with ray distances
theAxis	Selection ray
theOver	Thickness of the selecting ray
isOnlySelectable	If False, any displayed object can be picked, otherwise only selectable ones.

Returns: The ray distance of the intersection point between the ray and theSel.

Standard_Boolean NIS_InteractiveContext::selectObjects	(	TColStd_PackedMapOfInteger &	mapObj,
		const Bnd_B3f &	theBox,
		const gp_Trsf &	theTrf,
		const gp_Trsf &	theTrfInv,
		const Standard_Boolean	isFullyIn
	)		const

protected

Build a list of objects that are inside or touched by an oriented box.

Parameters

mapObj	`[out]` Container of object IDs, updated by detected objects.
theBox	3D box of selection
theTrf	Position/Orientation of the box (for box-box intersections)
theTrfInv	Inverted Position/Orientation of the box (for box-object intersections)
isFullyIn	True if only those objects are processed that are fully inside the selection rectangle. False if objects fully or partially included in the rectangle are processed.

Returns: True if at least one object was selected.

Standard_Boolean NIS_InteractiveContext::selectObjects	(	TColStd_PackedMapOfInteger &	mapObj,
		const NCollection_List< gp_XY > &	thePolygon,
		const Bnd_B2f &	thePolygonBox,
		const gp_Trsf &	theTrfInv,
		const Standard_Boolean	isFullyIn
	)		const

protected

Build a list of objects that are inside or touched by a polygon.

Parameters

mapObj	`[out]` Container of object IDs, updated by detected objects.
thePolygon	the list of vertices of a free-form closed polygon without self-intersections. The last point should not coincide with the first point of the list. Any two neighbor points should not be confused.
thePolygonBox	2D box of selection polygon
theTrfInv	Inverted Position/Orientation of the plane where thePolygon is defined (for polygon-object intersections)
isFullyIn	True if only those objects are processed that are fully inside the selection polygon. False if objects fully or partially included in the polygon are processed.

Returns: True if at least one object was selected.

void NIS_InteractiveContext::SetFilter ( const Handle< NIS_SelectFilter > & theFilter )

inline

Install a selection filter.

void NIS_InteractiveContext::SetSelectable	(	const TColStd_PackedMapOfInteger &	IDs,
		const Standard_Boolean	isSelectable
	)

Define objects that can be selected by no means (isSelectable = false), or make the objects selectable (isSelectable = true).

Parameters

IDs	Container of IDs of objects to be set as selectable or not selectable
isSelectable	If False, the given IDs are made non-selectable by SetSelected methods, If True, the given IDs are made selectable.

Standard_Boolean NIS_InteractiveContext::SetSelected	(	const Handle< NIS_InteractiveObject > &	theObj,
		const Standard_Boolean	isSelected = `Standard_True`
	)

Set or unset the selected state of the object, also changing its hilight status. This method does not update the views.

Parameters

theObj	Object to be selected or deselected
isSelected	true if the object should be selected, False - if deselected.

Returns: True if the selection status has been changed, False if noithing changed

void NIS_InteractiveContext::SetSelected	(	const TColStd_PackedMapOfInteger &	map,
		const Standard_Boolean	isAdded = `Standard_False`
	)

Set the selection. Previously selected objects are deselected if they are not included in the given map.

Parameters

map	Container of IDs of objects to be selected
isAdded	If True, the given IDs are added to the current selection (nothing is deselected). If False (default) - the previous selection is forgotten.

void NIS_InteractiveContext::SetSelectionMode ( const SelectionMode theMode )

inline

Set the selection mode.

void NIS_InteractiveContext::SetShareDrawList ( Standard_Boolean isShare )

inline

Set or reset the flag that tells to NIS_Drawer to create shared DrawList. The default mode (in Constructor) is True.

void NIS_InteractiveContext::UpdateViews ( )

This method signals that the presenation should be refreshed in all updated Drawers and in all Views. Calls Redraw() of each view from inside.

The documentation for this class was generated from the following file:

NIS_InteractiveContext.hxx

Data Structures

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Management of objects

Method Display()

Using the memory

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation