Public Member Functions
ToolContext Class Reference

Detailed Description

ToolContext is used for accessing/handling tool data. Instances of this object can pass information to the C++ API callbacks that implement the custom tool plug-in item.

A custom tool must be registered at startup time using PluginRegistrar::RegisterTool. A scripting command with the same name as the custom tool is also registered. Calling this command will invoke the tool. A custom shortcut key may also be assigned to the tool using the keyboard mapping dialog.

Tool Callbacks
All tool callbacks are optional so tools only need to implement the callbacks they are interested in receiving.
Callback names must be formatted as
 {plugin_item_name}_{callback_name} 
where plugin_item_name is the string passed to PluginRegistrar::RegisterTool to identify the tool plug-in item and callback_name is the name of the callback.
Each callback receives a reference to the ToolContext which is used to retrieve callback specific information and change the tool state.
Note: Callbacks that require a return value will be documented in the callback description. Return values for all other callbacks are ignored.
Setup
    CStatus MyTool_Setup( ToolContext &in_context )
This callback is called when the tool is created and can be used to setup initial tool state.
Cleanup
    CStatus MyTool_Cleanup( ToolContext &in_context )
This callback is called when the tool is destroyed and can be used to free up memory or release drawing resources like textures.
Activate
    CStatus MyTool_Activate( ToolContext &in_context )
This callback is called when the tool takes control of the view. Tools can be temporarily deactivated when another tool is invoked by holding down a (supra) hotkey. The original tool will be reactivated when the hotkey is released.
Deactivate
    CStatus MyTool_Deactivate( ToolContext &in_context )
This callback is called when another tool takes control of the view. Tools can be temporarily deactivated when another tool is invoked by holding down a (supra) hotkey. The original tool will be reactivated when the hotkey is released.
Draw
    CStatus MyTool_Draw( ToolContext &in_context )
This callback is called when the view is drawn and the tool can perform its own drawing in this callback. The default drawing coordinates are world-space but tools can draw in 2D screen-space by calling ToolContext::BeginViewDraw and ToolContext::EndViewDraw.
The callback will be called once for each visible view that needs to be redrawn. If the tool only wants to draw in a single view or during interaction then ToolContext::IsActiveView and ToolContext::IsInteracting can be used to detect these conditions. A tool can also be asked to draw when the user is interacting with a camera tool in supra mode and ToolContext::IsNavigating will return true when this happens.
MouseDown
    CStatus MyTool_MouseDown( ToolContext &in_context )
This callback is called when a mouse button is pressed on a 3D view.
Mouse position and button/modifier key state can be accessed through the tool context. The tool can then convert the mouse coordinates to 3D using the ToolContext coordinate conversion methods.
The tool must return CStatus::OK if it wants to proceed with the interaction. If any other value is returned then the interaction will be aborted and no subsequent MouseDrag or MouseUp events will be received.
MouseDrag
    CStatus MyTool_MouseDrag( ToolContext &in_context )
This callback is called when the user is dragging with a mouse button is pressed in a 3D view.
MouseUp
    CStatus MyTool_MouseUp( ToolContext &in_context )
This callback is called when the user releases a mouse button to end interaction in a 3D view.
If ToolContext::WasAborted is true then the tool interaction was aborted because the user pressed Esc or the interaction was interrupted.
MouseMove
    CStatus MyTool_MouseMove( ToolContext &in_context )
This callback is called when the user moves the mouse cursor in a 3D view and no mouse buttons are pressed. This could be used to highlight on-screen controls or provide feedback on what is under the cursor.
MouseEnter
    CStatus MyTool_MouseEnter( ToolContext &in_context )
This callback is called when the mouse cursor enters a 3D view.
MouseLeave
    CStatus MyTool_MouseLeave( ToolContext &in_context )
This callback is called when the mouse cursor leaves a 3D view.
ModifierChanged
    CStatus MyTool_ModifierChanged( ToolContext &in_context )
This callback is called when a mouse modifier key changes. ToolContext::IsShiftKeyDown and ToolContext::IsControlKeyDown can be used to determine the current state of the modifier keys.
SelectionChanged
    CStatus MyTool_SelectionChanged( ToolContext &in_context )
This callback is called when the selection changes.
SnapValid
    CStatus MyTool_SnapValid( ToolContext &in_context )
