Syllable higlevel API: os::Invoker Class Reference

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])

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 ([email protected])


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

os::Invoker Class Reference
[Various utillity classes.]

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

os::Invoker Class Reference [Various utillity classes.]

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

os::Invoker Class Reference
[Various utillity classes.]