OnEvent
 
 
 

OnEvent


Description

Fired when an event occurs. For example, the OnEvent callback for a siOnBeginNewScene event is fired when a new scene is created with File > New Scene, the Project Manager, or the NewScene command.


Applies To

Events registered with PluginRegistrar.RegisterEvent (for EventInfos). or PluginRegistrar.RegisterTimerEvent (for TimerEvents).


Supported Events

See siEventID for a list of supported events.


Syntax

public class <event_name>
{
        public bool OnEvent( Context in_context )
        {
                ...
        }
}
CStatus <event_name>_OnEvent( CRef& in_context )
{ 
        ... 
}
function <event_name>_OnEvent( in_context )
{ 
        ... 
}
def <event_name>_OnEvent( in_context ):
        ...
Function <event_name>_OnEvent( in_context )
        ...
End Function
sub <event_name>_OnEvent 
{ 
        my $in_context = shift; 
}

<event_name> is the name specified in the call to PluginRegistrar.RegisterEvent, with any spaces converted to underscores. For example, if you register the event with the name "My New Scene", then the callback name is "My_New_Scene_OnEvent".


Parameters

Parameter Language Type Description
in_context Scripting and C# Context Context.Source returns the event PluginItem.
C++ CRef& A reference to the Context object.

Context Attributes

Event Attribute Description
siOnActivate State Boolean value which indicates whether the application has been activated (true) or deactivated (false).
siOnBeginCommand Command Fired when a Command is about to be executed. The event can be used to abort the command execution, modify the command argument values or launch other commands.
siOnEndCommand Command Fired when a Command has been executed. The event can be used to access the command return value or output argument values. Contrary to other event types, this event is always fired when the current command has been aborted by a previous event.
Aborted Boolean denoting whether the command was aborted.
ReturnValue Value returned by the command (if any).
siOnBeginFileExport

siOnEndFileExport
Input The objects being exported:
  • ActionSource for siFileTypeAction
  • Library for siFileTypeMatLib
  • Mixer for siFileTypeMixer
  • Model for siFileTypeModel
  • XSICollection for siFileTypedotXSI and siFileTypeIGES file types
  • Custom objects for siFileTypeCustom
FileName The full path name of the exported file.
FileType An siFileType value that specifies the type of file being exported. Possible values are:
siOnBeginFileImport

siOnEndFileImport
FileName The full path name of the file to import.
FileType An siFileType value that specifies the type of file being imported. Possible values are:
Parent The parent of the model created during import, empty if not specified.
Reference Specifies whether a reference model is being imported. Applies only when importing .emdl (siFileTypeModel), .xsi (siFileTypedotXSI) files and custom files (siFileTypeCustom).
Name The name of the reference model created during the import, if there is one. This field will be blank for dotXSI imported models.
siOnBeginFrame

siOnEndFrame

siOnBeginSequence

siOnEndSequence

siOnRenderAbort
RenderType A siRenderType value that specifies the type of render operation being performed:
FileName List of file names being rendered.

The file names given are resolved from the file name template before being passed to the event handler. The file name template is specified in the individual Framebuffer object of each Pass property.
Frame The frame number of the frame being rendered.
Sequence Frame sequence number. The sequence number represents the number of frames rendered so far. For example, if frames 20 to 30 are being rendered, then the sequence number for frame 20 is 1, and the sequence number for frame 30 is 11.
RenderField A siRenderFieldType value that specifies whether field rendering is enabled:
RenderError A siRenderErrorType value that specifies the type of render error: Available with siOnRenderAbort only.

siOnBeginRenderPass

siOnEndRenderPass
Pass The pass object that is about to get rendered.
Frames An array of frames (times) that are about to get rendered.
siOnBeginPassChange

siOnEndPassChange
SourcePass The name of the old pass to switch from.
TargetPass The name of the new pass to switch to.
siOnBeginSceneOpen

siOnEndSceneOpen

siOnBeginSceneSaveAs

siOnEndSceneSaveAs

