0026209: Visualization - provide a method to fit view to the specific bounding box
[occt.git] / src / SelectMgr / SelectMgr_SelectableObject.cdl
1 -- Created on: 1995-02-20
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 deferred class SelectableObject from SelectMgr  inherits PresentableObject from PrsMgr  
18
19          ---Purpose: A framework to supply the structure of the object to be
20         -- selected. At the first pick, this structure is created by
21         -- calling the appropriate algorithm and retaining this
22         -- framework for further picking.
23         -- This abstract framework is inherited in Application
24         -- Interactive Services (AIS), notably in AIS_InteractiveObject.
25         -- Consequently, 3D selection should be handled by the
26         -- relevant daughter classes and their member functions
27         -- in AIS. This is particularly true in the creation of new interactive objects.
28
29            
30 uses
31
32     Box                   from Bnd,
33     IndexedMapOfOwner     from SelectMgr,
34     SelectionManager      from SelectMgr,
35     Selection             from SelectMgr,
36     SequenceOfSelection   from SelectMgr,
37     TypeOfPresentation3d  from PrsMgr,
38     Drawer                from Prs3d,
39     Presentation          from Prs3d,
40     PresentationManager   from PrsMgr,
41     PresentationManager3d from PrsMgr,
42     SequenceOfOwner       from SelectMgr,
43     NameOfColor           from Quantity,
44     EntityOwner           from SelectMgr, 
45     TransModeFlags        from Graphic3d,
46     ZLayerId              from Graphic3d
47
48 raises 
49     NotImplemented from Standard
50
51 is
52
53
54     ---Category: deferred Methods 
55
56
57     Initialize(aTypeOfPresentation3d: TypeOfPresentation3d from PrsMgr = PrsMgr_TOP_AllView);
58
59     ComputeSelection(me:mutable; aSelection : Selection from SelectMgr;
60                                  aMode      : Integer) is deferred;
61         ---Purpose: Recovers and calculates any sensitive primitive,
62         -- aSelection, available in Shape mode, specified by
63         -- aMode. As a rule, these are sensitive faces.
64         -- This method is defined as virtual. This enables you to
65         -- implement it in the creation of a new class of AIS
66         -- Interactive Object. You need to do this and in so
67         -- doing, redefine this method, if you create a class
68         -- which enriches the list of signatures and types.
69
70
71     ---Category: 
72     
73     
74     RecomputePrimitives (me : mutable)
75       is static;
76         ---Purpose: Re-computes the sensitive primitives for all modes. IMPORTANT: Do not use
77     -- this method to update selection primitives except implementing custom selection manager!
78     -- This method does not take into account necessary BVH updates, but may invalidate the pointers
79     -- it refers to. TO UPDATE SELECTION properly from outside classes, use method UpdateSelection.
80     
81     RecomputePrimitives (me      : mutable;
82                          theMode : Integer from Standard)
83       is static;
84     ---Purpose: Re-computes the sensitive primitives which correspond to the <theMode>th selection mode.
85     -- IMPORTANT: Do not use this method to update selection primitives except implementing custom selection manager!
86     -- selection manager! This method does not take into account necessary BVH updates, but may invalidate
87     -- the pointers it refers to. TO UPDATE SELECTION properly from outside classes, use method UpdateSelection.
88
89
90     AddSelection(me:mutable; aSelection : Selection from SelectMgr;
91                              aMode      : Integer) 
92     is static;
93         ---Purpose: Adds the selection aSelection with the selection mode
94         -- index aMode to this framework.
95
96
97     ClearSelections(me:mutable; update: Boolean from Standard = Standard_False) is static;
98         ---Level: Public 
99         ---Purpose: Empties all the selections in the SelectableObject
100         --          <update> parameter defines whether all object's
101         -- selections should be flagged for further update or not.
102         -- This improved method can be used to recompute an
103         -- object's selection (without redisplaying the object
104         -- completely) when some selection mode is activated not for the first time.
105
106     Selection(me;aMode : Integer) 
107     returns any Selection from SelectMgr
108     is  static;
109         ---C++:  return const& 
110         ---Purpose: Returns the selection Selection having the selection mode aMode.
111
112     HasSelection(me; aMode: Integer) 
113     returns Boolean from Standard is static ;
114         --- Purpose: Returns true if a selection corresponding to the
115         -- selection mode aMode is present in this framework.   
116
117
118     
119     Init(me:mutable) is static;
120     ---Purpose: Begins the iteration scanning for sensitive primitives.
121     ---C++: inline
122
123
124     More(me) returns Boolean is static;
125     ---Purpose: Continues the iteration scanning for sensitive primitives.
126     ---C++: inline
127     
128
129
130     Next(me:mutable) is static;
131     ---Purpose: Continues the iteration scanning for sensitive primitives.
132     ---C++: inline
133     
134
135
136     CurrentSelection(me) returns any Selection from SelectMgr;
137     ---Purpose: Returns the current selection in this framework. 
138     ---C++: return const&
139     ---C++: inline
140     
141
142     ResetTransformation(me:mutable) is redefined static;
143     
144     UpdateTransformation(me:mutable) is redefined virtual;
145         ---Purpose: Recomputes the location of the selection aSelection.
146
147     UpdateTransformations(me:mutable;aSelection: Selection from SelectMgr) is virtual;
148     ---Level: Public
149     ---Purpose: Updates locations in all sensitive entities from <aSelection> 
150     --          and in corresponding entity owners.
151         
152     HilightSelected       ( me : mutable; PM : PresentationManager3d from PrsMgr; 
153                             Seq : SequenceOfOwner from SelectMgr ) raises NotImplemented from Standard is virtual;
154     ---Purpose: Method which draws selected owners ( for fast presentation draw )
155
156     ClearSelected         ( me : mutable ) is virtual;
157         ---Purpose: Method which clear all selected owners belonging
158         -- to this selectable object ( for fast presentation draw )
159
160     HilightOwnerWithColor ( me : mutable; thePM : PresentationManager3d from PrsMgr;
161                             theColor  : NameOfColor from Quantity;
162                             theOwner  : EntityOwner from SelectMgr ) raises NotImplemented from Standard is virtual;
163         ---Purpose: Method which hilight an owner belonging to
164         -- this selectable object  ( for fast presentation draw )
165
166     IsAutoHilight  ( me ) returns Boolean from Standard is virtual;
167         ---Purpose: If returns True, the old mechanism for highlighting
168         -- selected objects is used (HilightSelected Method may be empty).
169         -- If returns False, the HilightSelected method will be
170         -- fully responsible for highlighting selected entity
171         -- owners belonging to this selectable object.
172
173     SetAutoHilight ( me : mutable; newAutoHilight : Boolean from Standard ) is virtual;
174         ---Purpose: Set AutoHilight property to true or false 
175      
176    -- SetTransformPersistence(  me     :  mutable; 
177    --                         aFlag  :  TransModeFlags  from  Graphic3d ) is redefined; 
178    ---Level:    Public 
179    ---Purpose:  Sets  up  Transform  Persistence Mode  for  this  object 
180       ---Category: Graphic attributes management
181      
182     GetHilightPresentation(  me: mutable;
183                              TheMgr:  PresentationManager3d from PrsMgr )  returns Presentation from Prs3d  is  static; 
184     
185     GetSelectPresentation(   me: mutable;
186                              TheMgr:  PresentationManager3d from PrsMgr )  returns Presentation from Prs3d  is  static; 
187
188    SetZLayer ( me         : mutable;
189                theLayerId : ZLayerId from Graphic3d )
190      is redefined virtual;
191    ---Purpose: Set Z layer ID and update all presentations of the selectable object.
192    -- The layers mechanism allows drawing objects in higher layers in overlay of objects in lower layers.
193
194    UpdateSelection ( me      : mutable;
195                      theMode : Integer from Standard = -1)
196      is static;
197    ---Purpose: Sets update status FULL to selections of the object. Must be used as the only method of UpdateSelection
198    -- from outer classes to prevent BVH structures from being outdated.
199
200    BoundingBox (me : mutable;
201                 theBndBox : out Box from Bnd)
202     is deferred;
203     ---Purpose: Returns bounding box of selectable object
204     -- by storing its minimum and maximum 3d coordinates
205     -- to output parameters
206
207     SetAttributes(me:mutable; theDrawer: Drawer from Prs3d) is virtual;
208         ---Purpose: Initializes the drawing tool theDrawer.
209
210     Attributes(me) returns any Drawer from Prs3d;
211         ---C++: return const&
212         ---C++:  inline
213         ---Purpose: Returns the attributes settings.
214
215     UnsetAttributes(me:mutable) is virtual;
216     ---Purpose: Clears settings provided by the drawing tool theDrawer.
217
218     SetHilightAttributes(me:mutable; theDrawer: Drawer from Prs3d) is virtual;
219         ---Purpose: Initializes the hilight drawing tool theDrawer.
220
221     HilightAttributes(me) returns any Drawer from Prs3d;
222         ---C++: return const&
223         ---C++:  inline
224         ---Purpose: Returns the hilight attributes settings.
225
226     UnsetHilightAttributes(me:mutable) is virtual;
227     ---Purpose: Clears settings provided by the hilight drawing tool theDrawer.
228
229     InitDefaultHilightAttributes(myclass; theDrawer : Drawer from Prs3d);
230     ---Purpose: Initializes theDrawer by default hilight settings.
231
232     SetAssemblyOwner (me : mutable;
233                       theOwner : EntityOwner from SelectMgr;
234                       theMode  : Integer from Standard = -1);
235     ---Purpose: Sets common entity owner for assembly sensitive object entities
236
237     GetAssemblyOwner (me)
238       returns EntityOwner from SelectMgr
239       is static;
240     ---C++: return const&
241     ---Purpose: Returns common entity owner if the object is an assembly
242
243     BndBoxOfSelected (me : mutable;
244                       theOwners : out IndexedMapOfOwner from SelectMgr)
245       returns Box from Bnd;
246     ---Purpose: Returns a bounding box of sensitive entities with the owners given
247     --          if they are a part of activated selection
248
249 fields
250
251     myselections        : SequenceOfSelection is protected;
252     myDrawer            : Drawer from Prs3d is protected;
253     myHilightDrawer     : Drawer from Prs3d is protected;
254     myAssemblyOwner     : EntityOwner from SelectMgr is protected;
255     mycurrent           : Integer;
256     myAutoHilight       : Boolean from Standard;
257
258     mySelectionPrs      : Presentation from Prs3d;
259     myHilightPrs        : Presentation from Prs3d;
260     
261 friends
262     class SelectionManager from SelectMgr
263
264 end SelectableObject;