notify (lx_notify.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search
There are security restrictions on this page


Notification System

The notification system is a high-level mechanism for reusing common named event handlers. The system was mainly designed for the command system, allowing the attribute system to be notified by commands that values and other attributes need to be updated.

Notification Service

The notification service is used to manage different notifiers, such as adding new notifiers or walking the notifier list.

(1) SDK: Declarations
 #define LXu_NOTIFYSYSSERVICE    "4A3B31B0-A8F8-430A-9611-9D30E51CBBBA"

Requesit ScriptQuery() method.

(2) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 ScriptQuery) (
         LXtObjectID              self,
         void                   **ppvObj);

A new notifier can be instanced with this function. The plug-in class name and argument string are provided. If the notifier with these arguments already exists, that notifier is used instead.

(3) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 Spawn) (
         LXtObjectID              self,
         const char              *name,
         const char              *args,
         void                   **ppvObj);

These functions can be used to walk the list of instanced notifiers. As usual, the client must release any objects returned by ByIndex(), NameByIndex() and Lookup().

(4) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 Count) (
         LXtObjectID              self,
         unsigned int            *count);

(5) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 ByIndex) (
         LXtObjectID              self,
         unsigned int             index,
         void                   **ppvObj);

(6) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 NameByIndex) (
         LXtObjectID              self,
         unsigned int             index,
         const char             **name);

Notifiers that have been instanced can be looked up with this function.

(7) SDK: ILxNotifySysService interface
         LXxMETHOD(  LxResult,
 Lookup) (
         LXtObjectID              self,
         const char              *name,
         const char              *args,
         void                   **ppvObj);

(8) User Service Class: NotifySysService method

Empty notifysys service Python user class.

(9) PY: NotifySysService method
 pass

Common Notifiers

There are some very common types of events for which notifiers can be created. These are listed here just for a central place to put them.

Most of the specifications support strings to indicate the command notify flags to be sent for the notifier.

(10) Common Flags

Selection

(11) SDK: Declarations
 #define LXsNOTIFIER_SELECT      "select.event"

A "select.event" notifier can be created to trigger on selection events. The format for the arguments is "<type> [mode+flags]". The type is the selection type name, like "vertex" or "item". The optional modes are:

element
Trigger only for changes to element selection, not other selection-related events.
exist
Trigger only if the existence of a selection changes, i.e. when the first element is selected or the last one is dropped.
time
Trigger on time changes.

The argument string "item +v" would send a VALUE change when item selection changes. This is the same as just "item", since VALUE is the default event type. The string "polygon exist+dl" would send DISABLE and LABEL flags depending on there being any polygon selection or not.

Mesh Edits

(12) SDK: Declarations
 #define LXsNOTIFIER_MESHES      "meshes.event"

A "meshes.event" notifier can be created to trigger on mesh edits. The format is "+<edit> [+flags]". The edit flags indicate the type of mesh edit:

(13) Mesh Edit Flags
 +v      Vertex
 +p      Polygon
 +t      Polygon Tags
 +o      Vertex Position
 +h      Hide/Show State
 +f      Polygon Type
 +l      List of Maps
 +u      UV Map Value
 +m      Morph Map Value
 +a      Any Vertex Map Value

The argument string "+vp +vd" would trigger on vertex or polygons edits and would send VALUE and DISABLE notification. The string "+o" would trigger on component level transforms, sending the default VALUE event.

Item Changes

(14) SDK: Declarations
 #define LXsNOTIFIER_ITEM        "item.event"

A "item.event" notifier can be created to trigger on specific item changes. The argument format is "event<[itemType]> [+flags]". The event types are:

add, remove
When items are added and removed.
package
When the packages on an item change.
name
When the name of the item changes.
tag
When any tags on an item change.
chanlist
When the list of user channels, including their type and other attributes, changes for an item.

Here are some examples:

"remove"
Sends a value event on any item being deleted.
"add[clip] +d"
Sends a disable event when any clip item is added.
"tag[group] +ld"
Sends a disable+label event when the tags change on group items.
"chanlist +t"
Sends a data-type event when the user channels change on any item.

Graph Changes

(15) SDK: Declarations
 #define LXsNOTIFIER_GRAPHS      "graphs.event"

A "graphs.event" notifier can be created to trigger on graph edits. The argument format is "<graph> [+flags]". The graph is the graph name.

The string "parent +d" would trigger on parenting changes and send a DISABLE event.

Channel Changes

(16) SDK: Declarations
 #define LXsNOTIFIER_CHANNEL     "channel.event"

A "channel.event" notifier can be created to trigger on changes to a given channel. The argument format is "+flags channel [type]". The flags determine the type of notification, and the channel is the channel name. The optional type is the item type name.

The string "+v enable" would trip a value event on any "enable" channel change.

Action Changes

(17) SDK: Declarations
 #define LXsNOTIFIER_ACTION      "action.event"

An "action.event" notifier can be created to trigger on changes to action parenting. The argument format is "action [+flags]", the name of the action followed by event flags.

Notifier Interface

Individual notifiers support this interface. The notifier itself simply monitors one or more event ports and sends an ILxNotify object as the event data to the client. Some clients might except more interfaces on the object; for example, the attribute system expects notifiers for command states to include an ILxCommandNotify interface so it can know if the command's value, label or datatype needs refreshing.

The ILxNotify object is temporary, and must be released by the ILxNotifier after the event has been sent.

(18) SDK: Declarations
 #define LXu_NOTIFIER    "68725BA4-8EF9-4de4-8792-74CF090799C3"
 #define LXa_NOTIFIER    "notifier"

Get the name of the notifier, which should always be the same as the plug-in's name own name.

(19) SDK: ILxNotifier interface
         LXxMETHOD(  LxResult,
 Name) (
         LXtObjectID              self,
         const char             **name);

These set and get the argument strings. The argument string allows specific events to be filtered through the notifier. For example, a tool notifier might only recognize specific tools, with the tool name provided through the argument string.

(20) SDK: ILxNotifier interface
         LXxMETHOD(  LxResult,
 SetArgs) (
         LXtObjectID              self,
         const char              *args);

(21) SDK: ILxNotifier interface
         LXxMETHOD(  LxResult,
 Args) (
         LXtObjectID              self,
         const char             **args);

A client is added to a notifier through this method. The client object has to implement an interface compatible with this type of modifier.

(22) SDK: ILxNotifier interface
         LXxMETHOD(  LxResult,
 AddClient) (
         LXtObjectID              self,
         LXtObjectID              object);

This removes a client from a notifier that has been previously added.

(23) SDK: ILxNotifier interface
         LXxMETHOD(  LxResult,
 RemoveClient) (
         LXtObjectID              self,
         LXtObjectID              object);

(24) User Class: Notifier method

Empty Notifier Python user class.

(25) PY: Notifier method
 pass