Public Member Functions | Protected Member Functions | List of all members
BInvoker Class Reference

An object that can be "invoked" to send a message to a BHandler. More...

Inherited by BColumnListView, BControl, BListView, and BMenuItem.

Public Member Functions

 BInvoker ()
 Initializes a BInvoker without a message or target. More...
 
 BInvoker (BMessage *message, const BHandler *handler, const BLooper *looper=NULL)
 Initializes the BInvoker with message and sets the target to either a local handler or as the preferred handler of a local looper where the message is sent when Invoke() is called. More...
 
 BInvoker (BMessage *message, BMessenger target)
 Initializes the BInvoker with message and sets the target messenger where the message is sent when Invoke() is called. More...
 
virtual ~BInvoker ()
 Destructor method, deletes the BMessage object if set. More...
 
uint32 Command () const
 Returns the message's what data member. More...
 
BHandlerHandlerForReply () const
 Returns the previously set reply handler or NULL if not set. More...
 
virtual status_t Invoke (BMessage *message=NULL)
 Sends the message to the invoker's target. More...
 
status_t InvokeNotify (BMessage *message, uint32 kind=B_CONTROL_INVOKED)
 Sends the message to its target, using the notification code specified by kind. More...
 
bool IsTargetLocal () const
 Returns whether or not the invoker and its target belong to the same team. More...
 
BMessageMessage () const
 Returns a pointer to the invoker's message object. More...
 
BMessenger Messenger () const
 Returns the BMessenger object that the invoker uses to send its messages. More...
 
virtual status_t SetHandlerForReply (BHandler *handler)
 Sets the BHandler object responsible for handling reply messages. More...
 
virtual status_t SetMessage (BMessage *message)
 Assigns message to the invoker, deleting any previously assigned message. More...
 
virtual status_t SetTarget (const BHandler *handler, const BLooper *looper=NULL)
 Sets the target to either a local handler or as the preferred handler of a local looper. More...
 
virtual status_t SetTarget (BMessenger messenger)
 Sets the invoker's target to messenger. More...
 
status_t SetTimeout (bigtime_t timeout)
 Sets the timeout to use when sending the message to the target. More...
 
bigtime_t Timeout () const
 Returns the current timeout value. More...
 

Protected Member Functions

void BeginInvokeNotify (uint32 kind=B_CONTROL_INVOKED)
 Implement this method to set up an InvokeNotify() context. More...
 
void EndInvokeNotify ()
 Implement this method to tear down an InvokeNotify() context. More...
 
uint32 InvokeKind (bool *_notify=NULL)
 Returns the kind set by InvokeNotify(). More...
 

Detailed Description

An object that can be "invoked" to send a message to a BHandler.

The designated BHandler of a BInvoker is known as its "target".

BInvoker is most often used as a mix-in class, for example, BControl derives from BInvoker as well as from BView.

See also
Invoke()
SetTarget(const BHandler*, const BLooper*) for details.
Since
BeOS R3

Constructor & Destructor Documentation

◆ BInvoker() [1/3]

BInvoker::BInvoker ( )

Initializes a BInvoker without a message or target.

You must call SetTarget() to set the invoker's target before calling Invoke() for the message to be sent.

You may call SetMessage() to set the message to send when calling Invoke(), alternatively you may pass a BMessage to Invoke() each time you call it.

See also
Invoke()
SetMessage()
SetTarget()
Since
BeOS R3

◆ BInvoker() [2/3]

BInvoker::BInvoker ( BMessage message,
const BHandler handler,
const BLooper looper = NULL 
)

Initializes the BInvoker with message and sets the target to either a local handler or as the preferred handler of a local looper where the message is sent when Invoke() is called.

Note
It is not necessary to specify both the handler and the looper, the unused parameter should be passed in as NULL.
See also
Invoke()
SetTarget(const BHandler*, const BLooper*) for details.
Since
BeOS R3

◆ BInvoker() [3/3]

BInvoker::BInvoker ( BMessage message,
BMessenger  messenger 
)

Initializes the BInvoker with message and sets the target messenger where the message is sent when Invoke() is called.

A BMessenger can target either local or remote objects.

See also
SetMessage() for details.
Since
BeOS R3

◆ ~BInvoker()

BInvoker::~BInvoker ( )
virtual

Destructor method, deletes the BMessage object if set.

Since
BeOS R3

Member Function Documentation

◆ BeginInvokeNotify()

void BInvoker::BeginInvokeNotify ( uint32  kind = B_CONTROL_INVOKED)
protected

Implement this method to set up an InvokeNotify() context.

This is used by derive classes to emulate an InvokeNotify() call inside of Invoke() without breaking binary compatibility.

Since
BeOS R5

◆ Command()

uint32 BInvoker::Command ( ) const

Returns the message's what data member.

Note
If a message has not been assigned to the invoker this method returns 0 instead.
Since
BeOS R3

