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*/ 309