path: root/src/SelectMgr/SelectMgr_ViewerSelector.cdl

-- File:	SelectMgr_ViewerSelector.cdl
-- Created:	Fri Feb 10 09:42:17 1995
-- Author:	Mister rmi
--		<rmi@photon>
--modified by rob -FEB 01 1996
--                -JUL 23 1997 : optimize recompute of selections...
--                               insert real sleep/awake option....
--                -APR 02 1998 : improvment of selection.
--                               Sort with new Criterions
--                               (depth + size +...)
--                               store detected in a best way...
---Copyright:	 Matra Datavision 1995


deferred class ViewerSelector from SelectMgr inherits TShared from MMgt 

    	---Purpose: A framework to define finding, sorting the sensitive
    	-- primitives in a view. Services are also provided to
    	-- define the return of the owners of those primitives
    	-- selected. The primitives are sorted by criteria such
    	-- as priority of the primitive or its depth in the view
    	-- relative to that of other primitives.
    	-- This framework is undefined for either 2D or 3D,
    	-- and is consequently used by both
    	-- StdSelect_ViewerSelector2d and
    	-- StdSelect_ViewerSelector3d, which inherit it, and
    	-- which in turn, return 2D and 3D owners of sensitive
    	-- primitives respectively.
    	-- Note that in 3D, the inheriting framework
    	-- StdSelect_ViewerSelector3d   is only to be used
    	-- if you do not want to use the services provided by
    	-- AIS. In 2D, you will, however, need the services
    	-- provided by the StdSelect_ViewerSelector2d.
    	-- Two tools are available to find and select objects
    	-- found at a given position in the view. If you want to
    	-- select the owners of all the objects detected at
    	-- point x,y, you use the Init - More - Next - Picked
    	-- loop. If, on the other hand, you want to select only
    	-- one object detected at that point, you use the Init -
    	-- More - OnePicked loop. In this iteration, More is
    	-- used to see if an object was picked and
    	-- OnePicked, to get the object closest to the pick position.
    	-- Viewer selectors are driven by
    	-- SelectMgr_SelectionManager, and manipulate
    	-- the SelectMgr_Selection objects given to them by
    	-- the selection manager.

uses
    AsciiString                  from TCollection,
    SelectableObject             from SelectMgr,
    DataMapOfIntegerSensitive    from SelectMgr,
    DataMapOfSelectionActivation from SelectMgr,
    Selection                    from SelectMgr,
    Box2d                        from Bnd,
    HArray1OfInteger             from TColStd,
    ListOfInteger                    from TColStd,
    SequenceOfInteger                from TColStd,
    MapOfTransient                   from TColStd,
    IndexedMapOfInteger              from TColStd,
    IndexedDataMapOfOwnerCriterion   from SelectMgr,
    SensitiveEntity              from SelectBasics,
    SortAlgo                     from SelectBasics,
    EntityOwner                  from SelectMgr,
    StateOfSelection             from SelectMgr, 
    Array1OfPnt2d                from TColgp
    
