All Frameworks  Class Hierarchy  This Framework  Next  Indexes

CATIAApplicationFrame Interface CATI3DCompass

System.IUnknown
  |
  +---System.IDispatch
    |
    +---System.CATBaseUnknown
      |
      +---CATI3DCompass
 

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.


interface CATI3DCompass

Interface to access and manipulate the compass through software coding.

Role: The compass object implements the CATI3DCompass interface. To retrieve a pointer to the compass object that implements CATI3DCompass use CATFrmEditor.GetCompass method.


Method Index


o GetBeginDragPreviewEvent(CATCallbackEvent*)
Retrieves the event emitted when compass starts being moved to another location.
o GetBeginMoveEvent(CATCallbackEvent*)
Retrieves the event emitted when user start dragging the compass.
o GetCurrentTransformation(CATMathTransformation**)
Retrieves the current compass transformation.
o GetDragPreviewEvent(CATCallbackEvent*)
Retrieves the event emitted when compass is being moved to another location.
o GetDragPreviewPosition(CATPathElement**,CATMathAxis**)
Retreive compass preview informations.
o GetEndDragPreviewEvent(CATCallbackEvent*)
Retrieves the event emitted when compass ends being moved to another location.
o GetEndMoveEvent(CATCallbackEvent*)
Retrieves the event emitted when user finish dragging the compass.
o GetEventPublisher(CATBaseUnknown**)
Retreives the compass event publisher.
o GetMoveEvent(CATCallbackEvent*)
Retrieves the event emitted when user is dragging the compass.
o GetPosition(CATMathAxis*)
Retreive the position and orientation of the compass.
o GetPrivilegedPlane(int*)
Retreives the privileged plane definition.
o GetPrivilegedPlaneModifiedEvent(CATCallbackEvent*)
Retreives the privileged plane modification event.
o GetState(CATCompassState*)
Retrieve the state of the compass.
o GetVisibility(int*)
Retrieve the compass visibility.
o Hide()
Hides the compass from the screen.
o SetPosition(CATMathAxis*)
Sets the position and orientation of the compass.
o SetPrivilegedPlane(int*)
Sets the privileged plane definition.
o SetState(CATCompassState*)
Sets the state of the compass.
o Show()
Shows the compass on the screen.

Methods


o GetBeginDragPreviewEvent
public virtual HRESULT GetBeginDragPreviewEvent(CATCallbackEvent* oBeginDragPreviewEvent) = 0
Retrieves the event emitted when compass starts being moved to another location.
Role: This event is emitted at the first mouse interaction when user is moving the compass to another location by dragging its center. This event is not emitted when select command is running.
Parameters:
oBeginDragPreviewEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetBeginMoveEvent
public virtual HRESULT GetBeginMoveEvent(CATCallbackEvent* oBeginMoveEvent) = 0
Retrieves the event emitted when user start dragging the compass.
Role: This event is emitted at the first mouse interaction after clicking one of the compass handle. Subscribe to this event to react on compass start of manipulation by the user. This event is not emitted when select command is running.
Parameters:
oBeginMoveEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetCurrentTransformation
public virtual HRESULT GetCurrentTransformation(CATMathTransformation** oTransformation) = 0
Retrieves the current compass transformation.
Role: This method should be called in the callback method of the BeginMove, Move or EndMove event to know the current transformation that is being applied to the compass. The current transformation is computed between the current position (when Move event is sent) and the initial position (when BeginMove event is sent). The returned value can be modified to override the standard behaviour of the compass, thus permitting to take into account an applicative displacement constraint.
Parameters:
oTransformation
The current compass transformation.
Returns:
S_OK if operation is successful
o GetDragPreviewEvent
public virtual HRESULT GetDragPreviewEvent(CATCallbackEvent* oDragPreviewEvent) = 0
Retrieves the event emitted when compass is being moved to another location.
Role: This event is emitted at the second and every following mouse interaction when user is moving the compass to another location by dragging its center. This event is not emitted when select command is running.
Parameters:
oDragPreviewEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetDragPreviewPosition
public virtual HRESULT GetDragPreviewPosition(CATPathElement** oElementUnder,
CATMathAxis** oPreviewPosition) = 0
Retreive compass preview informations.
Role: This method should be called in the callback method of the BeginDragPreview, DragPreview and EndDragPreview events to retrieve the current preview position of the compass and, if any, the current model object under the mouse. The preview position of the compass can be modified thus allowing application to implement such behaviour as compass snapping to the object that is under the mouse.
Parameters:
oElementUnder
A pointer to a
CATPathElement representing the model objects under the mouse
oPreviewPosition
A pointer to the current preview position
Returns:
S_OK if operation is successful
o GetEndDragPreviewEvent
public virtual HRESULT GetEndDragPreviewEvent(CATCallbackEvent* oEndDragPreviewEvent) = 0
Retrieves the event emitted when compass ends being moved to another location.
Role: This event is emitted when the mouse button is released after dragging the compass to another location by using its center.
Parameters:
oEndDragPreviewEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetEndMoveEvent
public virtual HRESULT GetEndMoveEvent(CATCallbackEvent* oEndMoveEvent) = 0
Retrieves the event emitted when user finish dragging the compass.
Role: This event is emitted when the mouse button is released after dragging one of the compass handle. Subscribe to this event to react compass end of manipulation by the user. This event is not emitted when select command is running.
Parameters:
oEndMoveEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetEventPublisher
public virtual HRESULT GetEventPublisher(CATBaseUnknown** oCompassEventPublisher) = 0
Retreives the compass event publisher.
Parameters:
oCompassEventPublisher
The event publisher used by the compass to publish events. For usage of event publisher see
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetMoveEvent
public virtual HRESULT GetMoveEvent(CATCallbackEvent* oMoveEvent) = 0
Retrieves the event emitted when user is dragging the compass.
Role: This event is emitted at the second and every following mouse interaction when user is dragging one of the compass handle. Subscribe to this event to react on compass direct manipulation by the user. This event is not emitted when select command is running.
Parameters:
oMoveEvent
A pointer to the published event. See
CATEventSubscriber.AddCallback
Returns:
S_OK if operation is successful
o GetPosition
public virtual HRESULT GetPosition(CATMathAxis* oAxis) = 0
Retreive the position and orientation of the compass.
Parameters:
oAxis
The returned compass position and orientation in the absolute coordinates systems.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o GetPrivilegedPlane
public virtual HRESULT GetPrivilegedPlane(int* oPrivilegedPlane) = 0
Retreives the privileged plane definition.
Parameters:
oPrivilegedPlane
The oPrivileged plane value is equal to either
1
if the privileged plane is defined as (X,Y) or (U,V)
2
if the privileged plane is defined as (Y,Z) or (V,W)
3
if the privileged plane is defined as (Z,X) or (W,U)

