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:

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
ToolContext &	operator= (const ToolContext &in_obj)
ToolContext &	operator= (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

ToolContext

(

)

Default constructor.

~ToolContext

(

)

Default destructor.

ToolContext

(

const CRef &

in_ref

)

Constructor.

Parameters:

in_ref

constant reference object.

ToolContext

(

const ToolContext &

in_obj

)

Copy constructor.

Parameters:

in_obj

constant 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_ClassID

class 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_obj

constant 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_ref

constant 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:

x	mouse X coordinate in pixels.
y	mouse 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_virtualKeycode	Virtual keycode for the keyboard shortcut.
in_description	Shortcut 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_virtualKeycode	Virtual 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_virtualKeycode	Virtual 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:

width	width of view in pixels
height	height 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:

x	horizontal offset in pixels
y	vertical offset in pixels
width	width of viewport in pixels
height	height 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_cursorId

Predefined 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_message

Tool 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_enable

Enable 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_plane

Get 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_plane

Get 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_plane

New 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_flag

Value 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_flag	Value from the siToolCapabilities enum
in_enable	True 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:

x	view X coordinate in pixels.
y	view Y coordinate in pixels.
out_world	3D 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:

x	view X coordinate in pixels.
y	view Y coordinate in pixels.
out_ray	3D 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_world	world-space input point
out_view	view-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_view	view-space input point
out_view	world-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_world	world-space input point
out_camera	camera-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_camera	camera-space input point
out_world	world-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_worldToview

world-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_worldToCamera

world-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_allViews

If 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_str	Text string to display.
in_hPos	Horizontal text position relative to the current raster position. Default is siLeftAlign.
in_vPos	Vertical 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_str	Text string to measure.
out_width	Width of text string in pixels.
out_height	Height of text string in pixels.
out_descent	Number 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_str	Text string to modify.
x	left view coordinate of text editing box in pixels
y	bottom view coordinate of text editing box in pixels
width	width of text editing box in pixels
height	height 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:

x	horizontal view coordinate of pick region in pixels
y	vertical view coordinate of pick region in pixels
width	width of pick region in pixels
height	height 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_param	The parameter to update.
in_time	Time 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_param	The parameter to set.
in_value	New 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_param

The 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_kine	The kinematic state to update.
in_time	Time 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_kine	The kinematic state to set.
in_value	New 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_kine

The 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_objects	List of objects or components to update.
in_time	Time 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_objects	List of objects or components to update.
in_value	New transform values.
in_srt	Type of transform that will be applied.
in_refMode	Reference mode to use for the transform. Default is siLocal.
in_delta	Relative or absolute transform. Default is siRelative.
in_axesFilter	Used with siAbsolute to specify which transform axes to modify. Default is siXYZ.
in_usePivot	Perform transform relative to a pivot. Default is false.
in_pivot	Global pivot location. Default pivot is world-space origin.
in_reference	Reference-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_objects

List 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:

x	View X coordinate in pixels.
y	View Y coordinate in pixels.
size	Size of snap region in pixels.
in_snaptype	Mask 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_families	An 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: si3DObjectFamily siLatticeFamily siCameraFamily siLightPrimitiveFamily siChainElementFamily siMeshFamily siControlObjectFamily siNullPrimitiveFamily siCurveFamily siNurbsCurveListFamily siGeometryFamily siNurbsSurfaceMeshFamily siGeometryShaderFamily siSurfaceCurveFamily siImplicitGeometryFamily siSurfaceFamily
in_objects	List of objects to snap to. If empty then the entire scene will be used.
out_world	3D 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_points	Points 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_pickMode	Picking mode. For objects use siPickSingleObject or siPickMultipleObjects and for subcomponents use siPickSingleSubComponent or siPickMultipleSubComponents.
in_pickType	Defines the type of picking used. One of siPickRectangle, siPickRaycast, siPickLasso, siPickFreeform or siPickRectangleRaycast.
in_filter	A 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: siCameraFilter siBoundaryFilter siChainElementFilter siEdgeFilter siControlFilter siIsopointFilter siCurveFilter siKnotFilter siEffectorFilter siPointFilter siGeometryFilter siPolygonFilter siGroupFilter siUIsolineFilter siImplicitFilter siVIsolineFilter siLatticeFilter siUKnotCurveFilter siLightFilter siVKnotCurveFilter siModelFilter siNullFilter siPointCloudFilter siPolyMeshFilter siPrimitiveFilter siSkeletonJointFilter siSubSurfaceFilter siSurfaceCurveFilter siSurfaceMeshFilter siTextureControlFilter siTrimCurveFilter
in_objects	List 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_picked	List 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:

x	Left view coordinate of picking region.
y	Bottom view coordinate of picking region.
width	Width of picking region in view coordinates.
height	Height of picking region in view coordinates.
in_filter	A 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: siObjectFilter siPointFilter siEdgeFilter siPolygonFilter
in_objects	List 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_viewMode	siViewMode 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:

x	View X coordinate in pixels.
y	View Y coordinate in pixels.
in_hPos	Horizontal menu position relative to the input position. Default is siLeftAlign.
in_vPos	Vertical 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_filename	Filename of image to load.
in_relativePath	If true in_filename is relative to plugin location.

Returns:

Requested Image.

---

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

• xsi_toolcontext.h