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