src/SelectMgr/SelectMgr.cdl

   1 -- Created on: 1995-02-06
   2 -- Created by: Mister rmi
   3 -- Copyright (c) 1995-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 package SelectMgr
  18
  19         ---Purpose: SelectMgr manages the process of dynamic
  20         -- selection through the following services:
  21         -- -   activating and deactivating selection modes for Interactive Objects
  22         -- -   adding and removing viewer selectors
  23         -- -   definitions of abstract filter classes
  24         --  The principle of graphic selection consists in
  25         -- representing the objects which you want to select
  26         -- by a bounding box in the selection view. The object
  27         -- is selected when you use the mouse to designate
  28         -- the zone produced by the object.
  29         -- To realize this, the application creates a selection
  30         -- structure which is independent of the point of view.
  31         -- This structure is made up of sensitive primitives
  32         -- which have one owner object associated to each of
  33         -- them. The role of the sensitive primitive is to reply
  34         -- to the requests of the selection algorithm whereas
  35         -- the owner's purpose is to make the link between
  36         -- the sensitive primitive and the object to be selected.
  37         -- Each selection structure corresponds to a selection
  38         -- mode which defines the elements that can be selected.
  39         -- For example, to select a complete geometric model,
  40         -- the application can create a sensitive primitive for
  41         -- each face of the interactive object representing the
  42         -- geometric model. In this case, all the primitives
  43         -- share the same owner. On the other hand, to select
  44         -- an edge in a model, the application must create
  45         -- one sensitive primitive per edge.
  46         -- Example
  47         -- void
  48         -- InteractiveBox::ComputeSelection
  49         --       (const Handle(SelectMgr_Selection)& Sel,
  50         --        const Standard_Integer Mode){ switch(Mode){ case 0:
  51         -- // locating the whole box by making its faces sensitive ...
  52         --          {
  53         -- Handle(SelectMgr_EntityOwner)
  54         --  Ownr = new
  55         -- SelectMgr_EntityOwner(this,5);
  56         --        for(Standard_Integer
  57         -- I=1;I<=Nbfaces;I++){Sel->Add(new Select3D_SensitiveFace
  58         --                (Ownr,[array of the vertices] face I);
  59         --        break;
  60         --        }
  61         -- case 1:         // locates the   edges
  62         --          {
  63         --        for(Standard_Integer
  64         --  i=1;i<=12;i++){
  65         --                         // 1 owner per edge...
  66         --          Handle(mypk_EdgeOwner)
  67         --  Ownr = new
  68         -- mypk_EdgeOwner(this,i,6);
  69         --                         // 6->priority
  70         --          Sel->Add(new
  71         --          Select3D_SensitiveSegment
  72         --                   (Ownr,firstpt(i),lastpt(i));
  73         --        }
  74         --        }
  75         -- }
  76         -- The algorithms for creating selection structures
  77         -- store the sensitive primitives in a
  78         -- SelectMgr_Selection object. To do this, a set of
  79         -- ready-made sensitive primitives is supplied in the
  80         -- Select2D and Select3D packages. New sensitive
  81         -- primitives can be defined through inheritance
  82         -- from   SensitiveEntity. For the application to make
  83         -- its own objects selectable, it must define owner
  84         -- classes inheriting SelectMgr_EntityOwner.
  85         -- For any object inheriting from
  86         -- AIS_InteractiveObject, you redefine its
  87         -- ComputeSelection functions. In the example below
  88         -- there are different modes of selection on the
  89         -- topological shape contained within the interactive
  90         -- object -selection of the shape itself, the vertices,
  91         -- the edges, the wires, the faces.
  92         -- Example
  93         -- void
  94         -- MyPack_MyClass::ComputeSelection(
  95         --             const Handle(SelectMgr_Selection)& aSelection,
  96         --             const Standard_Integer aMode)
  97         -- {
  98         --    switch(aMode){
  99         --   case 0:
 100         --   StdSelect_BRepSelectionTool::Load(
 101         --      aSelection,this,myShape,TopAbs_SHAPE);
 102         --   break;
 103         --   }
 104         --   case 1:
 105         --   StdSelect_BRepSelectionTool::Load(
 106         --      aSelection,this,myShape,TopAbs_VERTEX);
 107         --   break;
 108         --   }
 109         --    case 2:
 110         --    StdSelect_BRepSelectionTool::Load(
 111         --       aSelection,this,myShape,TopAbs_EDGE);
 112         --    break;
 113         --    }
 114         --    case 3:
 115         --    StdSelect_BRepSelectionTool::Load(
 116         --       aSelection,this,myShape,TopAbs_WIRE);
 117         --    break;
 118         --    }
 119         --    case 4:
 120         --    StdSelect_BRepSelectionTool::Load(
 121         --       aSelection,this,myShape,TopAbs_FACE);
 122         --    break;
 123         --    }
 124         -- }
 125         -- The StdSelect_BRepSelectionTool object
 126         -- provides a high level service which will make the
 127         -- shape 'myShape' selectable when the
 128         -- AIS_InteractiveContext is asked to display your object.
 129         --   Note: The traditional way of highlighting selected entity
 130         -- owners adopted by the Open CASCADE library assumes that
 131         -- each entity owner highlights itself on its own. This approach
 132         -- has two drawbacks:
 133         --      -      each entity owner has to maintain its own
 134         --         Prs3d_Presentation object, that results in
 135         --         large memory overhead for thousands of owners;
 136         --      -      drawing selected owners one by one is not
 137         --         efficient from the OpenGL usage viewpoint.
 138         -- That is why a different method has been introduced. On the basis of
 139         -- SelectMgr_EntityOwner::IsAutoHilight() return value an AIS_LocalContext
 140         -- object either uses the traditional way of highlighting
 141         -- (IsAutoHilight() returned true) or groups such owners according
 142         -- to their Selectable Objects and finally calls
 143         -- SelectMgr_SelectableObject::HilightSelected()
 144         -- or ClearSelected(), passing a group of owners as an argument.
 145         -- Hence, an application can derive its own interactive object and
 146         -- redefine HilightSelected(), ClearSelected() and
 147         -- HilightOwnerWithColor() virtual methods to take advantage of
 148         -- such OpenGL technique as arrays of primitives. In any case,
 149         -- these methods should at least have empty implementation.
 150         -- The AIS_LocalContext::UpdateSelected(const Handle(AIS_InteratciveObject)&,
 151         -- Standard_Boolean) method can be used for efficient redrawing a
 152         -- selection presentation for a given interactive object from an
 153         -- application code.
 154         -- Additionally, the SelectMgr_SelectableObject::ClearSelections()
 155         -- method now accepts an optional boolean argument. This parameter
 156         -- defines whether all object selections should be flagged for
 157         -- further update or not. This improved method can be used to
 158         -- re-compute an object selection (without redisplaying the object
 159         -- completely) when some selection mode is activated not for the first time.
 160
 161 uses
 162     Standard,
 163     MMgt,
 164     TCollection,
 165     TColStd,
 166     TColgp,
 167     Quantity,
 168     Bnd,
 169     TopLoc,
 170     TopAbs,
 171     TopoDS,
 172     SelectBasics,
 173     PrsMgr,
 174     Prs3d,
 175     Graphic3d,
 176     gp
 177
 178
 179 is
 180
 181     enumeration StateOfSelection is
 182         SOS_Activated,
 183         SOS_Deactivated,
 184         SOS_Sleeping,
 185         SOS_Any,
 186         SOS_Unknown;
 187         ---Purpose: different state of a Selection in a ViewerSelector...
 188
 189
 190     enumeration TypeOfUpdate is TOU_Full,TOU_Partial,TOU_None;
 191         ---Purpose: Provides values for types of update, including
 192         -- -   full
 193         -- -   partial
 194         -- -   none.
 195     deferred class SelectableObject;
 196
 197     deferred class ViewerSelector;
 198
 199     deferred class Filter;
 200
 201     deferred class CompositionFilter;
 202
 203     class AndFilter;
 204
 205     class OrFilter;
 206
 207
 208
 209
 210     class EntityOwner;
 211
 212     class Selection;
 213
 214     class  SelectionManager;
 215
 216     ---Category: instantiations of classes from TCollection...
 217
 218     class SequenceOfFilter instantiates Sequence from TCollection
 219     (Filter from SelectMgr);
 220
 221     class ListOfFilter instantiates List from TCollection
 222     (Filter from SelectMgr);
 223
 224     class SequenceOfOwner instantiates Sequence from TCollection
 225     (EntityOwner from SelectMgr);
 226
 227     class IndexedMapOfOwner instantiates IndexedMap from TCollection
 228     (EntityOwner from SelectMgr,MapTransientHasher from TColStd);
 229
 230     class DataMapOfIntegerSensitive instantiates DataMap from TCollection
 231         (Integer, SensitiveEntity from SelectBasics,
 232          MapIntegerHasher from TColStd);
 233
 234     class SequenceOfSelector instantiates Sequence from TCollection
 235         (ViewerSelector);
 236
 237     class SequenceOfSelection instantiates Sequence from TCollection
 238         (Selection);
 239
 240
 241     class DataMapOfSelectionActivation instantiates DataMap from TCollection
 242     (Selection,Integer,MapTransientHasher from TColStd);
 243
 244     class DataMapOfObjectSelectors instantiates DataMap from TCollection
 245     (SelectableObject,SequenceOfSelector,MapTransientHasher from TColStd);
 246
 247     private class IndexedDataMapOfOwnerCriterion
 248         instantiates IndexedDataMap from TCollection
 249                             (EntityOwner        from SelectBasics,
 250                              SortCriterion      from SelectMgr,
 251                              MapTransientHasher from TColStd);
 252
 253     private class SortCriterion;
 254
 255     pointer SOPtr to SelectableObject from SelectMgr;
 256
 257     imported CompareResults;
 258
 259 end SelectMgr;