haiku/docs/user/app/Invoker.dox

309 lines
7.5 KiB
Plaintext
Raw Normal View History

2015-01-15 23:29:00 +03:00
/*
* Copyright 2015 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
2015-01-15 23:29:00 +03:00
* 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".
2015-01-15 23:29:00 +03:00
BInvoker is most often used as a mix-in class, for example, BControl
derives from BInvoker as well as from BView.
\sa Invoke()
\sa SetTarget(const BHandler*, const BLooper*) for details.
2015-01-15 23:29:00 +03:00
\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.
2015-01-15 23:29:00 +03:00
\since BeOS R3
*/
/*!
\fn BInvoker::BInvoker(BMessage* message, const BHandler* handler,
const BLooper* looper)
\brief Initializes the BInvoker with \a message and sets the target
to either a local \a handler or as the preferred handler of a
local \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.
2015-01-15 23:29:00 +03:00
\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 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.
\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 previously
assigned message.
You may pass \c NULL into \a message to delete the current message
without replacing it.
When Invoke() is called with a \c NULL message parameter, a copy of the
passed in \a message is sent to the target BHandler. BInvoker takes
ownership of the BMessage object, so you must not delete it yourself.
2015-01-15 23:29:00 +03:00
\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 method
returns \c NULL instead.
\since BeOS R3
*/
/*!
\fn uint32 BInvoker::Command() const
\brief Returns the message's \c what data member.
2015-01-15 23:29:00 +03:00
\note If a message has not been assigned to the invoker this method
2015-01-17 15:41:55 +03:00
returns \c 0 instead.
2015-01-15 23:29:00 +03:00
\since BeOS R3
*/
/*!
\fn status_t BInvoker::SetTarget(BMessenger messenger)
\brief Sets the invoker's target to \a messenger.
2015-01-17 15:41:55 +03:00
A BMessenger target can be used to designate a remote handler (living
in another team).
2015-01-15 23:29:00 +03:00
\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 preferred
handler 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.
2015-01-17 15:41:55 +03:00
If given only a \a handler, it must already be attached to a BLooper.
2015-01-17 15:41:55 +03:00
If given only a \a looper, the message will be sent to its preferred
handler (in the case of a BWindow that is the focused view).
2015-01-15 23:29:00 +03:00
\since BeOS R3
*/
/*!
\fn bool BInvoker::IsTargetLocal() const
\brief Returns whether or not the invoker and its target belong to the
same 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 BMessenger BInvoker::Messenger() const
\brief 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 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's
SendMessage() method, as follows:
\code
messenger->SendMessage(message, replyHandler);
\endcode
By default, the handler for replies is \c NULL, consequently all reply
messages 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.
2015-01-17 15:41:55 +03:00
If \a message is \c NULL the default message is sent instead. You can set
the default message using \a SetMessage or in the constructor.
This method also sends a B_CONTROL_INVOKED notification to handlers
which registered themselves using StartWatching
2015-01-15 23:29:00 +03:00
\since BeOS R3
*/
/*!
\fn status_t BInvoker::InvokeNotify(BMessage* message, uint32 kind)
\brief Sends the \a message to its target, using the notification code
specified by \a kind.
If message is \c NULL, no message is sent to the target, but any watchers
of the invoker's handler will receive their expected notifications.
By default, \a kind is \c B_CONTROL_INVOKED, the same as sent by Invoke().
2015-01-17 15:41:55 +03:00
BInvoker does not send the notification itself, it is up to subclasses to
do that as needed.
\sa BLooper::StartWatching()
2015-01-17 15:41:55 +03:00
\sa BLooper::SendNotices()
\sa BHandler::NoticeChange()
2015-01-15 23:29:00 +03:00
\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 timeout
value is passed into the timeout parameter of BMessenger::SendMessage().
\sa BMessenger::SendMessage(BMessage*, BHandler*, bigtime_t) for details.
2015-01-15 23:29:00 +03:00
\since BeOS R5
*/
/*!
\fn bigtime_t BInvoker::Timeout() const
\brief Returns the current timeout value.
\since BeOS R5
2015-01-15 23:29:00 +03:00
*/
/*!
\fn uint32 BInvoker::InvokeKind(bool* _notify)
\brief 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,
2017-11-10 00:14:19 +03:00
you can use a bool pointer and set its value to \c true if InvokeNotify()
2015-01-15 23:29:00 +03:00
was called, or \c false if Invoke() was called. This lets you fetch the
InvokeNotify() arguments from Invoke() without breaking binary compatibility
with 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 of
Invoke() 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
*/