os::Invoker Class Reference

Inheritance diagram for os::Invoker:

Public Member Functions
	Invoker ()
	Default constructor. More...
	Invoker (Message *pcMessage)
	Constructor. More...
	Invoker (Message *pcMessage, const Handler *pcHandler, const Looper *pcLooper=NULL)
	Constructor. More...
	Invoker (Message *pcMessage, const Messenger &cTarget)
	Constructor. More...
virtual	~Invoker ()
	Destructor. More...
virtual status_t	SetMessage (Message *pcMessage)
	Assign a new message to the invoker. More...
Message *	GetMessage () const
	Get the message currently assigned to the invoker. More...
uint32	GetCode () const
	Get the code field from the currently assigned message. More...
virtual bool	Invoked (Message *pcMessage)
	Intercept outgoing messages. More...
virtual void	TargetChanged (const Messenger &cOldTarget)
	Virtual hook called by the system after the target has been changed. More...
virtual void	MessageChanged (const Message &cOldMsg)
	Virtual hook called by the system after the message has been changed. More...
virtual status_t	SetTarget (const Handler *pcHandler, const Looper *pcLooper=NULL)
	Set a new message target. More...
virtual status_t	SetTarget (const Messenger &cMessenger)
	Set a new message target. More...
bool	IsTargetLocal () const
	Check if the target lives in our process. More...
Handler *	GetTarget (Looper **ppcLooper=NULL) const
	Get the current target. More...
Messenger	GetMessenger () const
	Get the messenger used to target messages sendt by the invoker. More...
virtual status_t	SetHandlerForReply (Handler *pcHandler)
	Set a reply target for messages sendt by this messenger. More...
Handler *	GetHandlerForReply () const
	Get the current reply target for replies on messages sendt by the invoker. More...
virtual status_t	Invoke (Message *pcMessage=NULL)
	Send the current message to the current target. More...

Detailed Description

Description:

See Also

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Constructor & Destructor Documentation

Invoker::Invoker

(

)

Description:

The default constructor initialte the invoker to target the application looper but with no message. An message must be assigned with SetMessage() before the invoker can be used.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Invoker::Invoker

(

Message *

pcMsg

)

Description:

Construct a invoker with the specified message that targets the application looper.

Note

The invoker will take ownership over the message and will delete it when another message is assigned or the messenger is deleted. The message must therefor be allocated on the heap with the "new" operator and must not be deleted by the application.

Parameters

pcMsg

The message to be sendt when invoked. The invoker takes ownership over the message.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Invoker::Invoker	(	Message *	pcMsg,
		const Handler *	pcHandler,
		const Looper *	pcLooper = NULL
	)

Description:

Construct a invoker with a message and a target. When invoked the pcMsg will be sendt to the target specified by pcHandler and/or pcLooper.

Look at os::Messenger for a more detailed description on how the to target a looper or handler. The invoker will pass these parameters to an internal os::Messenger that is later used to send messages so the targeting rules of os::Messenger goes for the os::Invoker aswell.

Note

The invoker will take ownership over the message and will delete it when another message is assigned or the messenger is deleted. The message must therefor be allocated on the heap with the "new" operator and must not be deleted by the application.

Parameters

pcMsg	The message to be sendt when invoked. The invoker takes ownership over the message.
pcHandler	The handler that should receive messages sendt by this invoker or NULL if a looper is to be destined.
pcLooper	If pcHandler is NULL messages will be sendt to this looper without a specific target.

See Also

os::Messenger

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Invoker::Invoker	(	Message *	pcMsg,
		const Messenger &	cTarget
	)

Description:

Construct a invoker with a message and a target. When invoked the pcMsg will be sendt to the target specified by cTarget

Note

The invoker will take ownership over the message and will delete it when another message is assigned or the messenger is deleted. The message must therefor be allocated on the heap with the "new" operator and must not be deleted by the application.

Parameters

pcMsg	The message to be sendt when invoked. The invoker takes ownership over the message.
cTarget	A messenger specifying this invokers target

See Also

os::Messenger

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Invoker::~Invoker ( )

virtual

Description:

Free any resources allocated by the invoker and delete the user supplied message object. Since the message object is deleted here it is of course very important that you don't keep any external references to it after the invoker has been deleted. Neither should you ever delete a message that have been given to an invoker.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Member Function Documentation

uint32 Invoker::GetCode

(

void

)

const

Description:

Short for GetMessage()->GetCode(). If not message is assigned 0 will be returned.

Note

Since 0 is a valid value for a message-code it might be necessarry to check if the message exists with GetMessage() before calling this member.

Returns

The message-code of the currently assigned message or 0 if not message is currently assigned.