To get the privileged plane coordinates use the
CATI3DCompass.GetPosition method.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o GetPrivilegedPlaneModifiedEvent
public virtual HRESULT GetPrivilegedPlaneModifiedEvent(CATCallbackEvent* oPrivilegedPlaneModifiedEvent) = 0
Retreives the privileged plane modification event.
Parameters:
oPrivilegedPlaneModifiedEvent
The oProvilegedPlaneModifiedEvent is emitted each time the privileged plane definition changes. This might happen through code or user interaction.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o GetState
public virtual HRESULT GetState(CATCompassState* oCompassState) = 0
Retrieve the state of the compass.
Parameters:
oCompassState
The compass state can either be:
CatCompass
if the compass is docked on top right screen corner and manipulates viewpoint.
CatGlider
if the compass is located in the 3D scene and manipulates objects.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o GetVisibility
public virtual HRESULT GetVisibility(int* oVisible) = 0
Retrieve the compass visibility.
Parameters:
oVisible
Paremeter is set to TRUE if compass is visible, FALSE otherwise
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o Hide
public virtual HRESULT Hide()= 0
Hides the compass from the screen.
Returns:
S_OK if operation is successful
S_FALSE if compass was already hidden
E_FAIL if compass representation is destroyed or being destroyed
o SetPosition
public virtual HRESULT SetPosition( const CATMathAxis* iAxis) = 0
Sets the position and orientation of the compass.
Parameters:
iAxis
New position and orientation of the compass in the absolute coordinates system. If compass is docked in the top right corner of the screen (i.e. GetState returns CatCompass), only the orientation is taken into acount and the
CATMathAxis origin is ignored.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o SetPrivilegedPlane
public virtual HRESULT SetPrivilegedPlane(int* iPrivilegedPlane) = 0
Sets the privileged plane definition.
Parameters:
iPrivilegedPlane
The privileged plane to set.
Legal values It can be set to either :
1
to define the privileged plane as (X,Y) or (U,V)
2
to define the privileged plane as (Y,Z) or (V,W)
3
to define the privileged plane as (Z,X) or (W,U)

To set the privileged plane coordinates use the
CATI3DCompass.SetPosition method.
Returns:
S_OK if operation is successful
E_INVALIDARG if argument is NULL or pointing to an illegal value
E_FAIL if compass representation is destroyed or being destroyed
o SetState
public virtual HRESULT SetState( const CATCompassState* iCompassState) = 0
Sets the state of the compass.
Parameters:
iCompassState
The state to set.
Legal values It can be set to either :
CatCompass
to dock the compass on top right screen corner.
CatGlider
to position the compass in the 3D scene. Compass is positioned at the origin of the absolute axis system, while its orientation is kept.
Returns:
S_OK if operation is successful
E_FAIL if compass representation is destroyed or being destroyed
o Show
public virtual HRESULT Show()= 0
Shows the compass on the screen.
Returns:
S_OK if operation is successful
S_FALSE if compass was already visible
E_FAIL if compass representation is destroyed or being destroyed

This object is included in the file: CATI3DCompass.h
If needed, your Imakefile.mk should include the module: CATIAApplicationFrame

Copyright © 2003, Dassault Systèmes. All rights reserved.