This callback is called during snapping to allow the tool to reject unsuitable snap candidates. For example, when translating an object you would generally not want to snap to the object being moved.
For this callback to be triggered the tool must enable snapping and call one of ToolContext::GetWorldPosition or ToolContext::GetWorldRay. Alternatively, the tool may call ToolContext::Snap directly.
Information about the snap candidate can be accessed using ToolContext::GetSnapType, ToolContext::GetSnapObject and ToolContext::GetSnapComponent. Note: These methods may also be called from the mouse callbacks to get the overall result of the latest snap operation.
Note: This callback can be called numerous times during a single snap operation so it should try to minimize the amount of work it does and test the snap type first before attempting to access the object or components.
If the callback returns CStatus::OK the snap candidate will be allowed. Otherwise, the snap candidate will be ignored for snapping purposes.
KeyDown
    CStatus MyTool_KeyDown( ToolContext &in_context )
This callback is called on key down for shortcuts keys registered by the tool using ToolContext::RegisterShortcutKey.
Key information can be accessed using ToolContext::GetShortcutKey and ToolContext::GetShortcutKeyModifiers. Alternatively, the state of registered shortcut keys can be tested in other callbacks using ToolContext::IsShortcutKeyDown.
KeyUp
    CStatus MyTool_KeyUp( ToolContext &in_context )
This callback is called on key up for shortcuts keys registered by the tool using ToolContext::RegisterShortcutKey.
Key information can be accessed using ToolContext::GetShortcutKey and ToolContext::GetShortcutKeyModifiers. Alternatively, the state of registered shortcut keys can be tested in other callbacks using ToolContext::IsShortcutKeyDown.
MenuInit
    CStatus MyTool_MenuInit( ToolContext &in_context )
This callback is called by ToolContext::ShowContextMenu to set the contents of the menu. The Menu is accessed within the callback using Context::GetSource.
Example:
Simple plugin tool that uses picking to identify the object under the cursor. For a more detailed example see the CustomTools/netview_CustomTools SpotLightCreateTool custom tool example Tools can also be created from the Plugin Manager by flicking the File button and then chosing New > Tool.
    #ifndef linux
    #define WIN32_LEAN_AND_MEAN
    #include <windows.h> // Needed for OpenGL on windows
    #endif
    #include <GL/gl.h>
    #include <xsi_status.h>
    #include <xsi_argument.h>
    #include <xsi_toolcontext.h>
    #include <xsi_pluginregistrar.h>
    #include <xsi_math.h>
    
    using namespace XSI; 
    using namespace XSI::MATH; 
    
    class MyPickInfoTool {
    private: // Data
        LONG        m_cursorX;
        LONG        m_cursorY;
        CRefArray   m_picked;
    
    public: // Methods
        MyPickInfoTool() {}
    
        ~MyPickInfoTool() {}
    
        CStatus MouseMove( ToolContext& in_ctxt )
        {
            m_picked.Clear();
            in_ctxt.GetMousePosition( m_cursorX, m_cursorY );
    
            CLongArray l_points;
            l_points.Add( m_cursorX );
            l_points.Add( m_cursorY );
    
            // Check for object under the cursor
            in_ctxt.Pick( l_points, siPickSingleObject, siPickRaycast, L"", CRefArray(), m_picked );
            in_ctxt.Redraw( false );
            return CStatus::OK;
        }
    
        CStatus Draw( ToolContext& in_ctxt )
        {
            if ( in_ctxt.IsActiveView() && m_picked.GetCount() > 0 )
            {
                CString l_Str = m_picked.GetAsText();
                if ( l_Str.Length() > 0 )
                {
                    in_ctxt.BeginViewDraw();
    
                    LONG width = 0, height = 0, descent = 0;
                    in_ctxt.GetTextSize( l_Str, width, height, descent );
                    GLint x = (GLint)m_cursorX - width/2, y = (GLint)m_cursorY + 20;
    
                    // Draw text
                    glColor3d( 0, 0, 0 );
                    glRasterPos2i( x, y );
                    in_ctxt.DrawTextString( l_Str );
                }
            }
            return CStatus::OK;
        }
    };
        
    SICALLBACK XSILoadPlugin( PluginRegistrar& in_reg )
    {
        in_reg.PutAuthor(L"Autodesk Ltd");
        in_reg.PutName(L"Simple Tool Plugin");
        in_reg.PutVersion(1, 0);
        in_reg.RegisterTool(L"MyPickInfoTool");
        //RegistrationInsertionPoint - do not remove this line
        return CStatus::OK;
    }

    SICALLBACK MyPickInfoTool_Init( CRef& in_ctxt )
    {
        ToolContext l_ctxt( in_ctxt );
        PickInfoTool *l_pTool = new PickInfoTool;
        if ( !l_pTool ) return CStatus::Fail;
        l_ctxt.PutUserData( CValue((CValue::siPtrType)l_pTool) );
        return CStatus::OK;
    }
    
    SICALLBACK MyPickInfoTool_Term( CRef& in_ctxt )
    {
        ToolContext l_ctxt( in_ctxt );
        PickInfoTool *l_pTool = (PickInfoTool *)(CValue::siPtrType)l_ctxt.GetUserData();
        if ( !l_pTool ) return CStatus::Fail;
        delete l_pTool;
        l_ctxt.PutUserData( CValue((CValue::siPtrType)NULL) ); // Clear user data
        return CStatus::OK;
    }
    
    #define DECLARE_TOOL_CALLBACK(TOOL,CALLBACK) \
    SICALLBACK TOOL##_##CALLBACK( ToolContext& in_ctxt ) { \
        TOOL *l_pTool = (TOOL *)(CValue::siPtrType)in_ctxt.GetUserData(); \
        return ( l_pTool ? l_pTool->CALLBACK( in_ctxt ) : CStatus::Fail ); }
    
    DECLARE_TOOL_CALLBACK( MyPickInfoTool, MouseMove );
    DECLARE_TOOL_CALLBACK( MyPickInfoTool, Draw );
