This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
TfNotice Class Reference

The base class for objects used to notify interested parties (listeners) when events have occurred. More...

#include <notice.h>

+ Inheritance diagram for TfNotice:

Classes

class  Block
 Blocks sending of all notices in current thread. More...
 
class  Key
 Handle-object returned by TfNotice::Register(). More...
 
class  Probe
 Probe interface class which may be implemented and then registered via InsertProbe to introspect about notices as they are sent and delivered. More...
 

Public Types

typedef TfWeakPtr< ProbeWeakProbePtr
 
typedef std::vector< KeyKeys
 A TfNotice::Key container.
 

Public Member Functions

TF_API size_t Send () const
 Deliver the notice to interested listeners, returning the number of interested listeners.
 
template<typename SenderPtr >
size_t Send (SenderPtr const &s) const
 Deliver the notice to interested listeners, returning the number of interested listeners.
 
TF_API size_t SendWithWeakBase (const TfWeakBase *senderWeakBase, const void *senderUniqueId, const std::type_info &type) const
 Variant of Send() that takes a specific sender in the form of a TfWeakBase pointer and a typeid.
 

Static Public Member Functions

static TF_API void InsertProbe (const WeakProbePtr &probe)
 Register a probe that will be invoked when notices are sent and delivered.
 
static TF_API void RemoveProbe (const WeakProbePtr &probe)
 Remove a probe that was previously registered with InsertProbe.
 
template<class LPtr , class MethodPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method)
 Register a listener as being interested in a TfNotice.
 
template<class LPtr , class MethodPtr , class SenderPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method, SenderPtr const &sender)
 
template<class LPtr , class MethodPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method, const TfType &noticeType, const TfAnyWeakPtr &sender)
 
static TF_API bool Revoke (TfNotice::Key &key)
 Revoke interest by a listener.
 
static TF_API void Revoke (TfNotice::Keys *keys)
 Revoke interest by listeners.
 

Detailed Description

The base class for objects used to notify interested parties (listeners) when events have occurred.

The TfNotice class also serves as a container for various dispatching routines such as Register() and Send().

See The TfNotice Notification System in the C++ API reference for a detailed description of the notification system.

Python Example: Registering For and Sending

Notices The following code provides examples of how to set up a Notice listener connection (represented in Python by the Listener class), including creating and sending notices, registering to receive notices, and breaking a listener connection.

# To create a new notice type:
class APythonClass(Tf.Notice):
'''TfNotice sent when APythonClass does something of interest.'''
pass
Tf.Type.Define(APythonClass)
# An interested listener can register to receive notices from all
# senders, or from a particular type of sender.
# To send a notice to all registered listeners:;
APythonClass().SendGlobally()
# To send a notice to listeners who register with a specific sender:
APythonClass().Send(self)
# To register for the notice from any sender:
my_listener = Tf.Notice.RegisterGlobally(APythonClass, self._HandleNotice)
# To register for the notice from a specific sender
my_listener = Tf.Notice.Register(APythonClass, self._HandleNotice, sender)
def _HandleNotice(self, notice, sender):
'''callback function for handling a notice'''
# do something when the notice arrives
# To revoke interest in a notice
my_listener.Revoke()

For more on using notices in Python, see the Editor With Notices tutorial.

Definition at line 76 of file notice.h.

Member Typedef Documentation

◆ Keys

typedef std::vector<Key> Keys

A TfNotice::Key container.

Many listeners listen for several notices and must revoke interest for those several notices at once. These listeners can put all of the keys into a TfNotice::Keys then call Revoke() on it.

Definition at line 272 of file notice.h.

◆ WeakProbePtr

Definition at line 196 of file notice.h.

Member Function Documentation

◆ InsertProbe()

static TF_API void InsertProbe ( const WeakProbePtr probe)
static

Register a probe that will be invoked when notices are sent and delivered.


See also
TfNotice::Probe

◆ Register() [1/3]

static TfNotice::Key Register ( LPtr const &  listener,
MethodPtr  method 
)
inlinestatic

Register a listener as being interested in a TfNotice.

Registration of interest in a notice class N automatically registers interest in all classes derived from N. When a notice of appropriate type is received, the listening object's member-function method is called with the notice.

Supports several forms of registration.

  • Listening for a notice from a particular sender.
