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