This reference page is linked to from the following overview topics: Softimage 2012.

#include <xsi_toolcontext.h>

Class 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 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)

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]

x	mouse X coordinate in pixels.
y	mouse Y coordinate in pixels.

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

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.

CStatus UnRegisterShortcutKey	(	ULONG	in_virtualKeycode,
		ULONG	in_modifiers = `0`
	)

bool IsShortcutKeyDown	(	ULONG	in_virtualKeycode,
		ULONG	in_modifiers = `0`
	)		const

CStatus GetViewport	(	LONG &	x,
		LONG &	y,
		LONG &	width,
		LONG &	height
	)		const

x	horizontal offset in pixels
y	vertical offset in pixels
width	width of viewport in pixels
height	height of viewport in pixels

in_flag	Value from the siToolCapabilities enum
in_enable	True to enable the flag and false to disable it.

CStatus GetWorldPosition	(	LONG	x,
		LONG	y,
		MATH::CVector3 &	out_world
	)		const

x	view X coordinate in pixels.
y	view Y coordinate in pixels.
out_world	3D world-space position.

CStatus GetWorldRay	(	LONG	x,
		LONG	y,
		MATH::CLine &	out_ray
	)		const

x	view X coordinate in pixels.
y	view Y coordinate in pixels.
out_ray	3D world-space ray.

CStatus WorldToView	(	const MATH::CVector3 &	in_world,
		MATH::CVector3 &	out_view
	)		const

in_world	world-space input point
out_view	view-space output point

CStatus ViewToWorld	(	const MATH::CVector3 &	in_view,
		MATH::CVector3 &	out_world
	)		const

in_view	view-space input point
out_view	world-space output point

CStatus WorldToCamera	(	const MATH::CVector3 &	in_world,
		MATH::CVector3 &	out_camera
	)		const

in_world	world-space input point
out_camera	camera-space output point

CStatus CameraToWorld	(	const MATH::CVector3 &	in_view,
		MATH::CVector3 &	out_world
	)		const

in_camera	camera-space input point
out_world	world-space output point

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

CStatus DrawTextString	(	const CString &	in_str,
		siAlignment	in_hPos = `siLeftAlign`,
		siAlignment	in_vPos = `siBottomAlign`
	)

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.

CStatus GetTextSize	(	const CString &	in_str,
		LONG &	out_width,
		LONG &	out_height,
		LONG &	out_descent
	)		const

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.

CStatus EditTextString	(	CString &	io_str,
		LONG	x,
		LONG	y,
		LONG	width,
		LONG	height
	)

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

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

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

in_param	The parameter to update.
in_time	Time defaults to the current frame if `in_time` is set with `DBL_MAX`.

CStatus UpdateParameter	(	const Parameter &	in_param,
		const CValue &	in_value
	)