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.
{plugin_item_name}_{callback_name}
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.CStatus MyTool_Setup( ToolContext &in_context )
CStatus MyTool_Cleanup( ToolContext &in_context )
CStatus MyTool_Activate( ToolContext &in_context )
CStatus MyTool_Deactivate( ToolContext &in_context )
CStatus MyTool_Draw( ToolContext &in_context )
CStatus MyTool_MouseDown( ToolContext &in_context )
CStatus MyTool_MouseDrag( ToolContext &in_context )
CStatus MyTool_MouseUp( ToolContext &in_context )
CStatus MyTool_MouseMove( ToolContext &in_context )
CStatus MyTool_MouseEnter( ToolContext &in_context )
CStatus MyTool_MouseLeave( ToolContext &in_context )
CStatus MyTool_ModifierChanged( ToolContext &in_context )
CStatus MyTool_SelectionChanged( ToolContext &in_context )
CStatus MyTool_SnapValid( ToolContext &in_context )
CStatus MyTool_KeyDown( ToolContext &in_context )
CStatus MyTool_KeyUp( ToolContext &in_context )
CStatus MyTool_MenuInit( ToolContext &in_context )
#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 );
#include <xsi_toolcontext.h>
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) |
ToolContext | ( | ) |
Default constructor.
~ToolContext | ( | ) |
Default destructor.
ToolContext | ( | const CRef & | in_ref | ) |
Constructor.
in_ref | constant reference object. |
ToolContext | ( | const ToolContext & | in_obj | ) |
Copy constructor.
in_obj | constant class object. |
bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
in_ClassID | class type. |
Reimplemented from Context.
siClassID GetClassID | ( | ) | const [virtual] |
ToolContext& operator= | ( | const ToolContext & | in_obj | ) |
Creates an object from another object.
in_obj | constant class 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.
in_ref | constant class object. |
Reimplemented from Context.
CStatus GetMousePosition | ( | LONG & | x, |
LONG & | y | ||
) | const |
Returns the mouse coordinates relative to the current view
x | mouse X coordinate in pixels. |
y | mouse Y coordinate in pixels. |
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.
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 |
||
) |
Unregister a tool keyboard shortcut.
in_virtualKeycode | Virtual keycode for the keyboard shortcut. |
in_modifiers. | siKeyboardState modifier for the keyboard shortcut |
bool IsShortcutKeyDown | ( | ULONG | in_virtualKeycode, |
ULONG | in_modifiers = 0 |
||
) | const |
Get current state of tool keyboard shortcut.
in_virtualKeycode | Virtual keycode for the keyboard shortcut. |
in_modifiers. | siKeyboardState modifier for the keyboard shortcut |
ULONG GetShortcutKey | ( | ) | const |
Get virtual keycode for the key being processed in KeyUp/KeyDown callback.
ULONG GetShortcutKeyModifiers | ( | ) | const |
Get modifiers for the key being processed in KeyUp/KeyDown callback.
CStatus GetViewSize | ( | LONG & | width, |
LONG & | height | ||
) | const |
Returns the size of the view in pixel coordinates.
width | width of view in pixels |
height | height of view in pixels |
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.
x | horizontal offset in pixels |
y | vertical offset in pixels |
width | width of viewport in pixels |
height | height of viewport in pixels |
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.
Camera GetCamera | ( | ) | const |
Return the camera for the current view
CStatus SetCursor | ( | siToolCursor | in_cursorId | ) |
Set tool cursor
in_cursorId | Predefined cursor to use. Default is siArrowCursor. |
Set tool description
in_message | Tool message string with newlines separating description/left/middle/right message sections. |
CStatus EnableSnapping | ( | bool | in_enable | ) |
Enable standard tool snapping behaviour
in_enable | Enable standard control key snapping behaviour for this tool. |
CStatus GetViewPlane | ( | MATH::CPlane & | out_plane | ) | const |
Get view plane
out_plane | Get view aligned manipulation plane in this view. |
CStatus GetGridPlane | ( | MATH::CPlane & | out_plane | ) | const |
Get grid plane
out_plane | Get visible grid plane in this view. |
CStatus SetManipulationPlane | ( | const MATH::CPlane & | in_plane | ) |
Set projection plane
in_plane | New projection plane. |
CStatus ClearManipulationPlane | ( | ) |
Restore projection plane to default setting
bool WasAborted | ( | ) | const |
Returns true if user pressed Escape to end mouse drag.
CStatus ExitTool | ( | ) |
Schedule this tool for termination
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.
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.
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 |
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.
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 |
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.
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 |
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.
in_world | world-space input point |
out_view | view-space output point |
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.
in_view | view-space input point |
out_view | world-space output point |
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.
in_world | world-space input point |
out_camera | camera-space output point |
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.
in_camera | camera-space input point |
out_world | world-space output point |
CStatus GetWorldToViewMatrix | ( | MATH::CMatrix4 & | out_worldToView | ) | const |
Return matrix used to transform 3D world-space points to 2D pixel coordinates with depth.
out_worldToview | world-to-view 4x4 matrix |
CStatus GetWorldToCameraMatrix | ( | MATH::CMatrix4 & | out_worldToCamera | ) | const |
Return matrix used to transform 3D world-space points to 3D camera-space points.
out_worldToCamera | world-to-camera 4x4 matrix |
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)
in_allViews | If true redraw all views. If false redraw current view only. |
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.
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 |
Get size of text in 2D pixel coordinates. Only valid during drawing.
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. |
Display in-place text editing field at the specified 2D pixel coordinates. Only valid during mouse up.
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 |
CStatus BeginViewDraw | ( | ) |
Change drawing to 2D pixel coordinates. Only valid during drawing/picking.
CStatus EndViewDraw | ( | ) |
Change drawing back to 3D world-space coordinates. Only valid during 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.
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 EndPickDraw | ( | ) |
Restore drawing to original state. Only valid during mouse callbacks.
bool IsPickDraw | ( | ) | const |
Returns true if pick drawing is active.
Start an interaction update on a parameter. At the end of interaction a single undo event will be logged.
in_param | The parameter to update. |
in_time | Time defaults to the current frame if in_time is set with DBL_MAX . |
Update value of parameter during interaction. At the end of interaction a single undo event will be logged.
in_param | The parameter to set. |
in_value | New value for parameter. |
Stop updating parameter and log undo event. At the end of interaction a single undo event will be logged.
in_param | The parameter to stop updating. |
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.
in_kine | The kinematic state to update. |
in_time | Time defaults to the current frame if in_time is set with DBL_MAX . |
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.
in_kine | The kinematic state to set. |
in_value | New value for the kinematic state. |
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.
in_kine | The kinematic state to stop updating. |
Start an interaction update on a list of objects or components. At the end of interaction a single undo event will be logged.
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 . |
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.
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. |
Stop updating objects or components and log an undo event. At the end of interaction a single undo event will be logged.
in_objects | List of objects or components to update. |
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.
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. |
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.
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. |
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.
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: |
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) |
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.
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. |
Load an image from a file.
in_filename | Filename of image to load. |
in_relativePath | If true in_filename is relative to plugin location. |