docs/user/app/Invoker.dox

   1 /*
   2  * Copyright 2015 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.tk
   7  *              Axel Dörfler, axeld@pinc-software.de
   8  *              John Scipione, jscipione@gmail.com
   9  *
  10  * Corresponds to:
  11  *              headers/os/app/Invoker.h        hrev48680
  12  *              src/kits/app/Invoker.cpp        hrev48680
  13  */
  14
  15
  16 /*!
  17         \file Invoker.h
  18         \ingroup app
  19         \ingroup libbe
  20         \brief Provides the BInvoker class.
  21 */
  22
  23
  24 /*!
  25         \class BInvoker
  26         \ingroup app
  27         \ingroup libbe
  28         \brief An object that can be "invoked" to send a message to a BHandler.
  29
  30         The designated BHandler of a BInvoker is known as its "target".
  31
  32         BInvoker is most often used as a mix-in class, for example, BControl
  33         derives from BInvoker as well as from BView.
  34
  35         \sa Invoke()
  36         \sa SetTarget(const BHandler*, const BLooper*) for details.
  37
  38         \since BeOS R3
  39 */
  40
  41
  42 /*!
  43         \fn BInvoker::BInvoker(BMessage* message, BMessenger messenger)
  44         \brief Initializes the BInvoker with \a message and sets the target
  45                \a messenger where the message is sent when Invoke() is called.
  46
  47         A BMessenger can target either local or remote objects.
  48
  49         \sa SetMessage() for details.
  50
  51         \since BeOS R3
  52 */
  53
  54
  55 /*!
  56         \fn BInvoker::BInvoker(BMessage* message, const BHandler* handler,
  57                 const BLooper* looper)
  58         \brief Initializes the BInvoker with \a message and sets the target
  59                to either a local \a handler or as the preferred handler of a
  60                local \a looper where the message is sent when Invoke() is called.
  61
  62         \note It is not necessary to specify both the \a handler and the
  63               \a looper, the unused parameter should be passed in as \c NULL.
  64
  65         \sa Invoke()
  66         \sa SetTarget(const BHandler*, const BLooper*) for details.
  67
  68         \since BeOS R3
  69 */
  70
  71
  72 /*!
  73         \fn BInvoker::BInvoker()
  74         \brief Initializes a BInvoker without a message or target.
  75
  76         You must call SetTarget() to set the invoker's target before calling
  77         Invoke() for the message to be sent.
  78
  79         You may call SetMessage() to set the message to send when calling Invoke(),
  80         alternatively you may pass a BMessage to Invoke() each time you call it.
  81
  82         \sa Invoke()
  83         \sa SetMessage()
  84         \sa SetTarget()
  85
  86         \since BeOS R3
  87 */
  88
  89
  90 /*!
  91         \fn BInvoker::~BInvoker()
  92         \brief Destructor method, deletes the BMessage object if set.
  93
  94         \since BeOS R3
  95 */
  96
  97
  98 /*!
  99         \fn status_t BInvoker::SetMessage(BMessage* message)
 100         \brief Assigns \a message to the invoker, deleting any previously
 101                assigned message.
 102
 103         You may pass \c NULL into \a message to delete the current message
 104         without replacing it.
 105
 106         When Invoke() is called with a \c NULL message parameter, a copy of the
 107         passed in \a message is sent to the target BHandler. BInvoker takes
 108         ownership of the BMessage object, so you must not delete it yourself.
 109
 110         \since BeOS R3
 111 */
 112
 113
 114 /*!
 115         \fn BMessage* BInvoker::Message() const
 116         \brief Returns a pointer to the invoker's message object.
 117
 118         \note If a message has not been assigned to the invoker this method
 119               returns \c NULL instead.
 120
 121         \since BeOS R3
 122 */
 123
 124
 125 /*!
 126         \fn uint32 BInvoker::Command() const
 127         \brief Returns the message's \c what data member.
 128
 129         \note If a message has not been assigned to the invoker this method
 130               returns \c 0 instead.
 131
 132         \since BeOS R3
 133 */
 134
 135
 136 /*!
 137         \fn status_t BInvoker::SetTarget(BMessenger messenger)
 138         \brief Sets the invoker's target to \a messenger.
 139
 140         A BMessenger target can be used to designate a remote handler (living
 141         in another team).
 142
 143         \since BeOS R3
 144 */
 145
 146
 147 /*!
 148         \fn status_t BInvoker::SetTarget(const BHandler* handler,
 149                 const BLooper* looper)
 150         \brief Sets the target to either a local \a handler or as the preferred
 151                handler of a local \a looper.
 152
 153         \note It is not necessary to specify both the \a handler and the
 154               \a looper, the unused parameter should be passed in as \c NULL.
 155
 156         If given only a \a handler, it must already be attached to a BLooper.
 157
 158         If given only a \a looper, the message will be sent to its preferred
 159         handler (in the case of a BWindow that is the focused view).
 160
 161         \since BeOS R3
 162 */
 163
 164
 165 /*!
 166         \fn bool BInvoker::IsTargetLocal() const
 167         \brief Returns whether or not the invoker and its target belong to the
 168                same team.
 169
 170         \return \c true if the invoker and its target are in the same team,
 171                 \c false if they reside in separate address spaces.
 172
 173         \since BeOS R3
 174 */
 175
 176
 177 /*!
 178         \fn BMessenger BInvoker::Messenger() const
 179         \brief Returns the BMessenger object that the invoker uses to send its
 180                messages.
 181
 182         If a target hasn't been set yet, the returned BMessenger object will be
 183         invalid.
 184
 185         \see BMessenger::IsValid()
 186
 187         \since BeOS R3
 188 */
 189
 190
 191 /*!
 192         \fn status_t BInvoker::SetHandlerForReply(BHandler* replyHandler)
 193         \brief Sets the BHandler object responsible for handling reply messages.
 194
 195         When Invoke() is called, the \a replyHandler is passed to the messenger's
 196         SendMessage() method, as follows:
 197
 198 \code
 199    messenger->SendMessage(message, replyHandler);
 200 \endcode
 201
 202         By default, the handler for replies is \c NULL, consequently all reply
 203         messages will be sent to the BApplication instead.
 204
 205     \return Always returns \c B_OK.
 206
 207         \since BeOS R3
 208 */
 209
 210
 211 /*!
 212         \fn BHandler* BInvoker::HandlerForReply() const
 213         \brief Returns the previously set reply handler or \c NULL if not set.
 214
 215         \since BeOS R3
 216 */
 217
 218
 219 /*!
 220         \fn status_t BInvoker::Invoke(BMessage* message)
 221         \brief Sends the \a message to the invoker's target.
 222
 223         If \a message is \c NULL the default message is sent instead. You can set
 224         the default message using \a SetMessage or in the constructor.
 225
 226         This method also sends a B_CONTROL_INVOKED notification to handlers
 227         which registered themselves using StartWatching
 228
 229         \since BeOS R3
 230 */
 231
 232
 233 /*!
 234         \fn status_t BInvoker::InvokeNotify(BMessage* message, uint32 kind)
 235         \brief Sends the \a message to its target, using the notification code
 236                specified by \a kind.
 237
 238         If message is \c NULL, no message is sent to the target, but any watchers
 239         of the invoker's handler will receive their expected notifications.
 240         By default, \a kind is \c B_CONTROL_INVOKED, the same as sent by Invoke().
 241
 242         BInvoker does not send the notification itself, it is up to subclasses to
 243         do that as needed.
 244
 245         \sa BLooper::StartWatching()
 246         \sa BLooper::SendNotices()
 247         \sa BHandler::NoticeChange()
 248
 249         \since BeOS R5
 250 */
 251
 252
 253 /*!
 254         \fn status_t BInvoker::SetTimeout(bigtime_t timeout)
 255         \brief Sets the timeout to use when sending the message to the target.
 256
 257         By default the timeout is set to \c B_INFINITE_TIMEOUT. The \a timeout
 258         value is passed into the timeout parameter of BMessenger::SendMessage().
 259
 260         \sa BMessenger::SendMessage(BMessage*, BHandler*, bigtime_t) for details.
 261
 262         \since BeOS R5
 263 */
 264
 265
 266 /*!
 267         \fn bigtime_t BInvoker::Timeout() const
 268         \brief Returns the current timeout value.
 269
 270         \since BeOS R5
 271 */
 272
 273
 274 /*!
 275         \fn uint32 BInvoker::InvokeKind(bool* _notify)
 276         \brief Returns the kind set by InvokeNotify().
 277
 278         Derived classes should implement this method and call it from within
 279         Invoke() to determine what kind was specified when InvokeNotify()
 280         was called.
 281
 282         If you care whether Invoke() or InvokeNotify() was originally called,
 283         you can use a bool pointer and set its value to \c true if InvokeNotify()
 284         was called, or \c false if Invoke() was called. This lets you fetch the
 285         InvokeNotify() arguments from Invoke() without breaking binary compatibility
 286         with older applications.
 287
 288         \since BeOS R5
 289 */
 290
 291
 292 /*!
 293         \fn void BInvoker::BeginInvokeNotify(uint32 kind)
 294         \brief Implement this method to set up an InvokeNotify() context.
 295
 296         This is used by derive classes to emulate an InvokeNotify() call inside of
 297         Invoke() without breaking binary compatibility.
 298
 299         \since BeOS R5
 300 */
 301
 302
 303 /*!
 304         \fn void BInvoker::EndInvokeNotify()
 305         \brief \brief Implement this method to tear down an InvokeNotify() context.
 306
 307         \since BeOS R5
 308 */