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