69e10548940ba5fd94bd808f0ee4173c69a6da01
[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     
82 is
83
84     Initialize ;
85
86
87
88
89     Convert (me:mutable;aSelection : mutable Selection from SelectMgr) is virtual;
90         ---Level: Public 
91         ---Purpose: to be redefined if conversion is necessary for SensitiveEntities...
92             
93             
94             
95    ---Category: Activation/Desactivation Of Selection For Objects 
96    --           No general method like "activate a mode (integer) " is possible
97    --           here because objects inside the selection view are of different type
98    --           
99     
100
101     Activate  (me            : mutable;
102                aSelection    : Selection from SelectMgr;
103                AutomaticProj : Boolean = Standard_True) 
104     is static private;
105         ---Level: Internal
106     
107
108
109
110     ---Category: Management Methods . Some following methods  are private
111     --           because they owed to be called only through The Selection Manager  !!
112
113     Clear(me:mutable) is static;
114         ---Level: Public 
115         ---Purpose: Empties all the tables, removes all selections...
116     
117     UpdateConversion(me :mutable) is static;
118         ---Level: Public 
119         ---Purpose: converts all the sensitive entities ;
120
121     Deactivate (me         : mutable;
122                 aSelection : Selection from SelectMgr)
123     is static private;
124         ---Level: Internal
125
126     Sleep (me:mutable) is static private;
127         ---Level: Internal
128         ---Purpose: Desactivates all the objects of the view;
129         --          no object in this view will be selectable;
130
131     Awake (me :mutable;AutomaticProj : Boolean = Standard_True) is static private;
132         ---Level: Internal
133         ---Purpose: reactivates all the selection which were sleeping....
134
135     Sleep (me       : mutable;
136            anObject : SelectableObject from SelectMgr) is static private;
137     
138     Awake (me       : mutable;
139            anObject : SelectableObject from SelectMgr;
140            AutomaticProj : Boolean = Standard_True) is static private;
141     
142
143     Remove(me:mutable ; aSelection: Selection from SelectMgr) is static private;
144         ---Level: Public 
145         ---Purpose: removes a Selection from the Selector
146
147
148
149             ---Category: SELECTION OPERATIONS 
150             ------------=====================
151
152     SetSensitivity (me : mutable ; aTol:Real) is static;
153         ---Level: Public 
154         ---Purpose: changes the Sensitivity of picking
155         --          Input value is Real.
156
157     Sensitivity (me) returns Real from Standard;
158         ---Level: Public 
159         ---Purpose: returns the Sensitivity of picking
160         ---C++: inline
161
162     SetClipping(me:mutable ; Xc,Yc,Height,Width:Real) is static;
163         ---Level: Public 
164         ---Purpose: sets the clipping limits of dynamic picking
165         --          input value are Real
166
167     SetClipping(me:mutable ; aRectangle : Box2d from Bnd) is static;
168         ---Level: Public 
169         ---Purpose: sets the clipping limits of dynamic picking
170         --          input value are Real
171
172
173     
174
175     InitSelect (me : mutable ; Xr,Yr : Real) is static;
176         ---Level: Public 
177         ---Purpose: Performs a pick action. Xr, Yr   are the real 2D mouse
178         -- coordinates in the view. The selector looks for areas
179         -- and owners that are touched.
180
181     InitSelect (me : mutable ; aRect: Box2d from Bnd) is static;
182         ---Level: Public 
183         ---Purpose: Performs a pick action. aRect is a Box2d (real
184         -- coordinates) for the selection. The selector looks for
185         -- areas and owners that are touched.
186
187     InitSelect (me : mutable ; Xmin,Ymin,Xmax,Ymax: Real) is static;
188         ---Purpose: Performs a pick action
189         -- -   Xmin, Ymin define the coordinates of the minimum
190         --   point in the lower left hand corner of the selection
191         --   box, and XMax, YMax define the coordinates of
192         --   the maximum point in the upper right hand corner
193         --   of the selection box. The selector looks for areas
194         --   and owners that are touched.
195
196     InitSelect (me : mutable ; Polyline:Array1OfPnt2d from TColgp) is static;
197         ---Level: Public 
198         ---Purpose: pick action  - input  values of a polyline selection for selection.
199
200
201
202
203     ---Category: RESULT OF SELECTION...
204     --           2 Methods : *all the detected objects are given 
205     --           (use More - Next - Picked loop)
206     --                       *only one is wanted : 
207     --           (use More to know if something was picked and OnePicked
208     --            to get the closest object of pick position).
209     --                       
210     --                       
211
212     SortResult(me:mutable) is virtual;
213         ---Purpose: Sorts the detected entites by priority and distance.
214         --          to be redefined if other criterion are used...
215     
216     Init(me:mutable) is static;
217         ---Purpose: Begins an iteration scanning for the owners detected at a position in the view.
218         ---C++: inline
219
220     More(me:mutable) returns Boolean from Standard is static;
221         ---Purpose:  Continues the interation scanning for the owners
222         --   detected at a position in the view, or
223         -- -   continues the iteration scanning for the owner
224         --   closest to the position in the view.
225     
226     Next(me:mutable) is static;
227         ---Purpose: Returns the next owner found in the iteration. This is
228         -- a scan for the owners detected at a position in the view.
229          ---C++: inline
230
231
232     Picked(me) returns any EntityOwner is static;
233         ---Level: Public 
234         ---Purpose: Returns the current selected entity detected by the selector;
235
236
237     OnePicked(me:mutable) returns any EntityOwner is static;
238         ---Purpose: Returns the picked element with the highest priority,
239         -- and which is the closest to the last successful mouse position.
240
241     SetPickClosest(me: mutable; preferClosest: Boolean);
242         ---Purpose: Set preference of selecting one object for OnePicked() method:
243         -- - If True, objects with less depth (distance fron the view plane) are 
244         --   preferred regardless of priority (priority is used then to choose among 
245         --   objects with similar depth),
246         -- - If False, objects with higher priority are preferred regardless of the
247         --   depth which is used to choose among objects of the same priority.
248         ---C++: inline
249
250
251     NbPicked(me) returns Integer from Standard;
252         ---Purpose: Returns the number of owners found at a position in
253         -- the view by the Init - More - Next - Picked iteration.
254
255     Picked(me;aRank:Integer from Standard) 
256     returns any EntityOwner from SelectMgr;
257         ---Purpose: Returns the  entity which is at rank <aRank> 
258         --          in the list of stored ones.
259
260
261     HasStored (me:mutable) returns Boolean is static;
262         ---Level: Public 
263         ---Purpose: Returns True if a successful pick was stored,
264         --          i.e. LastPosition method means something... 
265
266     LastPosition (me; Xr,Yr : out Real ) is static;
267         ---Level: Public 
268         ---Purpose: Gives the last successful pick position;
269         --          is useful to get objects really picked
270
271
272
273
274
275     ---Category: INFORMATION ABOUT OBJECTS IN THE VIEWER SELECTOR
276
277
278     Contains (me;aSelectableObject: SelectableObject from SelectMgr) 
279     returns Boolean is static;
280     
281
282     Modes (me; 
283            aSelectableObject:SelectableObject from SelectMgr;
284            ModeList         : in out ListOfInteger from TColStd;
285            WantedState      : StateOfSelection from SelectMgr = SelectMgr_SOS_Any) returns Boolean;
286         ---Purpose: Returns the list of selection modes ModeList found in
287         -- this selector for the selectable object aSelectableObject.
288         -- Returns true if aSelectableObject is referenced inside
289         -- this selector; returns false if the object is not present
290         -- in this selector.
291
292     IsActive  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ; 
293         ---Purpose: Returns true if the selectable object
294         -- aSelectableObject having the selection mode aMode
295         -- is active in this selector.    
296     
297     IsInside  (me;aSelectableObject:SelectableObject;aMode:Integer) returns  Boolean is static ;
298         ---Purpose: Returns true if the selectable object
299         -- aSelectableObject having the selection mode aMode
300         -- is in this selector.
301     
302     Status    (me;aSelection :Selection from SelectMgr) returns StateOfSelection from SelectMgr;
303         ---Purpose: Returns the selection status Status of the selection aSelection.
304
305     Dump(me;S : in out OStream from Standard);
306
307
308     Status   (me;aSelectableObject:SelectableObject) returns AsciiString from TCollection is static;
309     
310     Status   (me) returns  AsciiString from TCollection is static;
311         ---Level: Internal 
312         ---Purpose: gives general information about the Selector
313
314
315
316
317
318
319
320     ---Category: Internal Methods
321
322                 
323     NbBoxes(me:mutable) returns Integer is static private;
324         ---Level: Internal 
325
326     UpdateSort (me:mutable) is static;
327         ---Level: Internal 
328
329     LoadResult (me:mutable) is virtual protected;
330         ---Level: Internal 
331
332     LoadResult (me:mutable;aBox:Box2d from Bnd) is virtual protected;
333         ---Level: Internal 
334
335     LoadResult (me:mutable;Polyline:Array1OfPnt2d from TColgp) is virtual protected;
336         ---Level: Internal 
337
338
339
340     Primitive(me;Rank:Integer from Standard)
341     returns SensitiveEntity from SelectBasics;
342         ---Level: Internal 
343
344     Primitives(me)
345     returns DataMapOfIntegerSensitive from SelectMgr;
346     ---Level: Internal
347     ---C++: inline
348     ---C++: return const&
349
350     SetUpdateSortPossible( me: mutable; possible : Boolean from Standard );
351     IsUpdateSortPossible( me )  returns Boolean from Standard;
352
353
354 fields
355
356 --before selection
357     myentities   : DataMapOfIntegerSensitive    is protected;
358     myselections : DataMapOfSelectionActivation is protected;
359     toupdate     : Boolean is protected;
360     tosort       : Boolean is protected;
361     preferclosest: Boolean is protected;
362 --for selection
363     mytolerance  : Real is protected;
364     myselector   : SortAlgo from SelectBasics is protected;
365     myclip       : Box2d    from Bnd is protected;    
366     myactivenb   : Integer;
367 --after selection -results... we sort the list of indexes not the map...
368     mystored     : IndexedDataMapOfOwnerCriterion from SelectMgr is protected;
369     myIndexes    : HArray1OfInteger  from TColStd;
370     myprim       : SequenceOfInteger from TColStd; -- for debug only
371     myCurRank    : Integer from Standard;
372
373     lastx        : Real;
374     lasty        : Real;
375
376     myUpdateSortPossible : Boolean from Standard;
377
378 friends 
379     class SelectionManager from SelectMgr
380
381 end ViewerSelector;
382
383
384
385
386
387
388
389
390
391
392
393