OnKeyDown (XSIApplication)

Description

The KeyDown event occurs when the user presses a key. The event does get fired if the window with the focus handles keyboard events. The KeyDown event handler may choose to consume the event or not. If the event is consumed then it will not be passed on to other XSI windows.

By default, the KeyDown event is passed on.

This event is installed using the XSIApplication.Advise method and can be removed using the XSIApplication.Unadvise method, please see these methods for a detailed example of installing and uninstalling events.

The event may be temporarily muted via the EventInfo.Mute property. All installed events can be viewed in the plugin manager dialog's event tab.

NOTE: The prefered and alternative method of installing this is event is as a self-installing plugin. See PluginRegistrar.RegisterEvent method for more details.

Scripting Syntax

    XSIApplication.OnKeyDown ([CustomData], [KeyCode], [ShiftMask], [Consumed])

Parameters

Parameter | Type | Description
CustomData | Variant | Custom data passed to the event handler. This argument is optional; you can specify one when binding an event with XSIApplication.Advise. The data is passed to the event handler whenever the event is fired, an empty value is passed if no custom data is specified.
KeyCode | Long | Specifies the virtual-key code of the key that generated the KeyDown event.
ShiftMask | siKeyboardState | Contains a combination of the following flags specifying the key(s) pressed during the action: siShiftMask, siCtrlMask, siAltMask.
Consumed [out] | Boolean | Specifies whether the event handler has consumed the event or not, in this case the event will not be passed on to XSI. By default the event is not consumed. Note: PythonScript, PerlScript and JScript do not support output arguments. Use the return value to pass the consumed status. PythonScript and PerlScript do not define a Boolean type so pass 1 for True and 0 for False.

Return Value

Boolean (true to consume event)

Examples

1. VBScript Example

    sub XSIApplication_OnKeyDown( data, key, mask, consumed )
       LogMessage "*** XSIApplication_OnKeyDown ***"
       processed = true
       LogMessage data & " : " & key & " : " & mask & " : " & processed
    end sub

2. JScript Example

    function XSIApplication::OnKeyDown( CustomData, KeyCode, ShiftMask, Unused )
    {
       Application.LogMessage( "*** JScript Event - XSIApplication::OnKeyDown ***");
       // your code here
       // return consumed status in return code
       return 0;
    }

3. PerlScript Example

    sub XSIApplication_OnKeyDown
    {
       my ($CustomData, $KeyCode, $ShiftMask, $Unused) = @_;
       $Application->LogMessage( "*** PerlScript Event - XSIApplication_OnKeyDown ***" );
       # your code here
       # return consumed status in return code
       return 0;
    }

4. Python Example

    def XSIApplication_OnKeyDown( CustomData, KeyCode, ShiftMask, Unused ):
       Application.LogMessage( '*** PythonScript Event - XSIApplication_OnKeyDown ***' )
       # your code here
       # return consumed status in return code
       return 0

See Also

XSIApplication.OnKeyUp | PluginRegistrar.RegisterEvent | XSIApplication.Advise | XSIApplication.Unadvise
XSIApplication.EventInfos |  |  |