954487e45789a2e87c44295b83c2b3eb103a692d
[occt.git] / 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
196     enumeration TypeOfBVHUpdate is TBU_Add,
197                                    TBU_Remove,
198                                    TBU_Renew,
199                                    TBU_Invalidate,
200                                    TBU_None;
201        ---Purpose:       Keeps track for BVH update state for each SelectMgr_Selection entity in a following way:
202        -- - Add        : 2nd level BVH does not contain any of the selection's sensitive entities and they must be
203        --                added;
204        -- - Remove     : all sensitive entities of the selection must be removed from 2nd level BVH;
205        -- - Renew      : 2nd level BVH already contains sensitives of the selection, but the its complete update
206        --                and removal is required. Therefore, sensitives of the selection with this type of update
207        --                must be removed from 2nd level BVH and added after recomputation.
208        -- - Invalidate : the 2nd level BVH needs to be rebuilt;
209        -- - None       : entities of the selection are up to date.
210
211     deferred class Filter;
212
213     deferred class CompositionFilter;     
214
215     class AndFilter;
216
217     class OrFilter;
218
219
220
221
222     class EntityOwner;
223
224     deferred class SelectableObject;
225
226     class  SelectionManager;
227
228     ---Category: instantiations of classes from TCollection...
229
230     class SequenceOfFilter instantiates Sequence from TCollection
231     (Filter from SelectMgr);
232
233     class ListOfFilter instantiates List from TCollection
234     (Filter from SelectMgr);
235
236     class SequenceOfOwner instantiates Sequence from TCollection
237     (EntityOwner from SelectMgr);
238
239     class IndexedMapOfOwner instantiates IndexedMap from TCollection
240     (EntityOwner from SelectMgr,MapTransientHasher from TColStd);
241
242     class SequenceOfSelector instantiates Sequence from TCollection
243         (ViewerSelector from SelectMgr);
244
245     class DataMapOfObjectSelectors instantiates DataMap from TCollection
246     (SelectableObject from SelectMgr,SequenceOfSelector,MapTransientHasher from TColStd);
247
248     private class IndexedDataMapOfOwnerCriterion
249         instantiates IndexedDataMap from TCollection
250                             (EntityOwner        from SelectBasics,
251                              SortCriterion      from SelectMgr,
252                              MapTransientHasher from TColStd);
253
254     private class SortCriterion;
255
256     pointer SOPtr to SelectableObject from SelectMgr;
257
258     imported CompareResults;
259
260     imported SelectableObjectSet;
261     imported FrustumBuilder;
262     imported BaseFrustum;
263     imported Frustum;
264     imported RectangularFrustum;
265     imported TriangularFrustum;
266     imported TriangularFrustumSet;
267     imported SelectingVolumeManager;
268     imported transient class Selection;
269     imported SequenceOfSelection;
270     imported SensitiveEntity;
271     imported SensitiveEntitySet;
272     imported transient class ViewerSelector;
273
274 end SelectMgr;