BInvoker Class Reference

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

Inherited by BControl, BListView, and BMenuItem.

Public Member Functions
	BInvoker ()
	Initializes a BInvoker without a message or target.
	BInvoker (BMessage *message, BMessenger target)
	Initializes the BInvoker with message and sets the target messenger where the message is sent when Invoke() is called.
	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.
virtual	~BInvoker ()
	Destructor method, deletes the BMessage object if set.
uint32	Command () const
	Returns the message's what data member.
BHandler *	HandlerForReply () const
	Returns the previously set reply handler or NULL if not set.
virtual status_t	Invoke (BMessage *message=NULL)
	Sends the message to the invoker's target.
status_t	InvokeNotify (BMessage *message, uint32 kind=B_CONTROL_INVOKED)
	Sends the message to its target, using the notification code specified by kind.
bool	IsTargetLocal () const
	Returns whether or not the invoker and its target belong to the same team.
BMessage *	Message () const
	Returns a pointer to the invoker's message object.
BMessenger	Messenger () const
	Returns the BMessenger object that the invoker uses to send its messages.
virtual status_t	SetHandlerForReply (BHandler *handler)
	Sets the BHandler object responsible for handling reply messages.
virtual status_t	SetMessage (BMessage *message)
	Assigns message to the invoker, deleting any previously assigned message.
virtual status_t	SetTarget (BMessenger messenger)
	Sets the invoker's target to messenger.
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.
status_t	SetTimeout (bigtime_t timeout)
	Sets the timeout to use when sending the message to the target.
BHandler *	Target (BLooper **_looper=NULL) const
	Invoke BMessenger::Target() on the internal messenger.
bigtime_t	Timeout () const
	Returns the current timeout value.

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

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 BButton, BChannelControl, BCheckBox, BColorControl, BControl, BListView, BMenuItem, BPictureButton, BRadioButton, and BTextControl.

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 ( 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

SetTarget() [2/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

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

Target()

BHandler * BInvoker::Target

(

BLooper **

_looper = NULL

)

const

Invoke BMessenger::Target() on the internal messenger.

See also

BMessenger::Target()

Since

BeOS R3

Timeout()

bigtime_t BInvoker::Timeout

(

)

const

Returns the current timeout value.

Since

BeOS R5