See Also

GetMessage(), SetMessage()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Message::GetCode().

Handler * Invoker::GetHandlerForReply

(

)

const

Description:

Get the current reply target for replies on messages sendt by the invoker. This is the handler assigned with SetHandlerForReply().

Returns

Pointer to the current reply target.

Error codes:

See Also

SetHandlerForReply()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Message * Invoker::GetMessage

(

)

const

Description:

Get the message currently assigned to the invoker through the constructor or the SetMessage() member.

Note

The message will be deleted if SetMessage() is called or if the messenger is deleted so make sure to not reference the message after any such event.

Returns

Pointer to the currently assigned message or NULL if no message has been assigned.

See Also

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::TabView::DeleteTab(), os::Menu::FindItem(), os::IconView::GetInvokeMsg(), os::Alert::HandleMessage(), and os::TabView::SetSelection().

Messenger Invoker::GetMessenger

(

void

)

const

Description:

Get the messenger used to target messages sendt by the invoker.

Returns

A copy of the internal messenger used to target messages from the invoker.

See Also

SetTarget(), Invoke()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Control::AttachedToWindow().

Handler * Invoker::GetTarget

(

Looper **

ppcLooper = NULL

)

const

Description:

Get the current looper/handler targeted by this invoker. Look at os::Messenger::GetTarget() for a more detailed description.

Parameters

ppcLooper

If non-NULL a pointer to the looper owning the target will be written here.

Returns

Pointer to the destined os::Handler (this might be a looper if no specific handler is targeted) or NULL if the messenger is invalid or targets a handled/looper in a remote process.

See Also

SetTarget(), os::Messenger::GetTarget(), os::Messenger

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Messenger::GetTarget().

status_t Invoker::Invoke ( Message *  pcMsg = NULL )

virtual

Description:

Call Invoke() to pass the currently assigned message (or optionally an "external" message passed to Invoke()) to the current target.

This is the member that is called by GUI controls and such to notify it's target about a change.

The message to be passed (whether it is supplied through the pcMsg parameter or the internal message) will be copyed and a pointer to the invoker is added under the name "source". Then the virtual member Invoked() is called to allow classes that overload os::Invoker to add date to the message or even cancel the operation before it is sendt to the current target.

Note

The receiver of the message can find a pointer to the invoker that sendt the message by calling FindPointer( "source", &pPtr ) on the incoming message.

Since os::Invoker often are mixed into other classe with multiple inheritance greate care must be taken when casting the void pointer from os::Message::FindPointer() to the real object. The most common usage of invoker is through the os::Control class which inherits from both os::View and os::Invoker. If you receive a message from for example a os::Button (which again inherits from os::Control) you can not cast the pointer directly to os::Button but you must let the compiler know that the pointer is really an os::Invoker pointer first.

The following example will put a pointer to the os::Button that sendt the message into pcButton if the message was sendt from a os::Button. If the source was not an os::Button the dynamic_cast will fail and pcButton will be NULL.

void* pSource = NULL;
pcMsg->FindPointer( "source", &pSource );
os::Button* pcButton = dynamic_cast<os::Button*>(static_cast<os::Invoker*>(pSource));

Note

If no message is currently assigned and pcMsg is NULL, or if no valid target has been specifed no message will be sendt.

Parameters

pcMsg

An optional message to be sendt instead of the internal message. The message will be copyed and you retain ownership over it. If this parameter is NULL the internal message will be used. It is often better to overload Invoked() and do per-message modifications there than to supply "custom" messages.

Returns

On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno. A message that is canceled by Invoked() are not considered a failure.

See Also

Invoked(), SetTarget(), SetMessage(), os::Invoker, os::Message

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Message::AddPointer(), Invoked(), and os::Messenger::SendMessage().

Referenced by os::TreeView::Collapse(), os::TextEdit::CommitEvents(), os::TabView::DeleteTab(), os::IconDirectoryView::DirChanged(), os::TreeView::Expand(), os::DropdownMenu::HandleMessage(), os::Alert::HandleMessage(), os::IconView::Invoked(), os::ListView::Invoked(), os::Menu::KeyDown(), os::ScrollBar::MouseUp(), os::Slider::MouseUp(), os::Menu::MouseUp(), os::IconView::SelectionChanged(), os::ListView::SelectionChanged(), os::DropdownMenu::SetSelection(), os::TabView::SetSelection(), os::Control::SetValue(), and os::TextView::SetValue().

bool Invoker::Invoked ( Message *  pcMessage )

virtual

Description:

This member is called from Invoke() just before a message is sendt to the target.

This allow classes that inherits from os::Invoker to add data to or otherwhice modify the message before it is sendt. The message can also be canceled entirely by returning false from this member.

