0024070: OpenGL capped object-level clipping planes
[occt.git] / src / SelectBasics / SelectBasics_SensitiveEntity.cdl
1 -- Created on: 1995-01-23
2 -- Created by: Mister rmi
3 -- Copyright (c) 1995-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
5 --
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
10 --
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13 --
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
20
21
22
23 deferred class SensitiveEntity from SelectBasics inherits TShared from MMgt
24
25         ---Purpose: root class ; the inheriting classes will be able to give
26         --          sensitive Areas for the dynamic selection algorithms
27
28 uses 
29     EntityOwner,
30     ListOfBox2d,
31     PickArgs,
32     Array1OfPnt2d from TColgp,
33     Box2d from Bnd
34
35 is
36
37
38     Initialize (OwnerId            : EntityOwner;
39                 aSensitivityFactor : ShortReal from Standard =1);
40     
41     
42     Set (me:mutable ; TheOwnerId : EntityOwner) is virtual;
43     ---Level: Public 
44     
45
46     OwnerId(me) returns any EntityOwner is static;
47     ---Level: Public 
48     ---C++: return const&
49             
50     
51     Areas(me:mutable; aresult : in out ListOfBox2d ) is deferred;  
52     ---Level: Public 
53     ---Purpose: to be implemented specifically by each type of
54     --          sensitive  primitive .
55     --          
56
57     Matches (me : mutable;
58              thePickArgs : PickArgs from SelectBasics;
59              theMatchDMin : out Real from Standard;
60              theMatchDepth : out Real from Standard) returns Boolean is deferred;
61     ---Level: Public
62     ---Purpose: Checks whether the sensitive entity matches the picking detection
63     -- area (close to the picking line). This method takes into account depth
64     -- limits produced by abstract view: far/near planes, clippings.
65     -- Please port existing implementations of your picking detection, which
66     -- were done at Matches (X, Y, Tol, DMin) method to this one, introducing
67     -- the depth checks. Please note that the previous method is suppressed
68     -- and the virtual implementations are not used by OCC selection framework.
69     -- The porting procedure for simple sensitives (or if you are not interested
70     -- in implementing full scale depth checks) can be simplified to writing the
71     -- following code snippet:
72     -- @code
73     -- { // example code for porting descendants of Select3D_SensitiveEntity
74     --
75     --   // invoke implementation of obsolete matches method (if implemented)...
76     --   if (!Matches (thePickArgs.X(), thePickArgs.Y(), thePickArgs.Tolerance(), theMatchDMin))
77     --     return Standard_False;
78     --
79     --   // invoke your implementation of computing depth (if implemented)...
80     --   Standard_Real aDetectDepth = ComputeDepth (thePickArgs.PickLine());
81     --
82     --   return !thePickArgs.IsClipped(aDetectDepth);
83     -- }
84     -- @endcode
85     -- @param thePickArgs [in] the picking arguments.
86     -- @param theMatchDMin [out] the minimum distance on xy plane from point
87     -- of picking to center of gravity of the detected sub-part of sensitive
88     -- entity or the whole sensitive (e.g. used for resolving selection of
89     -- coinciding circles, selection will be set to the one whose center is
90     -- closest to the picking point).
91     -- @param theMatchDepth [out] the minimum detected depth: depth of the 
92     -- closest detected sub-part of sensitive entity (or the whole sensitive).
93     -- @return True if the sensitive matches the detection area.
94     -- This method is an entry point for picking detection framework.
95     -- The method is triggered when it is required to compose list of
96     -- detected sensitive entities. The sensitives are filtered out from
97     -- detection result if returned value is False. The passed entities are
98     -- then can be sorted by "theDetectDist", "theDetectDepth" parameters.
99
100     Matches (me  :mutable; 
101              XMin,YMin,XMax,YMax : Real from Standard;
102              aTol: Real from Standard)
103     returns Boolean
104     is deferred;    
105     ---Level: Public 
106     ---Purpose: returns True if the box (Xmin,YMin)------(Xmax,Ymax)
107     --          contains the SensitiveEntity. 
108     --          Necessary for selection using elastic boxes,or segments.
109
110
111     Matches (me  :mutable; 
112              Polyline:Array1OfPnt2d from TColgp;
113              aBox:Box2d from Bnd;
114              aTol: Real from Standard)
115     returns Boolean
116     is deferred;    
117     ---Level: Public 
118     ---Purpose: returns True if the polyline xi,yi
119     --          contains the SensitiveEntity. 
120     --          Necessary for selection using polyline selection
121
122     NeedsConversion(me) returns Boolean is deferred ;
123     
124     Is3D(me) returns Boolean from Standard is deferred;
125     ---Purpose: returns True if able to give 3D information
126     --          (Depth,...). See Select3D
127     
128     MaxBoxes(me) returns Integer is deferred;
129     ---Purpose: returns the max number of boxes the entity is able to give
130     --          at a time
131
132
133     SetSensitivityFactor(me:mutable; aFactor:ShortReal from Standard);
134     ---C++: inline
135
136     SensitivityFactor(me) returns ShortReal from Standard;
137     ---C++: inline
138     ---Purpose: allows a better sensitivity for
139     --          a specific entity in selection algorithms
140     --          useful for small sized entities.
141
142
143 fields
144     
145     myOwnerId       : EntityOwner from SelectBasics is protected;
146     mySFactor       : ShortReal from Standard;
147 end SensitiveEntity;
148
149
150
151
152