Callbacks Module

Callbacks system

• Events are registered/de-registered “as needed”, no wasted function calls from the API
• Callbacks can be deferred and the callback condensed when rapidly fired
• Callbacks can be prioritized
• Undo handling for events that could cause an invalid undo queue state (Undo/Redo events)

Basic examples

import mlib.core.callbacks as callbacks

Getting events:

print '\n'.join(callbacks.getEvents())

Adding a callback:

#Define some callback function
def test():
        print 'Event fired!'

#Register it to the event "SelectionChanged"
callbacks.addCallback('SelectionChanged', 'test', test)

Removing a callback:

callbacks.removeCallback('SelectionChanged', 'test')

Registering a new event type:

#Either define a set of register/deregister functions or
#use the helper function to generate some for you
rfunc, dfunc = make_user_event_funcs('myEvent')
callbacks.addEvent('myEvent', rfunc, dfunc)

#Add a test callback for the new event type
callbacks.addCallback('myEvent', 'test', test)

#Post the event to test it out
callbacks.postEvent('myEvent')

mlib.core.callbacks.getEvents()

Get a list of event names that are supported

Returns:Event names Return type:list

mlib.core.callbacks.addCallback(event, owner, function, priority=None, immediate=None)

Add a callback to an event

Parameters:

• event (str) – Event to add callback for
• owner (str) – Name of callback owner (Typically your script or plugin __name__)
• function (function) – Any callable function to execute when the event occurs. Some events also pass data to the callback function.
• priority (int) – (Optional) Callback priority. Callbacks are executed in priority order.
• immediate (bool) – Execute this callback immediately on event occurance. default compresses multiple rapid events and delays until next idle.

mlib.core.callbacks.removeCallback(event, owner)

Remove a callback from an event

Parameters:

• event (str) – Event to remove callback for
• owner (str) – Name of callback owner to remove (See addCallback())

mlib.core.callbacks.getCallbacks(event=None)

Returns a list of all callbacks, sorted by priority

Parameters:event (str or None) – (Optional) event name to filter to Returns:callbacks Return type:list

mlib.core.callbacks.postEvent(event, *args, **kwargs)

Post an event if possible. Arguments are forwarded to postUserEvent/event_handler

Parameters:event (str) – Event to post

mlib.core.callbacks.addEvent(event, register_func, deregister_func, disable_undo=False, allow_deferred=False, deferred_low_priority=False, builtin=False)

Define a new event for the system.

Parameters:

• event (str) – Event name
• register_func (function) – Function to register the event_handler for this event
• deregister_func (function) – Function to de-register the event_handler for this event (Passed the return from register_func if needed)
• disable_undo (bool) – Disable the undo queue when calling callbacks, typically only needed for undo/redo based callbacks
• allow_deferred (bool) – Enable deffered callbacks, best for “rapid” events that do not need return values like SelecitonChanged. Uses evalDeferred.
• deferred_low_priority (bool) – Use “Low priority” when deferring. Useful for extremely spammy events.
• builtin (bool) – Flag as a builtin defined Event (From this callbacks.py module)

mlib.core.callbacks.event_handler(event, *args, **kwargs)

Parameters:

• event – Event being handled
• args – Positional arguments
• kwargs – Keyword arguments

mlib.core.callbacks.queued_event_handler(event, *args, **kwargs)

mlib.core.callbacks.make_user_event_funcs(event)

Generate a set of register/deregister functions for a MUserEventMessage with the given name. This is intended to make simple user events easier to implement.

Parameters:event – Event name to generate functions for Returns:Register Function, Deregister Function Return type:(rfunc, dfunc)

mlib.core.callbacks.add_default_events()

Populate the events list with some of the builtin events

class mlib.core.callbacks.Callback

Callback(event, owner, function, priority, immediate)

class mlib.core.callbacks.Event

Event(name, register_func, deregister_func, disable_undo, allow_deferred, deferred_low_priority, builtin)