HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TfNotice Class Reference

#include <notice.h>

+ Inheritance diagram for TfNotice:

Classes

class  Block
 
class  Key
 
class  Probe
 

Public Types

typedef TfWeakPtr< ProbeWeakProbePtr
 
typedef std::vector< KeyKeys
 

Public Member Functions

TF_API size_t Send () const
 
template<typename SenderPtr >
size_t Send (SenderPtr const &s) const
 
TF_API size_t SendWithWeakBase (const TfWeakBase *senderWeakBase, const void *senderUniqueId, const std::type_info &type) const
 
virtual TF_API ~TfNotice ()
 

Static Public Member Functions

static void InsertProbe (const WeakProbePtr &probe)
 
static void RemoveProbe (const WeakProbePtr &probe)
 
template<class LPtr , class MethodPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method)
 
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)
 
static TF_API void Revoke (TfNotice::Keys *keys)
 

Friends

class Tf_NoticeRegistry
 
class Tf_PyNotice
 

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 page_tf_Notification 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.

1 # To create a new notice type:
2 class APythonClass(Tf.Notice):
3  '''TfNotice sent when APythonClass does something of interest.'''
4  pass
5 Tf.Type.Define(APythonClass)
6 
7 # An interested listener can register to receive notices from all
8 # senders, or from a particular type of sender.
9 
10 # To send a notice to all registered listeners:;
11 APythonClass().SendGlobally()
12 
13 # To send a notice to listeners who register with a specific sender:
14 APythonClass().Send(self)
15 
16 # To register for the notice from any sender:
17 my_listener = Tf.Notice.RegisterGlobally(APythonClass, self._HandleNotice)
18 
19 # To register for the notice from a specific sender
20 my_listener = Tf.Notice.Register(APythonClass, self._HandleNotice, sender)
21 
22 def _HandleNotice(self, notice, sender):
23  '''callback function for handling a notice'''
24  # do something when the notice arrives
25 
26 # To revoke interest in a notice
27 my_listener.Revoke()

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

Definition at line 93 of file notice.h.

Member Typedef Documentation

typedef std::vector<Key> TfNotice::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 289 of file notice.h.

Definition at line 212 of file notice.h.

Constructor & Destructor Documentation

virtual TF_API TfNotice::~TfNotice ( )
virtual

Member Function Documentation

static void TfNotice::InsertProbe ( const WeakProbePtr probe)
static

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

See Also
TfNotice::Probe
template<class LPtr , class MethodPtr >
static TfNotice::Key TfNotice::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);
  • 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 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 359 of file notice.h.

template<class LPtr , class MethodPtr , class SenderPtr >
static TfNotice::Key TfNotice::Register ( LPtr const listener,
MethodPtr  method,
SenderPtr const sender 
)
inlinestatic

Definition at line 365 of file notice.h.

template<class LPtr , class MethodPtr >
static TfNotice::Key TfNotice::Register ( LPtr const listener,
MethodPtr  method,
const TfType noticeType,
const TfAnyWeakPtr sender 
)
inlinestatic

Definition at line 371 of file notice.h.

static void TfNotice::RemoveProbe ( const WeakProbePtr probe)
static

Remove a probe that was previously registered with InsertProbe.

See Also
TfNotice::Probe
static TF_API bool TfNotice::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.

static TF_API void TfNotice::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.

TF_API size_t TfNotice::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.

template<typename SenderPtr >
size_t TfNotice::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 782 of file notice.h.

TF_API size_t TfNotice::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.

Friends And Related Function Documentation

friend class Tf_NoticeRegistry
friend

Definition at line 773 of file notice.h.

friend class Tf_PyNotice
friend

Definition at line 777 of file notice.h.


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