[haiku-commits] haiku: hrev48682 - docs/user/app
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Thu, 15 Jan 2015 21:30:09 +0100 (CET)
hrev48682 adds 1 changeset to branch 'master'
old head: 7fb1396861fb37acddc0eca58fa55de2100f98a7
new head: 9bf7584d966cd164b3e262fa80d2469a760ad58a
overview:
http://cgit.haiku-os.org/haiku/log/?qt=range&q=9bf7584d966c+%5E7fb1396861fb
----------------------------------------------------------------------------
9bf7584d966c: Add BInvoker docs
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev48682
Commit: 9bf7584d966cd164b3e262fa80d2469a760ad58a
URL: http://cgit.haiku-os.org/haiku/commit/?id=9bf7584d966c
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Thu Jan 15 20:29:00 2015 UTC
----------------------------------------------------------------------------
1 file changed, 280 insertions(+)
docs/user/app/Invoker.dox | 280 ++++++++++++++++++++++++++++++++++++++++++
----------------------------------------------------------------------------
diff --git a/docs/user/app/Invoker.dox b/docs/user/app/Invoker.dox
new file mode 100644
index 0000000..5e61b5e
--- /dev/null
+++ b/docs/user/app/Invoker.dox
@@ -0,0 +1,280 @@
+/*
+ * Copyright 2015 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * John Scipione, jscipione@xxxxxxxxx
+ *
+ * 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.
+
+ When Invoke() is called, the message is sent to the designated BHandler
+ known as the "target". The message is sent as a BMessage. The message is
+ not copied, rather ownership of the BMessage object is transferred to
+ the invoker.
+
+ BInvoker is most often used as a mix-in class, for example, BControl
+ derives from BInvoker as well as from BView.
+
+ \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 Invoke()
+
+ \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()
+
+ \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.
+
+ \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 messages \c what data member.
+
+ \note If a message has not been assigned to the invoker this method
+ returns \c NULL instead.
+
+ \since BeOS R3
+*/
+
+
+/*!
+ \fn status_t BInvoker::SetTarget(BMessenger messenger)
+ \brief Sets the invoker's target to \a messenger.
+
+ \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.
+
+ \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.
+
+ If \a message is \c NULL the message previously set on the invoker is
sent
+ to the invoker's target instead.
+
+ \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().
+
+ \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.
+
+ \since BeOS R5
+*/
+
+
+/*!
+ \fn bigtime_t BInvoker::Timeout() const
+ \brief Returns the current timeout value.
+
+ \since BeOS R3
+*/
+
+
+/*!
+ \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,
+ you can use a bool pointer and set it's value to \c true if
InvokeNotify()
+ 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
+*/
Other related posts:
