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

    // C#
    public class <event_name>
    {
       public bool OnEvent( Context in_ctxt )
       {
           ...
       }
    }

    // C++
    CStatus <event_name>_OnEvent( CRef& in_context )
    {
       ...
    }

    // JScript
    function <event_name>_OnEvent( in_context )
    {
       ...
    }

    # Python
    def <event_name>_OnEvent( in_context )
       ...

    ' VBScript
    Function <event_name>_OnEvent( in_context )
       ...
    End Function

    # PerlScript
    sub <event_name>_OnEvent
    {
       my $in_context = shift;
    }

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

Parameters

Parameter | Language | Type | Description
in_context | Scripting | 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 de-activated (false).
siOnBeginFileExport siOnEndFileExport | Input | The objects being exported: • Model for siFileTypeModel • XSICollection for siFileTypeDotXSI and siFileTypeIges file types • Library for siFileTypeMatLib • Mixer for siFileTypeMixer
FileName | The full path name of the exported file.
FileType | An siFileType value that specifies the type of file being exported. Possible values are: • siFileTypeModel • siFileTypeDotXSI • siFileTypeIges • siFileTypeMatLib • siFileTypeMixer
siOnBeginFileImport siOnEndFileImport | FileName | The full path name of the file to import.
FileType | An siFileType value that specifies the of file being imported. Possible values are: • siFileTypeModel • siFileTypeDotXSI • siFileTypeIges • siFileTypeMatLib • siFileTypeMixer
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) and .xsi (siFileTypedotXSI) files.
Name | The name of the reference model created during the import (this field will be blank for dotXSI imported models).
siOnBeginFrame siOnEndFrame siOnBeginSequence siOnEndSequence | RenderType | A siRenderingType value that specifies the type of render operation being performed: • siRenderSequence • siRenderFramePreview • siRenderExportArchive
FileName | Name of the output file for the current frame or a list of names if multiple Framebuffers are being rendered. The file name given is 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
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.
siOnChangeProject | NewProjectPath | The newly activated project path.
OldProjectPath | The path of the previous active project.
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.
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 (for siOnKeyUp only) | 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 in seconds.
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.

Example

    // 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;

    XSIPLUGINCALLBACK CStatus 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;
    }

    XSIPLUGINCALLBACK CStatus 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.

    XSIPLUGINCALLBACK CStatus 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

• Event Callbacks

Autodesk Softimage v7.5