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

RIG_CREATED

A new rig is created in the scene. Not sent when an existing rig is loaded.

rig, rigName

RIG_DELETING

Before a rig is deleted, nothing has been touched yet.

rig, rigName

RIG_DELETED

A rig has been deleted.

rigName, rig is None

RIG_DELETE_FAILED

A rig delete raised an error after RIG_DELETING. The rig may be partly deleted.

rig, rigName, error, traceback

RIG_RENAMED

A rig was renamed.

rig, oldValue, newValue

COMPONENT_ADDED

A component is added to a rig, this includes duplicating, mirroring and loading a template.

rig, component, componentToken

COMPONENT_DELETING

Before a component is deleted, nothing has been touched yet.

rig, component, componentToken

COMPONENT_DELETED

A component has been deleted.

rig, componentToken

COMPONENT_DELETE_FAILED

A component delete raised an error after COMPONENT_DELETING. The component may be partly deleted.

rig, component, componentToken, error, traceback

COMPONENT_RENAMED

A component’s name or side changed.

rig, component, oldValue, newValue (the "name:side" tokens)

BUILD_STATE_CHANGED

A build or delete stage finished successfully, for example building the guides or deleting the rig layer.

rig, stage

BUILD_FAILED

A build or delete stage failed or was cancelled.

rig, stage, componentToken, error, traceback, cancelled, buildContext

CONFIGURATION_CHANGED

A configuration value really changed, see below.

key, oldValue, newValue, rig

REGISTRIES_RELOADED

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

eventType

The api.HiveEventType.

rig

The api.Rig the event is about. None for RIG_DELETED and for events without a rig.

rigName

The name of the rig. Always available, also after the rig is deleted.

component

The api.Component, when there is one.

componentToken

The "name:side" of the component e.g. "spine:M". Also available after the component is deleted.

key, oldValue, newValue

The changed setting for CONFIGURATION_CHANGED, the old and new name for the rename events.

stage

The build stage, one of the constants.*_FUNC_TYPE values. Use api.STAGE_LABELS[stage] for a name.

error, traceback

The exception and its formatted traceback for the failure events.

cancelled

True for a BUILD_FAILED which was a user cancel and not an error.

buildContext

The api.BuildContext of the failed build, with the log up to the failure.

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:

  1. RIG_DELETING

  2. COMPONENT_DELETING

  3. COMPONENT_DELETED

  4. RIG_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_CHANGED and REGISTRIES_RELOADED are de-duplicated. Only the last of a repeated event is sent, in the position of the first.

  • The *_DELETING and 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=False to api.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 eventTypes so your callback only runs for what it needs.

  • Read what you need from the event and store rigName and componentToken.

  • Handle *_DELETE_FAILED if 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.rig or event.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.

Reference

See the events api reference.