// Listener does not receive sender.
void Listener::_HandleNotice(SomeNotice const &notice) [const];
Register(listenerPtr, &Listener::_HandleNotice, senderPtr);
// Listener receives sender.
void Listener::_HandleNoticeSender(SomeNotice const &notice,
SenderPtr const &sender) [const];
Register(listenerPtr, &Listener::_HandleNoticeSender, senderPtr);
static TfNotice::Key Register(LPtr const &listener, MethodPtr method)
Register a listener as being interested in a TfNotice.
Definition: notice.h:344
  • Listening for a notice globally. Prefer listening to a notice from a particular sender whenever possible (as above).
void Listener::_HandleGlobalNotice(SomeNotice const &notice) [const];
Register(listenerPtr, &Listener::_HandleGlobalNotice);
  • Listening for a notice dynamically, with a type that is unknown at compile-time. This facility is used for some internal mechanisms, such as bridging notice delivery into Python, and is not meant for public consumption.
void Listener::_HandleGenericNotice(TfNotice const &notice,
TfType const &noticeType,
TfWeakBase *sender,
void const *senderUniqueId,
std::type_info const &senderType)
[const];
Register(listenerPtr,
&Listener::_HandleGenericNotice, noticeType, senderPtr);
The base class for objects used to notify interested parties (listeners) when events have occurred.
Definition: notice.h:76
TfType represents a dynamic runtime type.
Definition: type.h:48
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:124

The listener being registered must be pointed to by a TfWeakPtrFacade, like a TfWeakPtr or another TfWeakPtrFacade-based Handle. The sender being registered for (if any) must also be pointed to by a TfWeakPtrFacade.

Note that the notification center only holds onto the listening object via a TfWeakPtr. That is, it does not influence the lifetime of that object.

To reverse the registration, call Key::Revoke() on the Key object returned by this call.

Definition at line 344 of file notice.h.

◆ Register() [2/3]

static TfNotice::Key Register ( LPtr const &  listener,
MethodPtr  method,
const TfType noticeType,
const TfAnyWeakPtr sender 
)
inlinestatic

Definition at line 356 of file notice.h.

◆ Register() [3/3]

static TfNotice::Key Register ( LPtr const &  listener,
MethodPtr  method,
SenderPtr const &  sender 
)
inlinestatic

Definition at line 350 of file notice.h.

◆ RemoveProbe()

static TF_API void RemoveProbe ( const WeakProbePtr probe)
static

Remove a probe that was previously registered with InsertProbe.

See also
TfNotice::Probe

◆ Revoke() [1/2]

static TF_API bool Revoke ( TfNotice::Key key)
static

Revoke interest by a listener.

This revokes interest by the listener for the particular notice type and call-back method for which this key was created.

Revoke will return a bool value indicating whether or not the key was successfully revoked. Subsequent calls to Revoke with the same key will return false.

◆ Revoke() [2/2]

static TF_API void Revoke ( TfNotice::Keys keys)
static

Revoke interest by listeners.

This revokes interest by the listeners for the particular notice types and call-back methods for which the keys were created. It then clears the keys container.

◆ Send() [1/2]

TF_API size_t Send ( ) const

Deliver the notice to interested listeners, returning the number of interested listeners.


For most clients it is recommended to use the Send(sender) version of Send() rather than this one. Clients that use this form of Send will prevent listeners from being able to register to receive notices based on the sender of the notice.

ONLY listeners that registered globally will get the notice.

Listeners are invoked synchronously and in arbitrary order. The value returned is the total number of times the notice was sent to listeners. Note that a listener is called in the thread in which Send() is called and not necessarily in the thread that Register() was called in.

◆ Send() [2/2]

size_t Send ( SenderPtr const &  s) const

Deliver the notice to interested listeners, returning the number of interested listeners.

This is the recommended form of Send. It takes the sender as an argument.

Listeners that registered for the given sender AND listeners that registered globally will get the notice.

Listeners are invoked synchronously and in arbitrary order. The value returned is the total number of times the notice was sent to listeners. Note that a listener is called in the thread in which Send() is called and not necessarily in the thread that Register() was called in.

Definition at line 767 of file notice.h.

◆ SendWithWeakBase()

TF_API size_t SendWithWeakBase ( const TfWeakBase senderWeakBase,
const void *  senderUniqueId,
const std::type_info &  type 
) const

Variant of Send() that takes a specific sender in the form of a TfWeakBase pointer and a typeid.

This version is used by senders who don't have static knowledge of sender's type, but have access to its weak base pointer and its typeid.


The documentation for this class was generated from the following file: