0024070: OpenGL capped object-level clipping planes
[occt.git] / src / SelectMgr / SelectMgr_ViewerSelector.cdl
1 -- Created on: 1995-02-10
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 --modified by rob -FEB 01 1996
22 --                -JUL 23 1997 : optimize recompute of selections...
23 --                               insert real sleep/awake option....
24 --                -APR 02 1998 : improvment of selection.
25 --                               Sort with new Criterions
26 --                               (depth + size +...)
27 --                               store detected in a best way...
28
29
30 deferred class ViewerSelector from SelectMgr inherits TShared from MMgt 
31
32         ---Purpose: A framework to define finding, sorting the sensitive
33         -- primitives in a view. Services are also provided to
34         -- define the return of the owners of those primitives
35         -- selected. The primitives are sorted by criteria such
36         -- as priority of the primitive or its depth in the view
37         -- relative to that of other primitives.
38         -- This framework is undefined for either 2D or 3D,
39         -- and is consequently used by both
40         -- StdSelect_ViewerSelector2d and
41         -- StdSelect_ViewerSelector3d, which inherit it, and
42         -- which in turn, return 2D and 3D owners of sensitive
43         -- primitives respectively.
44         -- Note that in 3D, the inheriting framework
45         -- StdSelect_ViewerSelector3d   is only to be used
46         -- if you do not want to use the services provided by
47         -- AIS. In 2D, you will, however, need the services
48         -- provided by the StdSelect_ViewerSelector2d.
49         -- Two tools are available to find and select objects
50         -- found at a given position in the view. If you want to
51         -- select the owners of all the objects detected at
52         -- point x,y, you use the Init - More - Next - Picked
53         -- loop. If, on the other hand, you want to select only
54         -- one object detected at that point, you use the Init -
55         -- More - OnePicked loop. In this iteration, More is
56         -- used to see if an object was picked and
57         -- OnePicked, to get the object closest to the pick position.
58         -- Viewer selectors are driven by
59         -- SelectMgr_SelectionManager, and manipulate
60         -- the SelectMgr_Selection objects given to them by
61         -- the selection manager.
62
63 uses
64     AsciiString                  from TCollection,
65     SelectableObject             from SelectMgr,
66     DataMapOfIntegerSensitive    from SelectMgr,
67     DataMapOfSelectionActivation from SelectMgr,
68     Selection                    from SelectMgr,
69     Box2d                        from Bnd,
70     HArray1OfInteger             from TColStd,
71     ListOfInteger                    from TColStd,
72     SequenceOfInteger                from TColStd,
73     MapOfTransient                   from TColStd,
74     IndexedMapOfInteger              from TColStd,
75     IndexedDataMapOfOwnerCriterion   from SelectMgr,
76     SensitiveEntity              from SelectBasics,
77     SortAlgo                     from SelectBasics,
78     EntityOwner                  from SelectMgr,
79     StateOfSelection             from SelectMgr,
80     Array1OfPnt2d                from TColgp,
81     Lin                          from gp
82
83 is
84
85     Initialize ;
86
87
88
89
90     Convert (me:mutable;aSelection : mutable Selection from SelectMgr) is virtual;
91         ---Level: Public 
92         ---Purpose: to be redefined if conversion is necessary for SensitiveEntities...
93             
94             
95             
96    ---Category: Activation/Desactivation Of Selection For Objects 
97    --           No general method like "activate a mode (integer) " is possible
98    --           here because objects inside the selection view are of different type
99    --           
100     
101
102     Activate  (me            : mutable;
103                aSelection    : Selection from SelectMgr;
104                AutomaticProj : Boolean = Standard_True) 
105     is static private;
106         ---Level: Internal
107     
108
109
110
111     ---Category: Management Methods . Some following methods  are private
112     --           because they owed to be called only through The Selection Manager  !!
113
114     Clear(me:mutable) is static;
115         ---Level: Public 
116         ---Purpose: Empties all the tables, removes all selections...
117     
118     UpdateConversion(me :mutable) is static;
119         ---Level: Public 
120         ---Purpose: converts all the sensitive entities ;
121
122     Deactivate (me         : mutable;
123                 aSelection : Selection from SelectMgr)
124     is static private;
125         ---Level: Internal
126
127     Sleep (me:mutable) is static private;
128         ---Level: Internal
129         ---Purpose: Desactivates all the objects of the view;
130         --          no object in this view will be selectable;
131
132     Awake (me :mutable;AutomaticProj : Boolean = Standard_True) is static private;
133         ---Level: Internal
134         ---Purpose: reactivates all the selection which were sleeping....
135
136     Sleep (me       : mutable;
137            anObject : SelectableObject from SelectMgr) is static private;
138     
139     Awake (me       : mutable;
140            anObject : SelectableObject from SelectMgr;
141            AutomaticProj : Boolean = Standard_True) is static private;
142     
143
144     Remove(me:mutable ; aSelection: Selection from SelectMgr) is static private;
145         ---Level: Public 
146         ---Purpose: removes a Selection from the Selector
147
148
149
150             ---Category: SELECTION OPERATIONS 
151             ------------=====================
152
153     SetSensitivity (me : mutable ; aTol:Real) is static;
154         ---Level: Public 
155         ---Purpose: changes the Sensitivity of picking
156         --          Input value is Real.
157
158     Sensitivity (me) returns Real from Standard;
159         ---Level: Public 
160         ---Purpose: returns the Sensitivity of picking
161         ---C++: inline
162
163     SetClipping(me:mutable ; Xc,Yc,Height,Width:Real) is static;
164         ---Level: Public 
165         ---Purpose: sets the clipping limits of dynamic picking
166         --          input value are Real
167
168     SetClipping(me:mutable ; aRectangle : Box2d from Bnd) is static;
169         ---Level: Public 
170         ---Purpose: sets the clipping limits of dynamic picking
171         --          input value are Real
172
173
174     
175
176     InitSelect (me : mutable ; Xr,Yr : Real) is static;
177         ---Level: Public 
178         ---Purpose: Performs a pick action. Xr, Yr   are the real 2D mouse
179         -- coordinates in the view. The selector looks for areas
180         -- and owners that are touched.
181
182     InitSelect (me : mutable ; aRect: Box2d from Bnd) is static;
183         ---Level: Public 
184         ---Purpose: Performs a pick action. aRect is a Box2d (real
185         -- coordinates) for the selection. The selector looks for
186         -- areas and owners that are touched.
187
188     InitSelect (me : mutable ; Xmin,Ymin,Xmax,Ymax: Real) is static;
189         ---Purpose: Performs a pick action
190         -- -   Xmin, Ymin define the coordinates of the minimum
191         --   point in the lower left hand corner of the selection
192         --   box, and XMax, YMax define the coordinates of
193         --   the maximum point in the upper right hand corner
194         --   of the selection box. The selector looks for areas
195         --   and owners that are touched.
196
197     InitSelect (me : mutable ; Polyline:Array1OfPnt2d from TColgp) is static;
198         ---Level: Public 
199         ---Purpose: pick action  - input  values of a polyline selection for selection.
200
201
202
203
204     ---Category: RESULT OF SELECTION...
205     --           2 Methods : *all the detected objects are given 
206     --           (use More - Next - Picked loop)
207     --                       *only one is wanted : 
208     --           (use More to know if something was picked and OnePicked
209     --            to get the closest object of pick position).
210     --                       
211     --                       
212
213     SortResult(me:mutable) is virtual;
214         ---Purpose: Sorts the detected entites by priority and distance.
215         --          to be redefined if other criterion are used...
216     
217     Init(me:mutable) is static;
218         ---Purpose: Begins an iteration scanning for the owners detected at a position in the view.
219         ---C++: inline
220
221     More(me:mutable) returns Boolean from Standard is static;
222         ---Purpose:  Continues the interation scanning for the owners
223         --   detected at a position in the view, or
224         -- -   continues the iteration scanning for the owner
225         --   closest to the position in the view.
226     
227     Next(me:mutable) is static;
228         ---Purpose: Returns the next owner found in the iteration. This is
229         -- a scan for the owners detected at a position in the view.
230          ---C++: inline
231
232
233     Picked(me) returns EntityOwner from SelectMgr is static;
234         ---Level: Public 
235         ---Purpose: Returns the current selected entity detected by the selector;
236
237
238     OnePicked(me:mutable) returns EntityOwner from SelectMgr is static;
239         ---Purpose: Returns the picked element with the highest priority,
240         -- and which is the closest to the last successful mouse position.
241
242     SetPickClosest(me: mutable; preferClosest: Boolean);
243         ---Purpose: Set preference of selecting one object for OnePicked() method:
244         -- - If True, objects with less depth (distance fron the view plane) are 
245         --   preferred regardless of priority (priority is used then to choose among 
246         --   objects with similar depth),
247         -- - If False, objects with higher priority are preferred regardless of the
248         --   depth which is used to choose among objects of the same priority.
249         ---C++: inline
250
251
252     NbPicked(me) returns Integer from Standard;
253         ---Purpose: Returns the number of owners found at a position in
254         -- the view by the Init - More - Next - Picked iteration.
255
256     Picked(me;aRank:Integer from Standard) 
257     returns any EntityOwner from SelectMgr;
258         ---Purpose: Returns the  entity which is at rank <aRank> 
259         --          in the list of stored ones.
260
261
262     HasStored (me:mutable) returns Boolean is static;
263         ---Level: Public 
264         ---Purpose: Returns True if a successful pick was stored,
265         --          i.e. LastPosition method means something... 
266
267     LastPosition (me; Xr,Yr : out Real ) is static;
268         ---Level: Public 
269         ---Purpose: Gives the last successful pick position;
270         --          is useful to get objects really picked
271
272
273
274
275
276     ---Category: INFORMATION ABOUT OBJECTS IN THE VIEWER SELECTOR
277
278
279     Contains (me;aSelectableObject: SelectableObject from SelectMgr) 
280     returns Boolean is static;
281     
282
283     Modes (me; 
284            aSelectableObject:SelectableObject from SelectMgr;
285            ModeList         : in out ListOfInteger from TColStd;
286            WantedState      : StateOfSelection from SelectMgr = SelectMgr_SOS_Any) returns Boolean;
287         ---Purpose: Returns the list of selection modes ModeList found in
288         -- this selector for the selectable object aSelectableObject.
289         -- Returns true if aSelectableObject is referenced inside
290         -- this selector; returns false if the object is not present
291         -- in this selector.
292
293     IsActive  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ; 
294         ---Purpose: Returns true if the selectable object
295         -- aSelectableObject having the selection mode aMode
296         -- is active in this selector.    
297     
298     IsInside  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ;
299         ---Purpose: Returns true if the selectable object
300         -- aSelectableObject having the selection mode aMode
301         -- is in this selector.
302     
303     Status    (me;aSelection :Selection from SelectMgr) returns StateOfSelection from SelectMgr;
304         ---Purpose: Returns the selection status Status of the selection aSelection.
305
306     Dump(me;S : in out OStream from Standard);
307
308
309     Status   (me;aSelectableObject:SelectableObject) returns AsciiString from TCollection is static;
310     
311     Status   (me) returns  AsciiString from TCollection is static;
312         ---Level: Internal 
313         ---Purpose: gives general information about the Selector
314
315
316
317
318
319
320
321     ---Category: Internal Methods
322
323                 
324     NbBoxes(me:mutable) returns Integer is static private;
325         ---Level: Internal 
326
327     UpdateSort (me:mutable) is static;
328         ---Level: Internal 
329
330     LoadResult (me:mutable) is virtual protected;
331         ---Level: Internal 
332
333     LoadResult (me:mutable;aBox:Box2d from Bnd) is virtual protected;
334         ---Level: Internal 
335
336     LoadResult (me:mutable;Polyline:Array1OfPnt2d from TColgp) is virtual protected;
337         ---Level: Internal 
338
339
340
341     Primitive(me;Rank:Integer from Standard)
342     returns SensitiveEntity from SelectBasics;
343         ---Level: Internal 
344
345     Primitives(me)
346     returns DataMapOfIntegerSensitive from SelectMgr;
347     ---Level: Internal
348     ---C++: inline
349     ---C++: return const&
350
351     SetUpdateSortPossible( me: mutable; possible : Boolean from Standard );
352     IsUpdateSortPossible( me )  returns Boolean from Standard;
353
354     PickingLine (me; theX, theY : Real from Standard)
355       returns Lin from gp
356       is virtual protected;
357     ---Level: Internal
358     ---Purpose: Returns picking line along which the depth value should be
359     -- computed. Override this method to compute picking line by the same
360     -- which is used for projecting sensitive entities to selection space.
361     -- @param theX [in] the x picking coordinate.
362     -- @param theY [in] the y picking coordinate.
363     -- @return picking line.
364
365     DepthClipping (me; theX, theY : Real from Standard;
366                    theMin, theMax : out Real from Standard)
367       is virtual protected;
368     ---Level: Internal
369     ---Purpose: Returns global depth clipping limits applied to every sensitive.
370     -- Override this method to convert clippings defined by application into
371     -- selection space for mouse picking detection.
372     -- Default implementation returns infinite clip limits (no clipping).
373     -- @param theX [in] the x picking coordinate.
374     -- @param theY [in] the y picking coordinate.
375     -- @param theMin [out] the minimum depth. Default is RealFirst()
376     -- @param theMax [out] the maximum depth. Default is RealLast()
377
378     DepthClipping (me; theX, theY : Real from Standard;
379                    theOwner : EntityOwner from SelectMgr;
380                    theMin, theMax : out Real from Standard)
381       is virtual protected;
382     ---Level: Internal
383     ---Purpose: Returns depth clipping limits applied to sensitives of
384     -- entity owner. Override this method to convert clippings defined by
385     -- application owners into selection space for mouse picking detection.
386     -- Default implementation returns infinite clip limits (no clipping).
387     -- @param theX [in] the x picking coordinate.
388     -- @param theY [in] the y picking coordinate.
389     -- @param theOwner [in] the sensitive owner.
390     -- @param theMin [out] the minimum depth. Default is RealFirst()
391     -- @param theMax [out] the maximum depth. Default is RealLast()
392
393     HasDepthClipping (me; theOwner : EntityOwner from SelectMgr)
394       returns Boolean is virtual protected;
395     ---Level: Internal
396     ---Purpose: Returns True if the owner provides clipping by depth
397     -- for its sensitives. Override this method to tell the selector
398     -- to use the DepthClipping method for the owner.
399     -- Default implementation returns False for every owner.
400     -- @param theOwner [in] the onwer to check.
401     -- @return True if owner provides depth limits for sensitive clipping.
402
403 fields
404
405 --before selection
406     myentities   : DataMapOfIntegerSensitive    is protected;
407     myselections : DataMapOfSelectionActivation is protected;
408     toupdate     : Boolean is protected;
409     tosort       : Boolean is protected;
410     preferclosest: Boolean is protected;
411 --for selection
412     mytolerance  : Real is protected;
413     myselector   : SortAlgo from SelectBasics is protected;
414     myclip       : Box2d    from Bnd is protected;    
415     myactivenb   : Integer;
416 --after selection -results... we sort the list of indexes not the map...
417     mystored     : IndexedDataMapOfOwnerCriterion from SelectMgr is protected;
418     myIndexes    : HArray1OfInteger  from TColStd;
419     myprim       : SequenceOfInteger from TColStd; -- for debug only
420     myCurRank    : Integer from Standard;
421
422     lastx        : Real;
423     lasty        : Real;
424
425     myUpdateSortPossible : Boolean from Standard;
426
427 friends 
428     class SelectionManager from SelectMgr
429
430 end ViewerSelector;
431
432
433
434
435
436
437
438
439
440
441
442