siOnBeginSceneSave2

siOnEndSceneSave2
FileName Full path name of the scene.
siOnBeginScrubbing

siOnEndScrubbing
Objects An array of parameter object(s) being set.
Value The parameter value to set. The siOnBeginScrubbing callback receives the current parameter(s) value and the siOnEndScrubbing callback receives the new parameter(s) value.
Frame The frame number at which the parameter(s) is being set.
siOnChangeProject NewProjectPath The newly activated project path.
OldProjectPath The path of the previously active project.
siOnConnectShader

siOnDisconnectShader
Source An output Parameter object on a Shader that is being connected to or disconnected from another shader object's input parameter.
SourceProgID A string id that was used to create the source shader object.
Target An input Parameter object on a Shader that is being connected to or disconnected from another shader object's output parameter.
TargetProgID A string id that was used to create the target shader object.
siOnCreateShader Shader The Shader object that just got created.
ProgID A string id that was used to create the shader.
siOnCreateShaderDef ShaderDef The ShaderDef object that just got created.
ProgID A string id that uniquely identifies the shader definition. For more information, see Instantiating Shader Definitions and the ProgID.
siOnPreDefineShaderDef ShaderDef The ShaderDef object that just got created.
ProgID A string id that uniquely identifies the shader definition. For more information, see Instantiating Shader Definitions and the ProgID.
siOnPreParseShaderDef ShaderDef The ShaderDef object that just got created.
ProgID A string id that uniquely identifies the shader definition. For more information, see Instantiating Shader Definitions and the ProgID.
siOnCustomFileExport Target The objects to be exported.
FileName The full path name of the custom exported file.
FileType An siFileType value that specifies the type of file being exported.
Frame Frame at which to export the specified objects.
UserData Any data that needs to be accessible to the custom converter export event callback. The data is set when exporting with Crosswalk or when exporting attributes with the CacheObjectsIntoFile command. In the context of Crosswalk, the data is set with the name of the current Crosswalk custom property. With CacheObjectsIntoFile, the user data is set with the Attributes argument (i.e. comma-separated list) that is passed in to the command.
siOnCustomFileImport Target The parent of the content imported from the custom file.
FileName The full path name of the custom file to import.
FileType An siFileType value that specifies the type of file being imported.
Frame Frame at which to import the contents of the custom file
UserData Any data that needs to be accessible to the custom converter import event callback. The data is set in the context of Crosswalk with the name of the current Crosswalk custom property.
siOnCustomShaderExport Target The objects to be exported.
Filename The full path name of the custom exported shader.
Displayname Name of the shader definition as it appears in the Preset Manager. For more information, see Populating the Preset Manager.
Category Category in the Preset Manager for the shader definition. For more information, see Populating the Preset Manager.
siOnDragAndDrop DragAndDropAction A siDragAndDropAction value that specifies the type of action that needs to be processed by the callback:
DragSource The source object that is being dragged / dropped.
DragSourceID A siVariantType value that specifies the identification of the source object that is being dragged / dropped. The only supported type is siString for now.
DragSourceSupported Output argument. When the DragAndDropAction parameter is equal to siSourceDragAction, the callback should set this variable to true if the source is supported. False by default.
siOnDragAndDrop2 DragAndDropAction A siDragAndDropAction2 value that specifies the type of action that needs to be processed by the callback:
DragSourceObjects Array of source objects being dragged. Can be an array of Softimage SDK objects or strings.
DragTargetObjects Array of targets over which the source is being dragged, consisting of Softimage SDK objects.
DragTargetView The View in which the drag and drop 2 operation occurs.
DragMouseCoordinates Array (2 elements) representing the mouse coordinates (x,y) in the view client space.
Drag3DCoordinates Array (3 elements) representing the 3D coordinates (x,y,z) with respect to the mouse position. Only valid when the DragTargetView attribute object is a viewport.
DragModifiers siDragModifiers flags specifying the combination of modifiers currently being applied:
DragSourceSupported Output argument. When the DragAndDropAction attribute is equal to siDragOverAction, the callback should set this output attribute to true if the source is supported. false is the value by default for this output attribute. If true is returned under these circumstances, Softimage will launch a siOnDragAndDrop2 event when the source is dropped (with a DragAndDropAction equal to siDropAction. If false is returned, then Softimage will determine internally whether the siDropAction will be called or not. In other words, returning false has the same effect as if no siDragAndDrop2 event was connected. It is only possible to add support for new source / target combination with this output attribute. Note: The event callback code should return a consistent value for this attribute. In other words, if a sources / targets pair yields a true DragSourceSupported return attribute for a siOnDragOverAction call, it should also return true for the siDropAction call.
DragDropEffect Output argument. When the DragSourceSupported attribute is equal to true, this attribute will control the icon used for the mouse pointer. Possible values are:
siOnKeyUp

siOnKeyDown
KeyCode The virtual key code (in decimal) of the key that caused the event.
ShiftMask Specifies the state of the Shift, Alt, and Ctrl modifier keys when the key was pressed.

ShiftMask is an integer value that is the sum of the siKeyboardState values for the modifier keys pressed.

For example, if Shift+Ctrl+Alt is pressed, ShiftMask is equal to siShiftMask + siCtrlMask + siAltMask.
Consumed Specifies whether the event propagates up to Softimage.

If an handler consumes the event, the event is not passed on to Softimage. By default, events are not consumed.

Set this attribute to true with Context.SetAttribute if you don't want Softimage to process the key.
siOnObjectAdded Objects The list of objects that were added.
siOnObjectRemoved ObjectNames The list containing the names of the removed objects.
siOnSelectionChange ChangeType A siSelectionChangeType value that specifies how the selection list changed:
siOnSourcePathChange FileName Full path name of the source file. The event can change this path using Context.SetAttribute on the event's context. If you change the path, the source uses that path instead of the original path. All path validation proceeds as usual though.
SourceType A siSourcePathType value that specifies the type of source:
siOnTimeChange Frame Current frame number.
siOnValueChange Object The object that was changed.
FullName The full name of the object that was changed.
PreviousValue The value of the object before it was changed.
Note This is only available for the Parameter object type.

Return Value

Boolean

True to abort the operation that triggered the event, and False to continue. PerlScript and some versions of Python (prior to 2.2.1) do not define the True and False keywords, so use 1 for True and 0 for False.

CStatus::OK to abort the operation, and CStatus::False (or any other CStatus value except OK) to continue.


Examples

// C++ code generated by the Event Wizard
#include <xsi_application.h>
#include <xsi_context.h>
#include <xsi_pluginregistrar.h>
#include <xsi_status.h>
using namespace XSI; 

SICALLBACK XSILoadPlugin( PluginRegistrar& in_reg )
{
 in_reg.PutAuthor(L"sblair");
 in_reg.PutName(L"NewEvent Plug-in");
 in_reg.PutEmail(L"");
 in_reg.PutURL(L"");
 in_reg.PutVersion(1,0);
 in_reg.RegisterEvent(L"siOnSelectionChangeEvent",siOnSelectionChange);
 //RegistrationInsertionPoint - do not remove this line

 return CStatus::OK;
}

SICALLBACK XSIUnloadPlugin( const PluginRegistrar& in_reg )
{
 CString strPluginName = in_reg.GetName();
 Application().LogMessage(strPluginName + L" has been unloaded.");
 return CStatus::OK;
}

// Callback for the siOnSelectionChangeEvent event.

SICALLBACK siOnSelectionChangeEvent_OnEvent( CRef& in_ctxt )
{
 Context ctxt( in_ctxt );
 Application().LogMessage(L"siOnSelectionChangeEvent_OnEvent called");

 Application().LogMessage(L"ChangeType: " + CString(ctxt.GetAttribute(L"ChangeType")));

//  TODO: Put your code here.

//  Returns CStatus::False if you don't want to abort the event.
 return CStatus::False;
}

See Also