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