0028162: Draw Harness - eliminate usage of deprecated Local Context
[occt.git] / src / AIS / AIS_InteractiveObject.hxx
CommitLineData
42cf5bc1 1// Created on: 1996-12-11
2// Created by: Robert COUBLANC
3// Copyright (c) 1996-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#ifndef _AIS_InteractiveObject_HeaderFile
18#define _AIS_InteractiveObject_HeaderFile
19
42cf5bc1 20#include <Aspect_TypeOfFacingModel.hxx>
42cf5bc1 21#include <AIS_KindOfInteractive.hxx>
2ec85268 22#include <Graphic3d_NameOfMaterial.hxx>
23#include <PrsMgr_TypeOfPresentation3d.hxx>
24#include <SelectMgr_SelectableObject.hxx>
25#include <TColStd_ListOfInteger.hxx>
26#include <TColStd_ListOfTransient.hxx>
27#include <Quantity_Color.hxx>
28
42cf5bc1 29class AIS_InteractiveContext;
42cf5bc1 30class Graphic3d_MaterialAspect;
31class Prs3d_Presentation;
32class Prs3d_BasicAspect;
33class Bnd_Box;
34
42cf5bc1 35//! Defines a class of objects with display and selection services.
36//! Entities which are visualized and selected are
37//! Interactive Objects. You can make use of classes of
38//! standard Interactive Objects for which all necessary
39//! methods have already been programmed, or you can
40//! implement your own classes of Interactive Objects.
41//! Specific attributes of entities such as arrow aspect for
42//! dimensions must be loaded in a Drawer. This Drawer
43//! is then applied to the Interactive Object in view.
44//! There are four types of Interactive Object in AIS: the
45//! construction element or Datum, the Relation, which
46//! includes both dimensions and constraints, the Object,
47//! and finally, when the object is of an unknown type, the None type.
48//! Inside these categories, a signature, or index,
49//! provides the possibility of additional characterization.
50//! By default, the Interactive Object has a None type
51//! and a signature of 0. If you want to give a particular
52//! type and signature to your interactive object, you must
53//! redefine the methods, Signature and Type.
54//! Warning
55//! In the case of attribute methods, methods for
56//! standard attributes are virtual. They must be
57//! redefined by the inheriting classes. Setcolor for a
58//! point and Setcolor for a plane, for example, do not
59//! affect the same attributes in the Drawer.
60class AIS_InteractiveObject : public SelectMgr_SelectableObject
61{
2ec85268 62 friend class AIS_InteractiveContext;
63 DEFINE_STANDARD_RTTIEXT(AIS_InteractiveObject, SelectMgr_SelectableObject)
42cf5bc1 64public:
65
42cf5bc1 66 //! Returns the kind of Interactive Object:
67 //! - None
68 //! - Datum
69 //! - Relation
70 //! - Object
71 //! By default, the interactive object has a None type.
72 //! Because specific shapes entail different behavior
73 //! according to their sub-shapes, you may need to
74 //! create a Local Context. This will allow you to
75 //! specify the additional characteristics which you
76 //! need to handle these shapes.
77 Standard_EXPORT virtual AIS_KindOfInteractive Type() const;
78
79 //! Specifies additional characteristics of Interactive
80 //! Objects. A signature is, in fact, an index with integer
81 //! values assigned different properties.
82 //! This method is frequently used in conjuction with
83 //! Type to give a particular type and signature to an
84 //! Interactive Object. By default, the Interactive Object
85 //! has a None type and a signature of 0. Among the
86 //! datums, this signature is attributed to the shape
87 //! The remaining datums have the following default signatures:
88 //! - Point signature 1
89 //! - Axis signature 2
90 //! - Trihedron signature 3
91 //! - PlaneTrihedron signature 4
92 //! - Line signature 5
93 //! - Circle signature 6
94 //! - Plane signature 7.
95 Standard_EXPORT virtual Standard_Integer Signature() const;
96
97 //! Informs the graphic context that the interactive Object
98 //! may be decomposed into sub-shapes for dynamic selection.
99 //! The most used Interactive Object is AIS_Shape.
100 //! Activation methods for standard selection modes are
101 //! proposed in the Interactive Context. These include
102 //! selection by vertex or by edges. For datums with the
103 //! same behavior as AIS_Shape, such as vetices and
104 //! edges, we must redefine the virtual method so that
105 //! AcceptShapeDecomposition returns false.
106 //! Rule for selection :
107 //! Mode 0 : Selection of the interactive Object itself
108 //! Mode 1 : Selection of vertices
109 //! Mode 2 : Selection Of Edges
110 //! Mode 3 : Selection Of Wires
111 //! Mode 4 : Selection Of Faces ...
2ec85268 112 virtual Standard_Boolean AcceptShapeDecomposition() const { return Standard_False; }
113
42cf5bc1 114 //! change the current facing model apply on polygons for
115 //! SetColor(), SetTransparency(), SetMaterial() methods
116 //! default facing model is Aspect_TOFM_TWO_SIDE. This mean that attributes is
117 //! applying both on the front and back face.
118 Standard_EXPORT void SetCurrentFacingModel (const Aspect_TypeOfFacingModel aModel = Aspect_TOFM_BOTH_SIDE);
119
120 //! Returns the current facing model which is in effect.
121 Standard_EXPORT Aspect_TypeOfFacingModel CurrentFacingModel() const;
122
123 Standard_EXPORT virtual void SetColor (const Quantity_Color& aColor);
124
125 //! only the interactive obj knowns which Drawer attribute
126 //! is affected by the color (ex: for a wire, it's the
127 //! wireaspect field of the drawer, but for a vertex, only
128 //! the point aspect field is affected by the color)
129 //! WARNING : Do not forget to set the corresponding fields
130 //! here (hasOwnColor and myOwnColor)
131 Standard_EXPORT virtual void SetColor (const Quantity_NameOfColor aColor);
132
133 //! Removes color settings. Only the Interactive Object
134 //! knows which Drawer attribute is affected by the color
135 //! setting. For a wire, for example, wire aspect is the
136 //! attribute affected. For a vertex, however, only point
137 //! aspect is affected by the color setting.
138 Standard_EXPORT virtual void UnsetColor();
139
140 //! Allows you to provide the setting aValue for width.
141 //! Only the Interactive Object knows which Drawer
142 //! attribute is affected by the width setting.
143 Standard_EXPORT virtual void SetWidth (const Standard_Real aValue);
144
145 Standard_EXPORT virtual void UnsetWidth();
146
147 //! Returns true if the class of objects accepts the display mode aMode.
148 //! The interactive context can have a default mode of
149 //! representation for the set of Interactive Objects. This
150 //! mode may not be accepted by a given class of
151 //! objects. Consequently, this virtual method allowing us
152 //! to get information about the class in question must be implemented.
153 Standard_EXPORT virtual Standard_Boolean AcceptDisplayMode (const Standard_Integer aMode) const;
154
155 //! Returns the default display mode. This method is to
156 //! be implemented when the main mode is not mode 0.
157 Standard_EXPORT virtual Standard_Integer DefaultDisplayMode() const;
158
159 //! Updates the active presentation; if <AllModes> = Standard_True
160 //! all the presentations inside are recomputed.
161 //! IMPORTANT: It is preferable to call Redisplay method of
162 //! corresponding AIS_InteractiveContext instance for cases when it
163 //! is accessible. This method just redirects call to myCTXPtr,
164 //! so this class field must be up to date for proper result.
165 Standard_EXPORT void Redisplay (const Standard_Boolean AllModes = Standard_False);
166
167 //! Sets the infinite state flag aFlage.
168 //! if <aFlag> = True , the interactiveObject is
169 //! considered as infinite, i.e. its graphic presentations
170 //! are not taken in account for View FitAll...
171 Standard_EXPORT void SetInfiniteState (const Standard_Boolean aFlag = Standard_True);
42cf5bc1 172
173 //! Returns true if the interactive object is infinite. In this
174 //! case, its graphic presentations are not taken into
175 //! account in the fit-all view.
2ec85268 176 Standard_Boolean IsInfinite() const { return myInfiniteState; }
177
178 //! Indicates whether the Interactive Object has a pointer to an interactive context.
179 Standard_Boolean HasInteractiveContext() const { return myCTXPtr != NULL; }
180
42cf5bc1 181 //! Returns the context pointer to the interactive context.
182 Standard_EXPORT Handle(AIS_InteractiveContext) GetContext() const;
183
184 //! Sets the interactive context aCtx and provides a link
185 //! to the default drawing tool or "Drawer" if there is none.
186 Standard_EXPORT virtual void SetContext (const Handle(AIS_InteractiveContext)& aCtx);
187
188 //! Returns true if the object has an owner attributed to it.
189 //! The owner can be a shape for a set of sub-shapes or
190 //! a sub-shape for sub-shapes which it is composed of,
191 //! and takes the form of a transient.
192 Standard_EXPORT Standard_Boolean HasOwner() const;
193
194 //! Returns the owner of the Interactive Object.
195 //! The owner can be a shape for a set of sub-shapes or
196 //! a sub-shape for sub-shapes which it is composed of,
197 //! and takes the form of a transient.
198 //! There are two types of owners:
199 //! - Direct owners, decomposition shapes such as
200 //! edges, wires, and faces.
201 //! - Users, presentable objects connecting to sensitive
202 //! primitives, or a shape which has been decomposed.
2ec85268 203 const Handle(Standard_Transient)& GetOwner() const { return myOwner; }
204
205 //! Allows you to attribute the owner theApplicativeEntity to
42cf5bc1 206 //! an Interactive Object. This can be a shape for a set of
207 //! sub-shapes or a sub-shape for sub-shapes which it
208 //! is composed of. The owner takes the form of a transient.
2ec85268 209 void SetOwner (const Handle(Standard_Transient)& theApplicativeEntity) { myOwner = theApplicativeEntity; }
210
42cf5bc1 211 //! Each Interactive Object has methods which allow us
212 //! to attribute an Owner to it in the form of a Transient.
213 //! This method removes the owner from the graphic entity.
214 Standard_EXPORT void ClearOwner();
42cf5bc1 215
216 //! Returns true if the Interactive Object has a display
217 //! mode setting. Otherwise, it is displayed in Neutral Point.
2ec85268 218 Standard_Boolean HasDisplayMode() const { return myDisplayMode != -1; }
219
42cf5bc1 220 //! Sets the display mode aMode for the interactive object.
221 //! An object can have its own temporary display mode,
222 //! which is different from that proposed by the interactive context.
223 //! The range of possibilities currently proposed is the following:
224 //! - AIS_WireFrame
225 //! - AIS_Shaded
226 //! This range can, however, be extended through the creation of new display modes.
227 Standard_EXPORT void SetDisplayMode (const Standard_Integer aMode);
2ec85268 228
42cf5bc1 229 //! Removes display mode settings from the interactive object.
2ec85268 230 void UnsetDisplayMode() { myDisplayMode = -1; }
231
42cf5bc1 232 //! Returns the display mode setting of the Interactive Object.
233 //! The range of possibilities is the following:
234 //! - AIS_WireFrame
235 //! - AIS_Shaded
236 //! This range can, however, be extended through the
237 //! creation of new display modes.
2ec85268 238 Standard_Integer DisplayMode() const { return myDisplayMode; }
c3282ec1 239
42cf5bc1 240 //! Returns the selection priority setting. -1 indicates that there is none.
241 //! You can modify the selection priority of an owner to
242 //! make one entity more selectionable than another one.
243 //! The default selection priority for an owner is 5, for
244 //! example. To increase selection priority, choose a
245 //! setting between 5 and 10. An entity with priority 7 will
246 //! take priority over one with a setting of 6 if both
247 //! objects are selected at the same time.
248 //! You could give vertices priority 8, edges priority 7,
249 //! faces priority 6, and shapes priority 5. If a vertex, an
250 //! edge and a face are simultaneously detected during
251 //! selection, only the vertex will then be highlighted.
252 //! For trihedra, for example, the default priorities are the following four:
253 //! - priority 1 - a trihedron
254 //! - priority 5 - its origin
255 //! - priority 3 - its axes
256 //! - priority 2 - its planes
2ec85268 257 Standard_Integer SelectionPriority() const { return mySelPriority; }
258
259 //! Allows you to provide a setting thePriority for selection priority.
42cf5bc1 260 //! You can modify selection priority of an owner to make
261 //! one entity more selectionable than another one. The
262 //! default selection priority for an owner is 5, for
263 //! example. To increase selection priority, choose a
264 //! setting between 5 and 10. An entity with priority 7 will
265 //! take priority over one with a setting of 6.
2ec85268 266 void SetSelectionPriority (const Standard_Integer thePriority) { mySelPriority = thePriority; }
267
42cf5bc1 268 //! Removes the setting for selection priority. SelectionPriority then returns -1.
2ec85268 269 void UnsetSelectionPriority() { mySelPriority = -1; }
270
42cf5bc1 271 //! Returns true if there is a setting for selection priority.
272 //! You can modify selection priority of an owner to make
273 //! one entity more selectionable than another one. The
274 //! default selection priority for an owner is 5, for
275 //! example. To increase selection priority, choose a
276 //! setting between 5 and 10. An entity with priority 7 will
277 //! take priority over one with a setting of 6.
2ec85268 278 Standard_Boolean HasSelectionPriority() const { return mySelPriority != -1; }
279
42cf5bc1 280 //! Returns true if the Interactive Object is in highlight mode.
2ec85268 281 Standard_Boolean HasHilightMode() const { return myHilightMode != -1; }
282
42cf5bc1 283 //! Returns the setting for highlight mode.
284 //! At dynamic detection, the presentation echoed by the
285 //! Interactive Context, is by default the presentation
286 //! already on the screen. You can specify a Highlight
287 //! presentation mode which is valid no matter what the
288 //! active representation of the object. It makes no
289 //! difference whether this choice is temporary or
290 //! definitive. To do this, we use the following functions:
291 //! - SetHilightMode
292 //! - UnSetHilightMode
293 //! In the case of a shape, whether it is visualized in
294 //! wireframe presentation or with shading, we want to
295 //! systematically highlight the wireframe presentation.
296 //! Consequently, we set the highlight mode to 0.
2ec85268 297 Standard_Integer HilightMode() const { return myHilightMode; }
298
299 //! Sets the highlight mode theMode for the interactive object.
42cf5bc1 300 //! If, for example, you want to systematically highlight
301 //! the wireframe presentation of a shape - whether
302 //! visualized in wireframe presentation or with shading -
303 //! you set the highlight mode to 0.
2ec85268 304 void SetHilightMode (const Standard_Integer theMode) { myHilightMode = theMode; }
305
42cf5bc1 306 //! Allows the user to take a given Prs for hilight
307 //! ex : for a shape which would be displayed in shading mode
308 //! the hilight Prs is the wireframe mode.
309 //! if No specific hilight mode is defined, the displayed Prs
310 //! will be the hilighted one.
2ec85268 311 void UnsetHilightMode() { myHilightMode = -1; }
312
42cf5bc1 313 //! Returns true if the Interactive Object has color.
2ec85268 314 Standard_Boolean HasColor() const { return hasOwnColor; }
315
42cf5bc1 316 //! Returns the color setting of the Interactive Object.
2ec85268 317 virtual Quantity_NameOfColor Color() const { return myOwnColor.Name(); }
318
319 virtual void Color (Quantity_Color& theColor) const { theColor = myOwnColor; }
320
42cf5bc1 321 //! Returns true if the Interactive Object has width.
2ec85268 322 Standard_Boolean HasWidth() const { return myOwnWidth != 0.0; }
323
42cf5bc1 324 //! Returns the width setting of the Interactive Object.
2ec85268 325 Standard_Real Width() const { return myOwnWidth; }
326
42cf5bc1 327 //! Returns true if the Interactive Object has a setting for material.
2ec85268 328 Standard_Boolean HasMaterial() const { return hasOwnMaterial; }
329
42cf5bc1 330 //! Returns the current material setting.
331 //! This will be on of the following materials:
332 //! - Brass
333 //! - Bronze
334 //! - Gold
335 //! - Pewter
336 //! - Silver
337 //! - Stone.
2ec85268 338 virtual Graphic3d_NameOfMaterial Material() const { return myOwnMaterial; }
339
42cf5bc1 340 //! Sets the name aName for material defining this
341 //! display attribute for the interactive object.
342 //! Material aspect determines shading aspect, color and
343 //! transparency of visible entities.
344 Standard_EXPORT virtual void SetMaterial (const Graphic3d_NameOfMaterial aName);
345
346 //! Sets the material aMat defining this display attribute
347 //! for the interactive object.
348 //! Material aspect determines shading aspect, color and
349 //! transparency of visible entities.
350 Standard_EXPORT virtual void SetMaterial (const Graphic3d_MaterialAspect& aName);
351
352 //! Removes the setting for material.
353 Standard_EXPORT virtual void UnsetMaterial();
354
355 //! Attributes a setting aValue for transparency.
356 //! The transparency value should be between 0.0 and 1.0.
357 //! At 0.0 an object will be totally opaque, and at 1.0, fully transparent.
358 //! Warning At a value of 1.0, there may be nothing visible.
359 Standard_EXPORT virtual void SetTransparency (const Standard_Real aValue = 0.6);
360
361 //! Returns true if there is a transparency setting.
2ec85268 362 Standard_Boolean IsTransparent() const { return myTransparency > 0.005; }
363
42cf5bc1 364 //! Returns the transparency setting.
365 //! This will be between 0.0 and 1.0.
366 //! At 0.0 an object will be totally opaque, and at 1.0, fully transparent.
367 Standard_EXPORT virtual Standard_Real Transparency() const;
368
369 //! Removes the transparency setting. The object is opaque by default.
370 Standard_EXPORT virtual void UnsetTransparency();
371
372 //! Clears settings provided by the drawing tool aDrawer.
373 Standard_EXPORT virtual void UnsetAttributes() Standard_OVERRIDE;
2ec85268 374
42cf5bc1 375 //! Returns TRUE when this object has a presentation
376 //! in the current DisplayMode()
377 Standard_EXPORT Standard_Boolean HasPresentation() const;
378
379 //! Returns the current presentation of this object
380 //! according to the current DisplayMode()
381 Standard_EXPORT Handle(Prs3d_Presentation) Presentation() const;
2831708b 382
42cf5bc1 383 //! Sets the graphic basic aspect to the current presentation.
2831708b 384 Standard_EXPORT void SetAspect (const Handle(Prs3d_BasicAspect)& anAspect);
42cf5bc1 385
386 //! Sets up polygon offsets for this object.
387 //! It modifies all existing presentations of <anObj> (if any),
388 //! so it is reasonable to call this method after <anObj> has been displayed.
389 //! Otherwise, Compute() method should pass Graphic3d_AspectFillArea3d
390 //! aspect from <myDrawer> to Graphic3d_Group to make polygon offsets work.
391 //!
392 //! <aMode> parameter can contain various combinations of
393 //! Aspect_PolygonOffsetMode enumeration elements (Aspect_POM_None means
394 //! that polygon offsets are not changed).
395 //! If <aMode> is different from Aspect_POM_Off and Aspect_POM_None, then <aFactor> and <aUnits>
396 //! arguments are used by graphic renderer to calculate a depth offset value:
397 //!
398 //! offset = <aFactor> * m + <aUnits> * r, where
399 //! m - maximum depth slope for the polygon currently being displayed,
400 //! r - minimum window coordinates depth resolution (implementation-specific).
401 //!
402 //! Deafult settings for OCC 3D viewer: mode = Aspect_POM_Fill, factor = 1., units = 0.
403 //!
404 //! Negative offset values move polygons closer to the viewport,
405 //! while positive values shift polygons away.
406 //! Consult OpenGL reference for details (glPolygonOffset function description).
407 //!
408 //! NOTE: This method has a side effect - it creates own shading aspect
409 //! if not yet created, so it is better to set up object material,
410 //! color, etc. first.
411 Standard_EXPORT virtual void SetPolygonOffsets (const Standard_Integer aMode, const Standard_ShortReal aFactor = 1.0, const Standard_ShortReal aUnits = 0.0);
412
413 //! Returns Standard_True if <myDrawer> has non-null shading aspect
414 Standard_EXPORT virtual Standard_Boolean HasPolygonOffsets() const;
415
416 //! Retrieves current polygon offsets settings from <myDrawer>.
417 Standard_EXPORT virtual void PolygonOffsets (Standard_Integer& aMode, Standard_ShortReal& aFactor, Standard_ShortReal& aUnits) const;
418
419 //! Returns bounding box of object correspondingly to its current display mode.
420 Standard_EXPORT virtual void BoundingBox (Bnd_Box& theBndBox) Standard_OVERRIDE;
421
5ad8c033 422 //! Enables or disables on-triangulation build of isolines according to the flag given.
423 Standard_EXPORT void SetIsoOnTriangulation (const Standard_Boolean theIsEnabled);
42cf5bc1 424
fb66bb28 425 //! Synchronize presentation aspects after their modification.
426 //!
427 //! This method should be called after modifying primitive aspect properties (material, texture, shader)
428 //! so that modifications will take effect on already computed presentation groups (thus avoiding re-displaying the object).
429 Standard_EXPORT void SynchronizeAspects();
430
2ec85268 431private:
42cf5bc1 432
2ec85268 433 Standard_EXPORT virtual Standard_Boolean RecomputeEveryPrs() const;
42cf5bc1 434
2ec85268 435 Standard_EXPORT void MustRecomputePrs (const Standard_Integer aMode) const;
436
437 Standard_EXPORT const TColStd_ListOfInteger& ListOfRecomputeModes() const;
438
439 Standard_EXPORT void SetRecomputeOk();
42cf5bc1 440
441protected:
442
443
444 //! The TypeOfPresention3d means that the interactive object
c3282ec1 445 //! may have a presentation dependant of the view of Display.
42cf5bc1 446 Standard_EXPORT AIS_InteractiveObject(const PrsMgr_TypeOfPresentation3d aTypeOfPresentation3d = PrsMgr_TOP_AllView);
447
448 Standard_Real myTransparency;
449 Quantity_Color myOwnColor;
450 Graphic3d_NameOfMaterial myOwnMaterial;
451 Standard_Integer myHilightMode;
452 Standard_Real myOwnWidth;
453 Standard_Boolean myInfiniteState;
454 Standard_Boolean hasOwnColor;
455 Standard_Boolean hasOwnMaterial;
456 Aspect_TypeOfFacingModel myCurrentFacingModel;
457 Standard_Boolean myRecomputeEveryPrs;
458 TColStd_ListOfInteger myToRecomputeModes;
459
42cf5bc1 460private:
461
2ec85268 462 AIS_InteractiveContext* myCTXPtr;
42cf5bc1 463 Handle(Standard_Transient) myOwner;
42cf5bc1 464 Standard_Integer mySelPriority;
465 Standard_Integer myDisplayMode;
42cf5bc1 466
467};
468
2ec85268 469DEFINE_STANDARD_HANDLE(AIS_InteractiveObject, SelectMgr_SelectableObject)
42cf5bc1 470
471#endif // _AIS_InteractiveObject_HeaderFile