gir.addEventHandler

Top  Previous  Next

The addEventHandler function allows for a script to register a callback with the event processing core. This allows the script to catch events as they are processed by Girder. This is useful to create advanced event processing flows. Note that the callback is called on the Girder event thread and as such all processing should be kept to a minimum. If any tasks take too long they should be spun onto their own thread.

Definition

handlerId = gir.addEventHandler( eventString, minDevice, maxDevice, eventHandlerCallback )

 

Name

Type

Description

eventstring

string

The eventstring to match against. This is a regular expression.

minDevice

number

The lower bound of the event device number to match

maxDevice

number

The high bound of the event device number to match

eventHandlerCallback

callback function

The function that is called when the event matches the regular expression and device range.

handlerId

number

The id that can be used to unregister event handler

 

Callback Signature

The callback function has the following signature:

 

eventHandlerCallback ( eventString, deviceNumber, keyMod, payloads, captures )

 

Name

Type

Description

eventString

string

The eventstring of the event that just matched the parameters given to addEventHandler

deviceNumber

number

The device number of the plugin that created the event.

keyMod

number (enum)

Indicates whether this was a keydown, repeat or keyup.

payloads

table of strings

A table filled with the payloads that came with this event.

captures

table of strings

If the eventString passed to addEventHandler had captures, this is where they will be passed back to the script.

Examples

Example - Device Manager Events

Below is an example showing how this function can be used to catch all events from the device manager.

 

handlerId = gir.addEventHandler("dm\\..*", 18, 18,

   function ( event, device, keyMod, payloads, captures )      

       print(event, device)        

   end

)

 

The event string is a regular expression. In the example above this is "dm\\..*" part. A quick primer to regular expressions can be found here. Events that this expression will match are dm.toggle.18 or dm.button.32. This example expression is built out of three parts. "dm", "\\." and ".*". The first part matches "dm" only. The second part only matches a dot "." and the last part matches zero or more characters of any kind.

 

Example - All Events

By passing .* as the regular expression we catch all events from the system with event device numbers between 0 and 65000.

 

handlerId, err = gir.addEventHandler( ".*", 0, 65000, function( eventString ,eventDevice, keyMod, payloads, captures )

 

    print("Event: ", eventString, eventDevice, keyMod)

    table.print(payloads)

 

end)

 

if not handlerId then

    print("Add Handler registration failed.", err)

else

    print("Handler registered.")

end

 

Example - PIR-1 Button handling with captures

One useful thing to be able to do is capture the button presses from a PIR-1 and extract the button that was pressed and which PIR-1 triggered it. Potentially to strip the PIR-1 serial from it and resend the event. PIR-1's event looks like this:

 

"A4931313633351612171 button 1"

 

regId, err = gir.addEventHandler( "([a-fA-F0-9]{20}) button (\\d)", 123, 123, function( eventString ,eventDevice, keyMod, payloads, captures )

 

    print("Event: ", eventString, eventDevice, keyMod, #captures)

    table.print(captures)

 if #captures >= 3 then

         print("PIR: ", captures[2], " button: ", captures[3])

 end

 

end)

 

if not regId then

    print("Add Handler registration failed.", err)

else

    print("Handler registered.")

end

 

The main difference with previous examples is the regular expression. It now has two captures. These are the parts between parenthesis. First it's ([a-zA-Z0-9]{20}) and (\\d) . The first part matches any 20 hexadecimal character string. The second part matches any single number. Note that the returned captures includes the whole match as the first capture. Thus the PIR-1 serial is the second capture and the button is the third. (Note Lua's tables are 1 based, not zero as in C or other languages).

 

To read more about regular expression go to the Regular Expression Chapter.

Example - Removing Event Handler

If you need to unregister the handler that is possible. Make sure you stored the handlerId that was returned by gir.addEventHandler and then pass that to gir.removeEventHandler.

 

if handlerId then

    gir.removeEventHandler(handlerId)

    handlerId = nil

end

Related

gir.removeEventHandler

thread.newthread

Availability

Lua