1/* 2 * Copyright 2015, 2019 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 BHandler* BInvoker::Target(BLooper** _looper = NULL) const 179 \brief Invoke BMessenger::Target() on the internal messenger 180 181 \see BMessenger::Target() 182 183 \since BeOS R3 184*/ 185 186 187/*! 188 \fn BMessenger BInvoker::Messenger() const 189 \brief Returns the BMessenger object that the invoker uses to send its 190 messages. 191 192 If a target hasn't been set yet, the returned BMessenger object will be 193 invalid. 194 195 \see BMessenger::IsValid() 196 197 \since BeOS R3 198*/ 199 200 201/*! 202 \fn status_t BInvoker::SetHandlerForReply(BHandler* replyHandler) 203 \brief Sets the BHandler object responsible for handling reply messages. 204 205 When Invoke() is called, the \a replyHandler is passed to the messenger's 206 SendMessage() method, as follows: 207 208\code 209 messenger->SendMessage(message, replyHandler); 210\endcode 211 212 By default, the handler for replies is \c NULL, consequently all reply 213 messages will be sent to the BApplication instead. 214 215 \return Always returns \c B_OK. 216 217 \since BeOS R3 218*/ 219 220 221/*! 222 \fn BHandler* BInvoker::HandlerForReply() const 223 \brief Returns the previously set reply handler or \c NULL if not set. 224 225 \since BeOS R3 226*/ 227 228 229/*! 230 \fn status_t BInvoker::Invoke(BMessage* message) 231 \brief Sends the \a message to the invoker's target. 232 233 If \a message is \c NULL the default message is sent instead. You can set 234 the default message using \a SetMessage or in the constructor. 235 236 This method also sends a B_CONTROL_INVOKED notification to handlers 237 which registered themselves using StartWatching 238 239 \since BeOS R3 240*/ 241 242 243/*! 244 \fn status_t BInvoker::InvokeNotify(BMessage* message, uint32 kind) 245 \brief Sends the \a message to its target, using the notification code 246 specified by \a kind. 247 248 If message is \c NULL, no message is sent to the target, but any watchers 249 of the invoker's handler will receive their expected notifications. 250 By default, \a kind is \c B_CONTROL_INVOKED, the same as sent by Invoke(). 251 252 BInvoker does not send the notification itself, it is up to subclasses to 253 do that as needed. 254 255 \sa BLooper::StartWatching() 256 \sa BLooper::SendNotices() 257 \sa BHandler::NoticeChange() 258 259 \since BeOS R5 260*/ 261 262 263/*! 264 \fn status_t BInvoker::SetTimeout(bigtime_t timeout) 265 \brief Sets the timeout to use when sending the message to the target. 266 267 By default the timeout is set to \c B_INFINITE_TIMEOUT. The \a timeout 268 value is passed into the timeout parameter of BMessenger::SendMessage(). 269 270 \sa BMessenger::SendMessage(BMessage*, BHandler*, bigtime_t) for details. 271 272 \since BeOS R5 273*/ 274 275 276/*! 277 \fn bigtime_t BInvoker::Timeout() const 278 \brief Returns the current timeout value. 279 280 \since BeOS R5 281*/ 282 283 284/*! 285 \fn uint32 BInvoker::InvokeKind(bool* _notify) 286 \brief Returns the kind set by InvokeNotify(). 287 288 Derived classes should implement this method and call it from within 289 Invoke() to determine what kind was specified when InvokeNotify() 290 was called. 291 292 If you care whether Invoke() or InvokeNotify() was originally called, 293 you can use a bool pointer and set its value to \c true if InvokeNotify() 294 was called, or \c false if Invoke() was called. This lets you fetch the 295 InvokeNotify() arguments from Invoke() without breaking binary compatibility 296 with older applications. 297 298 \since BeOS R5 299*/ 300 301 302/*! 303 \fn void BInvoker::BeginInvokeNotify(uint32 kind) 304 \brief Implement this method to set up an InvokeNotify() context. 305 306 This is used by derive classes to emulate an InvokeNotify() call inside of 307 Invoke() without breaking binary compatibility. 308 309 \since BeOS R5 310*/ 311 312 313/*! 314 \fn void BInvoker::EndInvokeNotify() 315 \brief \brief Implement this method to tear down an InvokeNotify() context. 316 317 \since BeOS R5 318*/ 319