The message passed to Invoked() is a copy of the internal message or the message passed to Invoke() (if any) so any changes made here will not affect the internal message or the message passed to Invoke(). When this method returns the message will imidiatly be sendt to the target and then discarded (unless false is returned in which case the message is simply discarded).

The default implementation of this member does nothing and return true.

Parameters

pcMessage

Pointer to the message that is about to be sendt. You can do any modification you like to this message (but never delete it).

Returns

Normally you should return true to indicate that the message should be sendt. You can however return false if you for some reason want to cancel the invokation.

See Also

Invoke(), SetMessage(), SetTarget()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Reimplemented in os::ListView, os::Slider, os::TextView, os::Button, os::Spinner, os::MenuItem, os::Control, os::ScrollBar, os::RadioButton, os::CheckBox, and os::CheckMenu.

Referenced by Invoke().

bool Invoker::IsTargetLocal

(

)

const

Description:

Check if the target lives in our process.

Returns

true if the target is local or false if the target lives in a remote process.

See Also

SetTarget(), GetTarget(), os::Messenger

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Messenger::IsTargetLocal().

void Invoker::MessageChanged ( const Message &  cOldMsg )

virtual

Description:

You can overload this member if you need to be notified whenever the internal message is changed by the SetMessage() member.

This membert is called after the new message have been assigned but the old message is available through the cOldMsg argument.

Parameters

cOldMsg

The previous message assigned to this invoker.

See Also

SetMessage(), TargetChanged()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by SetMessage().

status_t Invoker::SetHandlerForReply ( Handler *  pcHandler )

virtual

Description:

Specify a target for replies sendt with os::Message::SendReply() on messages sendt by this invoker.

Look at the os::Messenger class for more info on syncronous/asyncronous replies and messaging in general.

Parameters

pcHandler

The handler that should receive replies on messages sendt by the invoker or NULL to disable replies.

Returns

Always 0.

See Also

GetHandlerForReply(), os::Messenger, os::Message, os::Handler

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

status_t Invoker::SetMessage ( Message *  pcMsg )

virtual

Description:

Assign a new message to the invoker. You can call SetMessage() to assign a message to a invoker that didn't get one in the constructor or to replace the old message. If the invoker already have a message assigned it will be deleted first.

If the message is set to NULL the invoker will be disabled until a new message is assigned.

Note

The invoker will take ownership over the message and will delete it when another message is assigned or the messenger is deleted. The message must therefor be allocated on the heap with the "new" operator and must not be deleted by the application.

Parameters

pcMsg

Pointer to the new message to be sendt when invoked. The invoker takes ownership over the message.

Returns

Always 0.

See Also

GetMessage(), MessageChanged(), Invoke()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References MessageChanged().

Referenced by os::DropdownMenu::DropdownMenu(), os::IconView::SetInvokeMsg(), and os::Spinner::Spinner().

status_t Invoker::SetTarget ( const Handler *  pcHandler, const Looper *  pcLooper = NULL  )

virtual

Description:

Set a new message target for the invoker. Ths pcHandler and pcLooper parameters is passed directly to the internal os::Messenger used to send messages from this invoker. Look at the os::Messenger documentation for a more detailed description on how to target messages.

Parameters

pcHandler	The handler that should receive messages sendt by this invoker or NULL if a looper is to be destined.
pcLooper	If pcHandler is NULL messages will be sendt to this looper without a specific target.

Returns

0 if the a valid target was set. -1 if no valid target was speciefied.

See Also

SetMessage(), TargetChanged(), Invoke()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Messenger::IsValid(), and TargetChanged().

Referenced by os::Spinner::AllAttached(), os::DropdownMenu::AllAttached(), os::TabView::AllAttached(), os::ListView::AllAttached(), os::Control::AttachedToWindow(), os::FileRequester::FileRequester(), and os::Menu::SetTargetForItems().

status_t Invoker::SetTarget ( const Messenger &  cMessenger )

virtual

Description:

Set a new message target.

Parameters

cMessenger

The messenger that should be used to target messages from this invoker.

Returns

0 if the a valid target was set. -1 if no valid target was speciefied.

See Also

SetMessage(), TargetChanged(), Invoke()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References os::Messenger::IsValid(), and TargetChanged().

void Invoker::TargetChanged ( const Messenger &  cOldTarget )

virtual

Description:

You can overload this member if you need to be notified whenever the target is changed by one of the SetTarget() members.

This membert is called after the new target have been assigned but the old target is available through the cOldTarget argument.

Parameters

cOldTarget

The previous target for this invoker.

See Also

SetTarget(), MessageChanged()

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by SetTarget().