◆ EndInvokeNotify()

void BInvoker::EndInvokeNotify ( )
protected

Implement this method to tear down an InvokeNotify() context.

Since
BeOS R5

◆ HandlerForReply()

BHandler * BInvoker::HandlerForReply ( ) const

Returns the previously set reply handler or NULL if not set.

Since
BeOS R3

◆ Invoke()

status_t BInvoker::Invoke ( BMessage message = NULL)
virtual

Sends the message to the invoker's target.

If message is NULL the default message is sent instead. You can set the default message using SetMessage or in the constructor.

This method also sends a B_CONTROL_INVOKED notification to handlers which registered themselves using StartWatching

Since
BeOS R3

Reimplemented in BListView, BMenuItem, BPictureButton, BControl, BButton, BColorControl, BCheckBox, BChannelControl, BTextControl, and BRadioButton.

◆ InvokeKind()

uint32 BInvoker::InvokeKind ( bool *  _notify = NULL)
protected

Returns the kind set by InvokeNotify().

Derived classes should implement this method and call it from within Invoke() to determine what kind was specified when InvokeNotify() was called.

If you care whether Invoke() or InvokeNotify() was originally called, you can use a bool pointer and set its value to true if InvokeNotify() was called, or false if Invoke() was called. This lets you fetch the InvokeNotify() arguments from Invoke() without breaking binary compatibility with older applications.

Since
BeOS R5

◆ InvokeNotify()

status_t BInvoker::InvokeNotify ( BMessage message,
uint32  kind = B_CONTROL_INVOKED 
)

Sends the message to its target, using the notification code specified by kind.

If message is NULL, no message is sent to the target, but any watchers of the invoker's handler will receive their expected notifications. By default, kind is B_CONTROL_INVOKED, the same as sent by Invoke().

BInvoker does not send the notification itself, it is up to subclasses to do that as needed.

See also
BLooper::StartWatching()
BLooper::SendNotices()
BHandler::NoticeChange()
Since
BeOS R5

◆ IsTargetLocal()

bool BInvoker::IsTargetLocal ( ) const

Returns whether or not the invoker and its target belong to the same team.

Returns
true if the invoker and its target are in the same team, false if they reside in separate address spaces.
Since
BeOS R3

◆ Message()

BMessage * BInvoker::Message ( ) const

Returns a pointer to the invoker's message object.

Note
If a message has not been assigned to the invoker this method returns NULL instead.
Since
BeOS R3

◆ Messenger()

BMessenger BInvoker::Messenger ( ) const

Returns the BMessenger object that the invoker uses to send its messages.

If a target hasn't been set yet, the returned BMessenger object will be invalid.

See also
BMessenger::IsValid()
Since
BeOS R3

◆ SetHandlerForReply()

status_t BInvoker::SetHandlerForReply ( BHandler replyHandler)
virtual

Sets the BHandler object responsible for handling reply messages.

When Invoke() is called, the replyHandler is passed to the messenger's SendMessage() method, as follows:

messenger->SendMessage(message, replyHandler);

By default, the handler for replies is NULL, consequently all reply messages will be sent to the BApplication instead.

Returns
Always returns B_OK.
Since
BeOS R3

◆ SetMessage()

status_t BInvoker::SetMessage ( BMessage message)
virtual

Assigns message to the invoker, deleting any previously assigned message.

You may pass NULL into message to delete the current message without replacing it.

When Invoke() is called with a NULL message parameter, a copy of the passed in message is sent to the target BHandler. BInvoker takes ownership of the BMessage object, so you must not delete it yourself.

Since
BeOS R3

◆ SetTarget() [1/2]

status_t BInvoker::SetTarget ( const BHandler handler,
const BLooper looper = NULL 
)
virtual

Sets the target to either a local handler or as the preferred handler of a local looper.

Note
It is not necessary to specify both the handler and the looper, the unused parameter should be passed in as NULL.

If given only a handler, it must already be attached to a BLooper.

If given only a looper, the message will be sent to its preferred handler (in the case of a BWindow that is the focused view).

Since
BeOS R3

◆ SetTarget() [2/2]

status_t BInvoker::SetTarget ( BMessenger  messenger)
virtual

Sets the invoker's target to messenger.

A BMessenger target can be used to designate a remote handler (living in another team).

Since
BeOS R3

◆ SetTimeout()

status_t BInvoker::SetTimeout ( bigtime_t  timeout)

Sets the timeout to use when sending the message to the target.

By default the timeout is set to B_INFINITE_TIMEOUT. The timeout value is passed into the timeout parameter of BMessenger::SendMessage().

See also
BMessenger::SendMessage(BMessage*, BHandler*, bigtime_t) for details.
Since
BeOS R5

◆ Timeout()

bigtime_t BInvoker::Timeout ( ) const

Returns the current timeout value.

Since
BeOS R5