/** Copyright 2015, 2019 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Adrien Destugues, pulkomandy@pulkomandy.tk* Axel Dörfler, axeld@pinc-software.de* John Scipione, jscipione@gmail.com** Corresponds to:* headers/os/app/Invoker.h hrev48680* src/kits/app/Invoker.cpp hrev48680*//*!\file Invoker.h\ingroup app\ingroup libbe\brief Provides the BInvoker class.*//*!\class BInvoker\ingroup app\ingroup libbe\brief 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, BControlderives from BInvoker as well as from BView.\sa Invoke()\sa SetTarget(const BHandler*, const BLooper*) for details.\since BeOS R3*//*!\fn BInvoker::BInvoker(BMessage* message, BMessenger messenger)\brief Initializes the BInvoker with \a message and sets the target\a messenger where the message is sent when Invoke() is called.A BMessenger can target either local or remote objects.\sa SetMessage() for details.\since BeOS R3*//*!\fn BInvoker::BInvoker(BMessage* message, const BHandler* handler,const BLooper* looper)\brief Initializes the BInvoker with \a message and sets the targetto either a local \a handler or as the preferred handler of alocal \a looper where the message is sent when Invoke() is called.\note It is not necessary to specify both the \a handler and the\a looper, the unused parameter should be passed in as \c NULL.\sa Invoke()\sa SetTarget(const BHandler*, const BLooper*) for details.\since BeOS R3*//*!\fn BInvoker::BInvoker()\brief Initializes a BInvoker without a message or target.You must call SetTarget() to set the invoker's target before callingInvoke() 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.\sa Invoke()\sa SetMessage()\sa SetTarget()\since BeOS R3*//*!\fn BInvoker::~BInvoker()\brief Destructor method, deletes the BMessage object if set.\since BeOS R3*//*!\fn status_t BInvoker::SetMessage(BMessage* message)\brief Assigns \a message to the invoker, deleting any previouslyassigned message.You may pass \c NULL into \a message to delete the current messagewithout replacing it.When Invoke() is called with a \c NULL message parameter, a copy of thepassed in \a message is sent to the target BHandler. BInvoker takesownership of the BMessage object, so you must not delete it yourself.\since BeOS R3*//*!\fn BMessage* BInvoker::Message() const\brief Returns a pointer to the invoker's message object.\note If a message has not been assigned to the invoker this methodreturns \c NULL instead.\since BeOS R3*//*!\fn uint32 BInvoker::Command() const\brief Returns the message's \c what data member.\note If a message has not been assigned to the invoker this methodreturns \c 0 instead.\since BeOS R3*//*!\fn status_t BInvoker::SetTarget(BMessenger messenger)\brief Sets the invoker's target to \a messenger.A BMessenger target can be used to designate a remote handler (livingin another team).\since BeOS R3*//*!\fn status_t BInvoker::SetTarget(const BHandler* handler,const BLooper* looper)\brief Sets the target to either a local \a handler or as the preferredhandler of a local \a looper.\note It is not necessary to specify both the \a handler and the\a looper, the unused parameter should be passed in as \c NULL.If given only a \a handler, it must already be attached to a BLooper.If given only a \a looper, the message will be sent to its preferredhandler (in the case of a BWindow that is the focused view).\since BeOS R3*//*!\fn bool BInvoker::IsTargetLocal() const\brief Returns whether or not the invoker and its target belong to thesame team.\return \c true if the invoker and its target are in the same team,\c false if they reside in separate address spaces.\since BeOS R3*//*!\fn BHandler* BInvoker::Target(BLooper** _looper = NULL) const\brief Invoke BMessenger::Target() on the internal messenger\see BMessenger::Target()\since BeOS R3*//*!\fn BMessenger BInvoker::Messenger() const\brief Returns the BMessenger object that the invoker uses to send itsmessages.If a target hasn't been set yet, the returned BMessenger object will beinvalid.\see BMessenger::IsValid()\since BeOS R3*//*!\fn status_t BInvoker::SetHandlerForReply(BHandler* replyHandler)\brief Sets the BHandler object responsible for handling reply messages.When Invoke() is called, the \a replyHandler is passed to the messenger'sSendMessage() method, as follows:\codemessenger->SendMessage(message, replyHandler);\endcodeBy default, the handler for replies is \c NULL, consequently all replymessages will be sent to the BApplication instead.\return Always returns \c B_OK.\since BeOS R3*//*!\fn BHandler* BInvoker::HandlerForReply() const\brief Returns the previously set reply handler or \c NULL if not set.\since BeOS R3*//*!\fn status_t BInvoker::Invoke(BMessage* message)\brief Sends the \a message to the invoker's target.If \a message is \c NULL the default message is sent instead. You can setthe default message using \a SetMessage or in the constructor.This method also sends a B_CONTROL_INVOKED notification to handlerswhich registered themselves using StartWatching\since BeOS R3*//*!\fn status_t BInvoker::InvokeNotify(BMessage* message, uint32 kind)\brief Sends the \a message to its target, using the notification codespecified by \a kind.If message is \c NULL, no message is sent to the target, but any watchersof the invoker's handler will receive their expected notifications.By default, \a kind is \c B_CONTROL_INVOKED, the same as sent by Invoke().BInvoker does not send the notification itself, it is up to subclasses todo that as needed.\sa BLooper::StartWatching()\sa BLooper::SendNotices()\sa BHandler::NoticeChange()\since BeOS R5*//*!\fn status_t BInvoker::SetTimeout(bigtime_t timeout)\brief Sets the timeout to use when sending the message to the target.By default the timeout is set to \c B_INFINITE_TIMEOUT. The \a timeoutvalue is passed into the timeout parameter of BMessenger::SendMessage().\sa BMessenger::SendMessage(BMessage*, BHandler*, bigtime_t) for details.\since BeOS R5*//*!\fn bigtime_t BInvoker::Timeout() const\brief Returns the current timeout value.\since BeOS R5*//*!\fn uint32 BInvoker::InvokeKind(bool* _notify)\brief Returns the kind set by InvokeNotify().Derived classes should implement this method and call it from withinInvoke() 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 \c true if InvokeNotify()was called, or \c false if Invoke() was called. This lets you fetch theInvokeNotify() arguments from Invoke() without breaking binary compatibilitywith older applications.\since BeOS R5*//*!\fn void BInvoker::BeginInvokeNotify(uint32 kind)\brief Implement this method to set up an InvokeNotify() context.This is used by derive classes to emulate an InvokeNotify() call inside ofInvoke() without breaking binary compatibility.\since BeOS R5*//*!\fn void BInvoker::EndInvokeNotify()\brief \brief Implement this method to tear down an InvokeNotify() context.\since BeOS R5*/