OCCT/src/SelectBasics/SelectBasics_SensitiveEntity.cdl

-- Created on: 1995-01-23
-- Created by: Mister rmi
-- Copyright (c) 1995-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.



deferred class SensitiveEntity from SelectBasics inherits TShared from MMgt

	---Purpose: root class ; the inheriting classes will be able to give
	--          sensitive Areas for the dynamic selection algorithms

uses 
    EntityOwner,
    ListOfBox2d,
    PickArgs,
    Array1OfPnt2d from TColgp,
    Box2d from Bnd

is


    Initialize (OwnerId            : EntityOwner;
    	    	aSensitivityFactor : ShortReal from Standard =1);
    
    
    Set (me:mutable ; TheOwnerId : EntityOwner) is virtual;
    ---Level: Public 
    

    OwnerId(me) returns any EntityOwner is static;
    ---Level: Public 
    ---C++: return const&
    	    
    
    Areas(me:mutable; aresult : in out ListOfBox2d ) is deferred;  
    ---Level: Public 
    ---Purpose: to be implemented specifically by each type of
    --          sensitive  primitive .
    --          

    Matches (me : mutable;
             thePickArgs : PickArgs from SelectBasics;
             theMatchDMin : out Real from Standard;
             theMatchDepth : out Real from Standard) returns Boolean is deferred;
    ---Level: Public
    ---Purpose: Checks whether the sensitive entity matches the picking detection
    -- area (close to the picking line). This method takes into account depth
    -- limits produced by abstract view: far/near planes, clippings.
    -- Please port existing implementations of your picking detection, which
    -- were done at Matches (X, Y, Tol, DMin) method to this one, introducing
    -- the depth checks. Please note that the previous method is suppressed
    -- and the virtual implementations are not used by OCC selection framework.
    -- The porting procedure for simple sensitives (or if you are not interested
    -- in implementing full scale depth checks) can be simplified to writing the
    -- following code snippet:
    -- @code
    -- { // example code for porting descendants of Select3D_SensitiveEntity
    --
    --   // invoke implementation of obsolete matches method (if implemented)...
    --   if (!Matches (thePickArgs.X(), thePickArgs.Y(), thePickArgs.Tolerance(), theMatchDMin))
    --     return Standard_False;
    --
    --   // invoke your implementation of computing depth (if implemented)...
    --   Standard_Real aDetectDepth = ComputeDepth (thePickArgs.PickLine());
    --
    --   return !thePickArgs.IsClipped(aDetectDepth);
    -- }
    -- @endcode
    -- @param thePickArgs [in] the picking arguments.
    -- @param theMatchDMin [out] the minimum distance on xy plane from point
    -- of picking to center of gravity of the detected sub-part of sensitive
    -- entity or the whole sensitive (e.g. used for resolving selection of
    -- coinciding circles, selection will be set to the one whose center is
    -- closest to the picking point).
    -- @param theMatchDepth [out] the minimum detected depth: depth of the 
    -- closest detected sub-part of sensitive entity (or the whole sensitive).
    -- @return True if the sensitive matches the detection area.
    -- This method is an entry point for picking detection framework.
    -- The method is triggered when it is required to compose list of
    -- detected sensitive entities. The sensitives are filtered out from
    -- detection result if returned value is False. The passed entities are
    -- then can be sorted by "theDetectDist", "theDetectDepth" parameters.

    Matches (me  :mutable; 
             XMin,YMin,XMax,YMax : Real from Standard;
             aTol: Real from Standard)
    returns Boolean
    is deferred;    
    ---Level: Public 
    ---Purpose: returns True if the box (Xmin,YMin)------(Xmax,Ymax)
    --          contains the SensitiveEntity. 
    --          Necessary for selection using elastic boxes,or segments.


    Matches (me  :mutable; 
             Polyline:Array1OfPnt2d from TColgp;
	     aBox:Box2d from Bnd;
             aTol: Real from Standard)
    returns Boolean
    is deferred;    
    ---Level: Public 
    ---Purpose: returns True if the polyline xi,yi
    --          contains the SensitiveEntity. 
    --          Necessary for selection using polyline selection

    NeedsConversion(me) returns Boolean is deferred ;
    
    Is3D(me) returns Boolean from Standard is deferred;
    ---Purpose: returns True if able to give 3D information
    --          (Depth,...). See Select3D
    
    MaxBoxes(me) returns Integer is deferred;
    ---Purpose: returns the max number of boxes the entity is able to give
    --          at a time


    SetSensitivityFactor(me:mutable; aFactor:ShortReal from Standard);
    ---C++: inline

    SensitivityFactor(me) returns ShortReal from Standard;
    ---C++: inline
    ---Purpose: allows a better sensitivity for
    --          a specific entity in selection algorithms
    --          useful for small sized entities.


fields
    
    myOwnerId       : EntityOwner from SelectBasics is protected;
    mySFactor       : ShortReal from Standard;
end SensitiveEntity;