Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

os::Invoker Class Reference

#include <invoker.h>

Inheritance diagram for os::Invoker::

os::Control os::DropdownMenu os::MenuItem os::TabView os::Button os::CheckBox os::ListView os::RadioButton os::ScrollBar os::Slider os::Spinner os::TextView os::MenuSeparator List of all members.

Public Methods

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

MessageGetMessage () 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...

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

HandlerGetHandlerForReply () 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@atheos.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@atheos.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@atheos.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@atheos.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@atheos.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@atheos.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@atheos.cx)

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@atheos.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@atheos.cx)

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@atheos.cx)

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@atheos.cx)

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));
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@atheos.cx)

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@atheos.cx)

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

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@atheos.cx)

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@atheos.cx)

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@atheos.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@atheos.cx)

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@atheos.cx)

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@atheos.cx)

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@atheos.cx)


Generated at Tue Sep 11 15:27:48 2001 for AtheOS higlevel API by doxygen1.2.9.1 written by Dimitri van Heesch, © 1997-2001