Hive Events¶
Hive sends an event whenever a rig or component is created, renamed or deleted, when a build finishes or fails, and when the configuration changes. Any tool can subscribe to these events, once, and hear about every rig, no matter if the change was made by the Hive Artist UI, a script, a build script or another tool.
Use events instead of polling the scene, or wiring your own code into Hive.
For code examples see Examples.
Note
Events only describe changes made through Hive. An undo, deleting a rig node with Maya directly, or opening a scene doesn’t send events.
Quick Start¶
Everything is available from the Hive api.
from zoo.libs.hive import api
def onEvent(event):
if event.eventType == api.HiveEventType.RIG_RENAMED:
print("Renamed {} to {}".format(event.oldValue, event.newValue))
api.subscribe(onEvent)
# ... later
api.unsubscribe(onEvent)
Subscribe to the events you need by passing their types.
api.subscribe(onEvent, eventTypes=(api.HiveEventType.RIG_DELETING, api.HiveEventType.RIG_DELETED))
A subscription is for all rigs, the ones in the scene now and the ones created later. Subscribing the same callable twice with the same event types does nothing, and unsubscribing a callable which isn’t subscribed is ignored.
The events live on a single dispatcher shared by all rigs, api.Configuration.events(), which
is where api.subscribe() and api.unsubscribe() send your callable.
The Events¶
Every event type is a member of api.HiveEventType, which is an IntEnum.
Event |
Sent when |
Useful event attributes |
|---|---|---|
|
A new rig is created in the scene. Not sent when an existing rig is loaded. |
|
|
Before a rig is deleted, nothing has been touched yet. |
|
|
A rig has been deleted. |
|
|
A rig delete raised an error after |
|
|
A rig was renamed. |
|
|
A component is added to a rig, this includes duplicating, mirroring and loading a template. |
|
|
Before a component is deleted, nothing has been touched yet. |
|
|
A component has been deleted. |
|
|
A component delete raised an error after |
|
|
A component’s name or side changed. |
|
|
A build or delete stage finished successfully, for example building the guides or deleting the rig layer. |
|
|
A build or delete stage failed or was cancelled. |
|
|
A configuration value really changed, see below. |
|
|
The component, template, build script and other registries were reloaded. |
The Event Object¶
Every listener receives one api.HiveEvent. It is read only, so a listener can’t change what the
listeners after it see. Attributes which don’t apply to an event are None, or an empty string for
rigName.
Attribute |
Description |
|---|---|
|
The |
|
The |
|
The name of the rig. Always available, also after the rig is deleted. |
|
The |
|
The |
|
The changed setting for |
|
The build stage, one of the |
|
The exception and its formatted traceback for the failure events. |
|
|
|
The |
Warning
rig and component wrap Maya nodes. Use them inside the callback, but don’t store them. After a delete
they are no longer valid, store rigName or componentToken instead.
Order And Guarantees¶
Delete events¶
Every *_DELETING event is followed by exactly one *_DELETED or *_DELETE_FAILED event, so a
tool which starts something on *_DELETING can always finish it.
Deleting a rig with one component sends:
RIG_DELETINGCOMPONENT_DELETINGCOMPONENT_DELETEDRIG_DELETED
The *_DELETING events are sent before anything is deleted. The rig and component are fully valid, which
makes them the place to clean up, save a backup or drop a reference to a node before it goes away. A listener can’t
cancel the delete.
When deleting a whole rig, a component which fails to delete is logged and skipped by Hive, the rig delete carries
on. In that case you get COMPONENT_DELETING, COMPONENT_DELETE_FAILED and the rig still ends with
RIG_DELETED. Deleting a single component raises the error after sending COMPONENT_DELETE_FAILED.
Failure events¶
BUILD_FAILED, COMPONENT_DELETE_FAILED and RIG_DELETE_FAILED are sent just before the error
reaches the caller. Hive raises the same exception it always did, an event listener can’t swallow or replace it.
A failure event describes a scene which may be half changed. Check exists() and refresh from the scene
instead of assuming the operation did or didn’t happen.
Every build or delete stage ends with exactly one of BUILD_STATE_CHANGED or BUILD_FAILED. A cancel is a
BUILD_FAILED with cancelled=True.
Configuration events¶
CONFIGURATION_CHANGED is only sent when a value really changes, setting the same value again
doesn’t send it. Hive applies the saved configuration on every build, this is why a build doesn’t send a
burst of events.
If key is None the change isn’t a single setting, for example the saved rig configuration changed or the
whole configuration was reloaded.
Nothing is sent while a api.Configuration is created.
Holding Back Events¶
Scripts which do a lot in one go can hold the events back until they are done. Listeners then only see the scene once it is consistent.
with api.Configuration.events().blocked():
rig.createComponent("fkchain", "spine", "M")
rig.createComponent("fkchain", "arm", "L")
# the two COMPONENT_ADDED events are sent here
Inside the block:
The success events are held and sent when the block exits, even if the code in the block raises.
BUILD_STATE_CHANGED,CONFIGURATION_CHANGEDandREGISTRIES_RELOADEDare de-duplicated. Only the last of a repeated event is sent, in the position of the first.The
*_DELETINGand all the failure events are never held back. A pre delete event that arrives after the delete is useless, and a failure must not be reordered.Blocks nest, the events are sent when the outermost block exits.
It only affects the thread it is used on.
Hive already does this for duplicating and mirroring components and for loading a template.
Writing Listeners¶
Events are synchronous¶
Your callback runs inside the Hive operation, on the thread which made the change, before the operation returns. Keep it short. A slow listener slows down the build, delete or rename which caused it. Listeners slower than 50 milliseconds are logged at debug level.
Don’t rebuild a whole UI from a callback. Queue the work, for example with a QTimer.singleShot(0, ...),
and do it once the operation is finished. The Hive Artist UI queues its refreshes this way.
Errors in a listener¶
If your callback raises, Hive logs the error and carries on with the next listener. A broken listener never fails or leaves half finished a build, a delete or a rename.
Listeners which change rigs¶
A listener can change a rig, which sends more events. Events nested deeper than 8 levels are dropped with an error in the log, this stops a listener which triggers itself.
Lifetime of a subscription¶
Bound methods, like
self._onEvent, are held with a weak reference. The subscription ends when the object is garbage collected, a closed window doesn’t stay alive because of it.Plain functions, lambdas and builtin methods are held strongly. Unsubscribe them when done.
Pass
weak=Falsetoapi.subscribe()to hold a bound method strongly.You can subscribe and unsubscribe from inside a callback. The listeners for an event are fixed when it is sent.
Do¶
Filter with
eventTypesso your callback only runs for what it needs.Read what you need from the event and store
rigNameandcomponentToken.Handle
*_DELETE_FAILEDif you start something on*_DELETING.Keep the logic in a function of the event so it can be tested, see the testing example.
Don’t¶
Store
event.rigorevent.component.Do slow work, or open dialogs, in the callback.
Rely on getting events for undo, raw Maya changes or opening a scene.
Events In Qt¶
For a UI, turn the events into Qt signals. Hive sends the event on the thread which made the change,
a QObject living on the GUI thread has Qt queue the signal to its slots when that is another thread. Send names
and tokens through the signal, not the live rig or component.
See the Qt example.
The Hive Artist UI does this for you. HiveUICore.hiveEvents is a HiveEventBridge which subscribes once
and has a Qt signal for each event, for example rigCreated(rigName), rigRenamed(oldName, newName),
componentDeleting(rigName, componentToken) and buildFailed(rigName, stage, message, cancelled).
Its hiveEvent signal carries the raw api.HiveEvent and is always emitted before the specific signals.
from zoo.apps.hiveartistui import uiinterface
core = uiinterface.instance().core()
core.hiveEvents.rigRenamed.connect(lambda oldName, newName: print(oldName, newName))
Note
HiveUICore.rigAdded, rigRenamed, rigDeleted and rigsChanged no longer exist. Use
core.hiveEvents.rigCreated, rigRenamed and rigDeleted.