is

    Initialize ;




    Convert (me:mutable;aSelection : mutable Selection from SelectMgr) is virtual;
    	---Level: Public 
    	---Purpose: to be redefined if conversion is necessary for SensitiveEntities...
	    
	    
	    
   ---Category: Activation/Desactivation Of Selection For Objects 
   --           No general method like "activate a mode (integer) " is possible
   --           here because objects inside the selection view are of different type
   --           
    

    Activate  (me            : mutable;
    	       aSelection    : Selection from SelectMgr;
    	       AutomaticProj : Boolean = Standard_True) 
    is static private;
    	---Level: Internal
    



    ---Category: Management Methods . Some following methods  are private
    --           because they owed to be called only through The Selection Manager  !!

    Clear(me:mutable) is static;
    	---Level: Public 
    	---Purpose: Empties all the tables, removes all selections...
    
    UpdateConversion(me :mutable) is static;
    	---Level: Public 
    	---Purpose: converts all the sensitive entities ;

    Deactivate (me         : mutable;
    	    	aSelection : Selection from SelectMgr)
    is static private;
    	---Level: Internal

    Sleep (me:mutable) is static private;
    	---Level: Internal
    	---Purpose: Desactivates all the objects of the view;
    	--          no object in this view will be selectable;

    Awake (me :mutable;AutomaticProj : Boolean = Standard_True) is static private;
    	---Level: Internal
    	---Purpose: reactivates all the selection which were sleeping....

    Sleep (me       : mutable;
    	   anObject : SelectableObject from SelectMgr) is static private;
    
    Awake (me       : mutable;
    	   anObject : SelectableObject from SelectMgr;
    	   AutomaticProj : Boolean = Standard_True) is static private;
    

    Remove(me:mutable ; aSelection: Selection from SelectMgr) is static private;
    	---Level: Public 
    	---Purpose: removes a Selection from the Selector



    	    ---Category: SELECTION OPERATIONS 
    	    ------------=====================

    SetSensitivity (me : mutable ; aTol:Real) is static;
    	---Level: Public 
    	---Purpose: changes the Sensitivity of picking
    	--          Input value is Real.

    SetClipping(me:mutable ; Xc,Yc,Height,Width:Real) is static;
    	---Level: Public 
   	---Purpose: sets the clipping limits of dynamic picking
   	--          input value are Real

    SetClipping(me:mutable ; aRectangle : Box2d from Bnd) is static;
    	---Level: Public 
    	---Purpose: sets the clipping limits of dynamic picking
    	--          input value are Real


    

    InitSelect (me : mutable ; Xr,Yr : Real) is static;
    	---Level: Public 
    	---Purpose: Performs a pick action. Xr, Yr   are the real 2D mouse
    	-- coordinates in the view. The selector looks for areas
    	-- and owners that are touched.

    InitSelect (me : mutable ; aRect: Box2d from Bnd) is static;
    	---Level: Public 
    	---Purpose: Performs a pick action. aRect is a Box2d (real
    	-- coordinates) for the selection. The selector looks for
    	-- areas and owners that are touched.

    InitSelect (me : mutable ; Xmin,Ymin,Xmax,Ymax: Real) is static;
    	---Purpose: Performs a pick action
    	-- -   Xmin, Ymin define the coordinates of the minimum
    	--   point in the lower left hand corner of the selection
    	--   box, and XMax, YMax define the coordinates of
    	--   the maximum point in the upper right hand corner
    	--   of the selection box. The selector looks for areas
    	--   and owners that are touched.

    InitSelect (me : mutable ; Polyline:Array1OfPnt2d from TColgp) is static;
    	---Level: Public 
    	---Purpose: pick action  - input  values of a polyline selection for selection.




    ---Category: RESULT OF SELECTION...
    --           2 Methods : *all the detected objects are given 
    --           (use More - Next - Picked loop)
    --                       *only one is wanted : 
    --           (use More to know if something was picked and OnePicked
    --            to get the closest object of pick position).
    --                       
    --                       

    SortResult(me:mutable) is virtual;
    	---Purpose: Sorts the detected entites by priority and distance.
    	--          to be redefined if other criterion are used...
    
    Init(me:mutable) is static;
    	---Purpose: Begins an iteration scanning for the owners detected at a position in the view.
    	---C++: inline

    More(me:mutable) returns Boolean from Standard is static;
    	---Purpose:  Continues the interation scanning for the owners
    	--   detected at a position in the view, or
    	-- -   continues the iteration scanning for the owner
    	--   closest to the position in the view.
    
    Next(me:mutable) is static;
    	---Purpose: Returns the next owner found in the iteration. This is
    	-- a scan for the owners detected at a position in the view.
   	 ---C++: inline


    Picked(me) returns any EntityOwner is static;
    	---Level: Public 
    	---Purpose: Returns the current selected entity detected by the selector;


    OnePicked(me:mutable) returns any EntityOwner is static;
    	---Purpose: Returns the picked element with the highest priority,
    	-- and which is the closest to the last successful mouse position.

    SetPickClosest(me: mutable; preferClosest: Boolean);
        ---Purpose: Set preference of selecting one object for OnePicked() method:
        -- - If True, objects with less depth (distance fron the view plane) are 
        --   preferred regardless of priority (priority is used then to choose among 
        --   objects with similar depth),
        -- - If False, objects with higher priority are preferred regardless of the
        --   depth which is used to choose among objects of the same priority.
        ---C++: inline


    NbPicked(me) returns Integer from Standard;
    	---Purpose: Returns the number of owners found at a position in
    	-- the view by the Init - More - Next - Picked iteration.

    Picked(me;aRank:Integer from Standard) 
    returns any EntityOwner from SelectMgr;
    	---Purpose: Returns the  entity which is at rank <aRank> 
    	--          in the list of stored ones.


    HasStored (me:mutable) returns Boolean is static;
    	---Level: Public 
    	---Purpose: Returns True if a successful pick was stored,
    	--          i.e. LastPosition method means something... 

    LastPosition (me; Xr,Yr : out Real ) is static;
    	---Level: Public 
    	---Purpose: Gives the last successful pick position;
    	--          is useful to get objects really picked





    ---Category: INFORMATION ABOUT OBJECTS IN THE VIEWER SELECTOR


    Contains (me;aSelectableObject: SelectableObject from SelectMgr) 
    returns Boolean is static;
    

    Modes (me; 
    	   aSelectableObject:SelectableObject from SelectMgr;
    	   ModeList         : in out ListOfInteger from TColStd;
  	   WantedState      : StateOfSelection from SelectMgr = SelectMgr_SOS_Any) returns Boolean;
    	---Purpose: Returns the list of selection modes ModeList found in
    	-- this selector for the selectable object aSelectableObject.
    	-- Returns true if aSelectableObject is referenced inside
    	-- this selector; returns false if the object is not present
    	-- in this selector.

    IsActive  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ; 
    	---Purpose: Returns true if the selectable object
    	-- aSelectableObject having the selection mode aMode
    	-- is active in this selector.    
    
    IsInside  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ;
    	---Purpose: Returns true if the selectable object
    	-- aSelectableObject having the selection mode aMode
    	-- is in this selector.
    
    Status    (me;aSelection :Selection from SelectMgr) returns StateOfSelection from SelectMgr;
    	---Purpose: Returns the selection status Status of the selection aSelection.

    Dump(me;S : in out OStream from Standard);


    Status   (me;aSelectableObject:SelectableObject) returns AsciiString from TCollection is static;
    
    Status   (me) returns  AsciiString from TCollection is static;
    	---Level: Internal 
    	---Purpose: gives general information about the Selector







    ---Category: Internal Methods

		
    NbBoxes(me:mutable) returns Integer is static private;
    	---Level: Internal 

    UpdateSort (me:mutable) is static;
    	---Level: Internal 

    LoadResult (me:mutable) is virtual protected;
    	---Level: Internal 

    LoadResult (me:mutable;aBox:Box2d from Bnd) is virtual protected;
    	---Level: Internal 

    LoadResult (me:mutable;Polyline:Array1OfPnt2d from TColgp) is virtual protected;
    	---Level: Internal 



    Primitive(me;Rank:Integer from Standard)
    returns SensitiveEntity from SelectBasics;
    	---Level: Internal 

    Primitives(me)
    returns DataMapOfIntegerSensitive from SelectMgr;
    ---Level: Internal
    ---C++: inline
    ---C++: return const&

    SetUpdateSortPossible( me: mutable; possible : Boolean from Standard );
    IsUpdateSortPossible( me )  returns Boolean from Standard;


fields

--before selection
    myentities   : DataMapOfIntegerSensitive    is protected;
    myselections : DataMapOfSelectionActivation is protected;
    toupdate     : Boolean is protected;
    tosort       : Boolean is protected;
    preferclosest: Boolean is protected;
--for selection
    mytolerance  : Real is protected;
    myselector   : SortAlgo from SelectBasics is protected;
    myclip       : Box2d    from Bnd is protected;    
    myactivenb   : Integer;
--after selection -results... we sort the list of indexes not the map...
    mystored     : IndexedDataMapOfOwnerCriterion from SelectMgr is protected;
    myIndexes    : HArray1OfInteger  from TColStd;
    myprim       : SequenceOfInteger from TColStd; -- for debug only
    myCurRank    : Integer from Standard;

    lastx        : Real;
    lasty        : Real;

    myUpdateSortPossible : Boolean from Standard;

friends	
    class SelectionManager from SelectMgr

end ViewerSelector;