See also:
PluginRegistrar::RegisterTool
Since:
10.0 (2012)

#include <xsi_toolcontext.h>

Inheritance diagram for ToolContext:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 ToolContext ()
 ~ToolContext ()
 ToolContext (const CRef &in_ref)
 ToolContext (const ToolContext &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
ToolContextoperator= (const ToolContext &in_obj)
ToolContextoperator= (const CRef &in_ref)
bool IsShortcutKeyDown (ULONG in_virtualKeycode, ULONG in_modifiers=0) const
ULONG GetShortcutKey () const
ULONG GetShortcutKeyModifiers () const
Mouse and Keyboard Methods
CStatus GetMousePosition (LONG &x, LONG &y) const
bool IsLeftButtonDown () const
bool IsMiddleButtonDown () const
bool IsRightButtonDown () const
bool IsDoubleClick () const
bool IsShiftKeyDown () const
bool IsControlKeyDown () const
CStatus RegisterShortcutKey (ULONG in_virtualKeycode, const CString &in_description, ULONG in_modifiers=0, bool in_repeats=false)
CStatus UnRegisterShortcutKey (ULONG in_virtualKeycode, ULONG in_modifiers=0)
View Methods
CStatus GetViewSize (LONG &width, LONG &height) const
CStatus GetViewport (LONG &x, LONG &y, LONG &width, LONG &height) const
bool IsInteracting () const
bool IsActiveView () const
bool IsNavigating () const
LONG GetViewIndex () const
Camera GetCamera () const
Tool State Methods
CStatus SetCursor (siToolCursor in_cursorId)
CStatus SetToolDescription (const CString &in_message)
CStatus EnableSnapping (bool in_enable)
CStatus GetViewPlane (MATH::CPlane &out_plane) const
CStatus GetGridPlane (MATH::CPlane &out_plane) const
CStatus SetManipulationPlane (const MATH::CPlane &in_plane)
CStatus ClearManipulationPlane ()
bool WasAborted () const
CStatus ExitTool ()
bool GetFlag (LONG in_flag) const
CStatus SetFlag (LONG in_flag, bool in_enable)
Coordinate Conversion Methods
CStatus GetWorldPosition (LONG x, LONG y, MATH::CVector3 &out_world) const
CStatus GetWorldRay (LONG x, LONG y, MATH::CLine &out_ray) const
CStatus WorldToView (const MATH::CVector3 &in_world, MATH::CVector3 &out_view) const
CStatus ViewToWorld (const MATH::CVector3 &in_view, MATH::CVector3 &out_world) const
CStatus WorldToCamera (const MATH::CVector3 &in_world, MATH::CVector3 &out_camera) const
CStatus CameraToWorld (const MATH::CVector3 &in_view, MATH::CVector3 &out_world) const
CStatus GetWorldToViewMatrix (MATH::CMatrix4 &out_worldToView) const
CStatus GetWorldToCameraMatrix (MATH::CMatrix4 &out_worldToCamera) const
Drawing and Text Methods
CStatus Redraw (bool in_allViews=true)
CStatus DrawTextString (const CString &in_str, siAlignment in_hPos=siLeftAlign, siAlignment in_vPos=siBottomAlign)
CStatus GetTextSize (const CString &in_str, LONG &out_width, LONG &out_height, LONG &out_descent) const
CStatus EditTextString (CString &io_str, LONG x, LONG y, LONG width, LONG height)
CStatus BeginViewDraw ()
CStatus EndViewDraw ()
bool IsViewDraw () const
CStatus BeginPickDraw (LONG x, LONG y, LONG width, LONG height)
CStatus EndPickDraw ()
bool IsPickDraw () const
Interactive Data Update Methods
CStatus BeginParameterUpdate (const Parameter &in_param, double in_time=DBL_MAX)
CStatus UpdateParameter (const Parameter &in_param, const CValue &in_value)
CStatus EndParameterUpdate (const Parameter &in_param)
CStatus BeginKinematicStateUpdate (const KinematicState &in_kine, double in_time=DBL_MAX)
CStatus UpdateKinematicState (const KinematicState &in_kine, const MATH::CTransformation &in_value)
CStatus EndKinematicStateUpdate (const KinematicState &in_kine)
CStatus BeginTransformUpdate (const CRefArray &in_objects, double in_time=DBL_MAX)
CStatus UpdateTransform (const CRefArray &in_objects, const MATH::CTransformation &in_value, siTransformFilter in_srt, siRefMode in_refMode=siLocal, siDeltaMode in_delta=siRelative, siAxesFilter in_axesFilter=siXYZ, bool in_usePivot=false, const MATH::CVector3 &in_pivot=MATH::CVector3(), const MATH::CTransformation &in_reference=MATH::CTransformation())
CStatus EndTransformUpdate (const CRefArray &in_objects)
Snapping Methods
siSnapType GetSnapType () const
CRef GetSnapObject () const
CRef GetSnapComponent () const
CStatus Snap (LONG x, LONG y, LONG size, ULONG in_snaptype, const CStringArray &in_families, const CRefArray &in_objects, MATH::CVector3 &out_world) const
Picking Methods
CStatus Pick (const CLongArray &in_points, siPickMode in_pickMode, siPickType in_pickType, const CString &in_filter, const CRefArray &in_objects, CRefArray &out_picked) const
PickBuffer GetPickBuffer (LONG x, LONG y, LONG width, LONG height, const CString &in_filter, const CRefArray &in_objects, siViewMode in_viewMode=siShaded) const
Context Menu Methods
CStatus ShowContextMenu (LONG x, LONG y, siAlignment in_hPos=siLeftAlign, siAlignment in_vPos=siTopAlign)
Utility Methods
Image LoadImageFromFile (const CString &in_filename, bool in_relativePath=true)

Constructor & Destructor Documentation

Default constructor.

Default destructor.

ToolContext ( const CRef in_ref)

Constructor.

Parameters:
in_refconstant reference object.
ToolContext ( const ToolContext in_obj)

Copy constructor.

Parameters:
in_objconstant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassIDclass type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from Context.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from Context.

ToolContext& operator= ( const ToolContext in_obj)

Creates an object from another object.

Parameters:
in_objconstant class object.
Returns:
The new ToolContext object.
ToolContext& operator= ( const CRef in_ref)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_refconstant class object.
Returns:
The new ToolContext object.

Reimplemented from Context.

CStatus GetMousePosition ( LONG &  x,
LONG &  y 
) const

Returns the mouse coordinates relative to the current view

Parameters:
xmouse X coordinate in pixels.
ymouse Y coordinate in pixels.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool IsLeftButtonDown ( ) const

Returns left mouse button state.

bool IsMiddleButtonDown ( ) const

Returns middle mouse button state.

bool IsRightButtonDown ( ) const

Returns right mouse button state.

bool IsDoubleClick ( ) const

Returns whether mouse button was double clicked

bool IsShiftKeyDown ( ) const

Returns shift key state.

bool IsControlKeyDown ( ) const

Returns control key state.

CStatus RegisterShortcutKey ( ULONG  in_virtualKeycode,
const CString in_description,
ULONG  in_modifiers = 0,
bool  in_repeats = false 
)

Register a tool keyboard shortcut.

Parameters:
in_virtualKeycodeVirtual keycode for the keyboard shortcut.
in_descriptionShortcut key description.
in_modifiers.siKeyboardState modifier for the keyboard shortcut
in_repeats.If true key events will be continuously sent while the key is held down.
Returns:
CStatus::OK success.
CStatus::Fail error.
CStatus UnRegisterShortcutKey ( ULONG  in_virtualKeycode,
ULONG  in_modifiers = 0 
)

Unregister a tool keyboard shortcut.

Parameters:
in_virtualKeycodeVirtual keycode for the keyboard shortcut.
in_modifiers.siKeyboardState modifier for the keyboard shortcut
Returns:
CStatus::OK success.
CStatus::Fail error.
bool IsShortcutKeyDown ( ULONG  in_virtualKeycode,
ULONG  in_modifiers = 0 
) const

Get current state of tool keyboard shortcut.

Parameters:
in_virtualKeycodeVirtual keycode for the keyboard shortcut.
in_modifiers.siKeyboardState modifier for the keyboard shortcut
Returns:
True if shortcut key is pressed.
ULONG GetShortcutKey ( ) const

Get virtual keycode for the key being processed in KeyUp/KeyDown callback.

Returns:
Virtual keycode or 0 if called from outside KeyUp/KeyDown callbacks.
ULONG GetShortcutKeyModifiers ( ) const

Get modifiers for the key being processed in KeyUp/KeyDown callback.

Returns:
Modifier flags or 0 if called from outside KeyUp/KeyDown callbacks.
CStatus GetViewSize ( LONG &  width,
LONG &  height 
) const

Returns the size of the view in pixel coordinates.

Parameters:
widthwidth of view in pixels
heightheight of view in pixels
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetViewport ( LONG &  x,
LONG &  y,
LONG &  width,
LONG &  height 
) const

Returns the 3D viewport in pixel coordinates. The 3D viewport can be a subset of the actual view size.

Parameters:
xhorizontal offset in pixels
yvertical offset in pixels
widthwidth of viewport in pixels
heightheight of viewport in pixels
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool IsInteracting ( ) const

Returns true if a MouseDown/MouseDrag/MouseUp is in progress.

bool IsActiveView ( ) const

Returns true if the view being drawn is the last view under the cursor.

bool IsNavigating ( ) const

Returns true if tool is being drawn and camera tool is currently active in supra mode.

LONG GetViewIndex ( ) const

Get index of current view. The view index may be used by the tool identify the view but the caller should not assume the index corresponds directly to the view manager (A/B/C/D) panes.

Returns:
Returns view index (greater or equal than zero) or -1 if the information is unavailable in current callback.
Camera GetCamera ( ) const

Return the camera for the current view

Returns:
Camera or invalid reference if unavailable in current callback.
CStatus SetCursor ( siToolCursor  in_cursorId)

Set tool cursor

Parameters:
in_cursorIdPredefined cursor to use. Default is siArrowCursor.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus SetToolDescription ( const CString in_message)

Set tool description

Parameters:
in_messageTool message string with newlines separating description/left/middle/right message sections.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus EnableSnapping ( bool  in_enable)

Enable standard tool snapping behaviour

Parameters:
in_enableEnable standard control key snapping behaviour for this tool.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetViewPlane ( MATH::CPlane out_plane) const

Get view plane

Parameters:
out_planeGet view aligned manipulation plane in this view.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus GetGridPlane ( MATH::CPlane out_plane) const

Get grid plane

Parameters:
out_planeGet visible grid plane in this view.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus SetManipulationPlane ( const MATH::CPlane in_plane)

Set projection plane

Parameters:
in_planeNew projection plane.
Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
CStatus ClearManipulationPlane ( )

Restore projection plane to default setting

Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool WasAborted ( ) const

Returns true if user pressed Escape to end mouse drag.

CStatus ExitTool ( )

Schedule this tool for termination

Returns:
CStatus::OK success.
CStatus::Fail Unavailable in current callback.
bool GetFlag ( LONG  in_flag) const

Returns the state of one of the various flags that affects tool behavior. You can set the value of a flag with ToolContext::SetFlag.

Parameters:
in_flagValue from the siToolCapabilities enum
CStatus SetFlag ( LONG  in_flag,
bool  in_enable 
)

Sets the state of one of the various flags that affects tool behavior. You can test the value of these flags with ToolContext::GetFlag.

Parameters:
in_flagValue from the siToolCapabilities enum
in_enableTrue to enable the flag and false to disable it.
Returns:
CStatus::OK success.
CStatus::Fail Unrecognized flag.
CStatus GetWorldPosition ( LONG  x,
LONG  y,
MATH::CVector3 out_world 
) const

Get 3D world-space point by projecting the 2D input point onto the current manipulation plane. If snapping is enabled and active then snapping will be applied to the resulting point. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
xview X coordinate in pixels.
yview Y coordinate in pixels.
out_world3D world-space position.
Returns:
CStatus::OK Projection succeeded.
CStatus::Fail Unavailable in current callback or point does not intersect the projection plane.
CStatus GetWorldRay ( LONG  x,
LONG  y,
MATH::CLine out_ray 
) const

Get 3D world-space ray through the 2D input point. If snapping is enabled and active then snapping will be applied to the resulting ray. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
xview X coordinate in pixels.
yview Y coordinate in pixels.
out_ray3D world-space ray.
Returns:
CStatus::OK Projection succeeded.
CStatus::Fail Unavailable in current callback.
CStatus WorldToView ( const MATH::CVector3 in_world,
MATH::CVector3 out_view 
) const

Convert a 3D world-space point to 2D pixel coordinates with depth. No snapping is applied to points. The X & Y coordinates of the output point represent 2D view coordinates while the Z component represents the depth.

Parameters:
in_worldworld-space input point
out_viewview-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus ViewToWorld ( const MATH::CVector3 in_view,
MATH::CVector3 out_world 
) const

Convert a 2D pixel coordinate with depth to a 3D world-space point. No snapping is applied to points.

Parameters:
in_viewview-space input point
out_viewworld-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus WorldToCamera ( const MATH::CVector3 in_world,
MATH::CVector3 out_camera 
) const

Convert a 3D world-space point to 3D camera-space point. No snapping is applied to points.

Parameters:
in_worldworld-space input point
out_cameracamera-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus CameraToWorld ( const MATH::CVector3 in_view,
MATH::CVector3 out_world 
) const

Convert a 3D camera-space point to a 3D world-space point. No snapping is applied to points.

Parameters:
in_cameracamera-space input point
out_worldworld-space output point
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus GetWorldToViewMatrix ( MATH::CMatrix4 out_worldToView) const

Return matrix used to transform 3D world-space points to 2D pixel coordinates with depth.

Parameters:
out_worldToviewworld-to-view 4x4 matrix
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus GetWorldToCameraMatrix ( MATH::CMatrix4 out_worldToCamera) const

Return matrix used to transform 3D world-space points to 3D camera-space points.

Parameters:
out_worldToCameraworld-to-camera 4x4 matrix
Returns:
CStatus::OK Succeeded.
CStatus::Fail Unavailable in current callback.
CStatus Redraw ( bool  in_allViews = true)

Request redraw. In most cases the redraw happens automatically so the only place this is needed is to trigger redraw based on mouse move events. (when no mouse buttons are pressed)

Parameters:
in_allViewsIf true redraw all views. If false redraw current view only.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback.
CStatus DrawTextString ( const CString in_str,
siAlignment  in_hPos = siLeftAlign,
siAlignment  in_vPos = siBottomAlign 
)

Draw text at current raster position and with the specified alignment. Only valid during drawing.

Parameters:
in_strText string to display.
in_hPosHorizontal text position relative to the current raster position. Default is siLeftAlign.
in_vPosVertical text position relative to the current raster position. Default is siBottomAlign.
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing.
CStatus GetTextSize ( const CString in_str,
LONG &  out_width,
LONG &  out_height,
LONG &  out_descent 
) const

Get size of text in 2D pixel coordinates. Only valid during drawing.

Parameters:
in_strText string to measure.
out_widthWidth of text string in pixels.
out_heightHeight of text string in pixels.
out_descentNumber of pixels the font extends below the baseline for the font.
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing.
CStatus EditTextString ( CString io_str,
LONG  x,
LONG  y,
LONG  width,
LONG  height 
)

Display in-place text editing field at the specified 2D pixel coordinates. Only valid during mouse up.

Parameters:
io_strText string to modify.
xleft view coordinate of text editing box in pixels
ybottom view coordinate of text editing box in pixels
widthwidth of text editing box in pixels
heightheight of text editing box in pixels
Returns:
CStatus::OK Success.
CStatus::False User cancelled editing.
CStatus::Fail Called from outside the mouse up callback.
CStatus BeginViewDraw ( )

Change drawing to 2D pixel coordinates. Only valid during drawing/picking.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing/picking.
CStatus EndViewDraw ( )

Change drawing back to 3D world-space coordinates. Only valid during drawing/picking.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside drawing/picking.
bool IsViewDraw ( ) const

Returns true if view drawing is active.

CStatus BeginPickDraw ( LONG  x,
LONG  y,
LONG  width,
LONG  height 
)

Setup drawing for OpenGL picking. The pick region is centered on the specified x/y coordinates. Only valid during mouse callbacks.

Parameters:
xhorizontal view coordinate of pick region in pixels
yvertical view coordinate of pick region in pixels
widthwidth of pick region in pixels
heightheight of pick region in pixels
Returns:
CStatus::OK Success.
CStatus::Fail Called from outside mouse callbacks.
CStatus EndPickDraw ( )

Restore drawing to original state. Only valid during mouse callbacks.

Returns:
CStatus::OK Success.
CStatus::Fail Called from outside mouse callbacks.
bool IsPickDraw ( ) const

Returns true if pick drawing is active.

CStatus BeginParameterUpdate ( const Parameter in_param,
double  in_time = DBL_MAX 
)

Start an interaction update on a parameter. At the end of interaction a single undo event will be logged.

Parameters:
in_paramThe parameter to update.
in_timeTime defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus UpdateParameter ( const Parameter in_param,
const CValue in_value 
)

Update value of parameter during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_paramThe parameter to set.
in_valueNew value for parameter.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndParameterUpdate ( const Parameter in_param)

Stop updating parameter and log undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_paramThe parameter to stop updating.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus BeginKinematicStateUpdate ( const KinematicState in_kine,
double  in_time = DBL_MAX 
)

Start an interaction update on a kinematic state. At the end of interaction a single undo event will be logged.

Parameters:
in_kineThe kinematic state to update.
in_timeTime defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus UpdateKinematicState ( const KinematicState in_kine,
const MATH::CTransformation in_value 
)

Update value of kinematic state during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_kineThe kinematic state to set.
in_valueNew value for the kinematic state.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndKinematicStateUpdate ( const KinematicState in_kine)

Stop updating kinematic state and log undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_kineThe kinematic state to stop updating.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus BeginTransformUpdate ( const CRefArray in_objects,
double  in_time = DBL_MAX 
)

Start an interaction update on a list of objects or components. At the end of interaction a single undo event will be logged.

Parameters:
in_objectsList of objects or components to update.
in_timeTime defaults to the current frame if in_time is set with DBL_MAX.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus UpdateTransform ( const CRefArray in_objects,
const MATH::CTransformation in_value,
siTransformFilter  in_srt,
siRefMode  in_refMode = siLocal,
siDeltaMode  in_delta = siRelative,
siAxesFilter  in_axesFilter = siXYZ,
bool  in_usePivot = false,
const MATH::CVector3 in_pivot = MATH::CVector3(),
const MATH::CTransformation in_reference = MATH::CTransformation() 
)

Update value of objects or components during interaction. At the end of interaction a single undo event will be logged.

Parameters:
in_objectsList of objects or components to update.
in_valueNew transform values.
in_srtType of transform that will be applied.
in_refModeReference mode to use for the transform. Default is siLocal.
in_deltaRelative or absolute transform. Default is siRelative.
in_axesFilterUsed with siAbsolute to specify which transform axes to modify. Default is siXYZ.
in_usePivotPerform transform relative to a pivot. Default is false.
in_pivotGlobal pivot location. Default pivot is world-space origin.
in_referenceReference-to-world transform to use with siObjCtr. Default is identity which is world-space.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
CStatus EndTransformUpdate ( const CRefArray in_objects)

Stop updating objects or components and log an undo event. At the end of interaction a single undo event will be logged.

Parameters:
in_objectsList of objects or components to update.
Returns:
CStatus::OK Success.
CStatus::Fail Unavailable in current callback or other failure.
CStatus::InvalidArgument Invalid argument.
siSnapType GetSnapType ( ) const

Return the siSnapType from the last snap operation or the current snap candidate if called from within the SnapValid callback. siSnapNone is returned if nothing was snapped or if this information is unavailable in the current callback.

CRef GetSnapObject ( ) const

Return the last snapped object or the current snap candidate object if called from within the SnapValid callback. Some snap types like siSnapNone and siSnapGrid do not have an associated object and in this case the returned reference will be invalid.

CRef GetSnapComponent ( ) const

Return the last snapped component or the current snap candidate if called from within the SnapValid callback. Some snap types are not associated with a component and in that case the returned reference will be invalid.

CStatus Snap ( LONG  x,
LONG  y,
LONG  size,
ULONG  in_snaptype,
const CStringArray in_families,
const CRefArray in_objects,
MATH::CVector3 out_world 
) const

Get 3D world-space point by snapping the 2D input point using the specified snap settings. Detailed information about the snap target can be obtained using the snapping access methods such as ToolContext::GetSnapType following this call.

Parameters:
xView X coordinate in pixels.
yView Y coordinate in pixels.
sizeSize of snap region in pixels.
in_snaptypeMask of siSnapType flags used to specify what types of snap targets will be considered. For example pass siSnapPoint|siSnapGrid to enable both point and grid snapping.
in_familiesAn array of families defined by ::siFamily or an empty array if none are required. The families are used for narrowing down the search, the array can contain X3DObject families like si3DObjectFamily or primitive families such as siNurbsSurfaceMeshFamily and siNullPrimitiveFamily. Only the children objects that match one of the supplied families are considered. If primitive families are supplied then only the objects defined with a primitive that belongs to one of them are considered. The list of valid families are the following:
in_objectsList of objects to snap to. If empty then the entire scene will be used.
out_world3D world-space position.
Returns:
CStatus::OK Snap succeeded.
CStatus::Fail Unavailable in current callback.
CStatus::InvalidArgument Invalid argument specified.
CStatus Pick ( const CLongArray in_points,
siPickMode  in_pickMode,
siPickType  in_pickType,
const CString in_filter,
const CRefArray in_objects,
CRefArray out_picked 
) const

Perform a pick operation on the view and return the list of objects or components that match.

Parameters:
in_pointsPoints to use for picking. The array size should be a multiple of 2 with each pair of values representing a single 2D view point. The number of points required depends on the picking mode. For siPickRaycast a single point is required. For siPickRectangle and siPickRectangleRaycast two points are needed. For siPickLasso and siPickFreeform can use an arbitrary number of points which define a path.
in_pickModePicking mode. For objects use siPickSingleObject or siPickMultipleObjects and for subcomponents use siPickSingleSubComponent or siPickMultipleSubComponents.
in_pickTypeDefines the type of picking used. One of siPickRectangle, siPickRaycast, siPickLasso, siPickFreeform or siPickRectangleRaycast.
in_filterA filter to use for picking. For object picking this can be empty but must be supplied for subcomponent picking to identify the subcomponent to pick. The list of valid filters are the following:
in_objectsList of objects to pick. When picking objects this list is optional and if empty the entire scene will be used. When picking subcomponents the list must supplied and non-empty.
out_pickedList of picked objects.
Returns:
CStatus::OK Pick succeeded.
CStatus::Fail Unavailable in current callback.
CStatus::InvalidArgument Invalid argument specified.
PickBuffer GetPickBuffer ( LONG  x,
LONG  y,
LONG  width,
LONG  height,
const CString in_filter,
const CRefArray in_objects,
siViewMode  in_viewMode = siShaded 
) const

Low-level picking operation that returns a buffer that can be used to map view coordinates to objects and component indices. The pick buffer acts like a snapshot taken at the time of the call and once it has been generated objects and component indices can be retrieved from the pick buffer without any additional overhead. The pick buffer will only return information about the closest object or component and cannot return information for objects and components that are hidden behind other objects or components. Passing an empty pick region (0,0,0,0) will generate a pick buffer that covers the entire view.

Parameters:
xLeft view coordinate of picking region.
yBottom view coordinate of picking region.
widthWidth of picking region in view coordinates.
heightHeight of picking region in view coordinates.
in_filterA filter to use for picking. For object picking this can be empty but must be supplied for subcomponent picking to identify the subcomponent to pick. The list of valid filters are the following:
in_objectsList of objects to pick. When picking objects this list is optional and if empty the entire scene will be used. When picking subcomponents the list must supplied and non-empty.
in_viewModesiViewMode to use when generating the pick buffer. Passing siAll will use the current display mode. Default is siShaded. The list of valid view modes are the following:
                        siAll (current view mode)
                        siWireframe
                        siShaded (default)
Returns:
PickBuffer. If unavailable in the current callback or any arguments are invalid then the resulting PickBuffer will be invalid.
CStatus ShowContextMenu ( LONG  x,
LONG  y,
siAlignment  in_hPos = siLeftAlign,
siAlignment  in_vPos = siTopAlign 
)

Show a tool context menu using the specified position/alignment. Only valid during mouse down or mouse up. The context menu needs to be defined by the MenuInit callback in the tool.

Parameters:
xView X coordinate in pixels.
yView Y coordinate in pixels.
in_hPosHorizontal menu position relative to the input position. Default is siLeftAlign.
in_vPosVertical menu position relative to the input position. Default is siTopAlign.
Returns:
CStatus::OK Success.
CStatus::False Nothing selected from menu or no menu to display.
CStatus::Fail Called from outside mouse down or mouse up callback.
Image LoadImageFromFile ( const CString in_filename,
bool  in_relativePath = true 
)

Load an image from a file.

Parameters:
in_filenameFilename of image to load.
in_relativePathIf true in_filename is relative to plugin location.
Returns:
Requested Image.

The documentation for this class was generated from the following file: