## 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: siFileTypeAction siFileTypeCustom siFileTypedotXSI siFileTypeIGES siFileTypeMatLib siFileTypeMixer siFileTypeModel
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: siFileTypeAction siFileTypeCustom siFileTypedotXSI siFileTypeIGES siFileTypeMatLib siFileTypeMixer siFileTypeModel
| 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: siRenderSequence siRenderFramePreview siRenderExportArchive
| 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: siRenderFieldNone siRenderFieldOdd siRenderFieldEven
| RenderError | A siRenderErrorType value that specifies the type of render error: siRenderNoError siRenderAbort siRenderFailure 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: siSourceDragAction siSourceDropAction
| 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: siDragOverAction siDropAction siDragEnterAction siDragLeaveAction
| 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: siDragModifierLButton siDragModifierRButton siDragModifierShift siDragModifierCtrl siDragModifierMButton siDragModifierAlt
| 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: siDropEffectCopy siDropEffectMove siDropEffectLink
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: siAddedToSelection if one or more objects were added to the selection siRemovedFromSelection if one or more objects were removed from the selection.
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: siSourcePathImageSource siSourcePathWritableImageSource siSourcePathModelSource
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

- Custom Display (View) Callbacks