1/*
2 * Copyright 2011-2014, 2019 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		John Scipione, jscipione@gmail.com
7 * 
8 * Corresponds to:
9 *		headers/os/app/Application.h	hrev49893
10 *		src/kits/app/Application.cpp	hrev52620
11 */
12
13
14/*!
15	\file Application.h
16	\ingroup app
17	\ingroup libbe
18	\brief Provides the BApplication class.
19*/
20
21
22/*!
23	\var be_app
24	\brief Global system app object.
25
26	\since BeOS R3
27*/
28
29
30/*!
31	\var be_app_messenger
32	\brief Global system app messenger object.
33
34	\since BeOS R3
35*/
36
37
38/*!
39	\class BApplication
40	\ingroup app
41	\ingroup libbe
42	\brief A container object for an application.
43
44	A BApplication establishes a connection between the application and the
45	Application Server.
46
47	The most common task performed by a BApplication object is to handle
48	messages sent to it. The BApplication object also is used
49	to get information about your application such as the number of windows
50	it has, its signature, executable location, and launch flags.
51
52	The BApplication object is automatically assigned to the global \c be_app
53	variable. The \c be_app variable allows you to refer to your BApplication
54	object from anywhere in the code.
55
56	To use a BApplication you first construct the object and then begin its
57	message loop by calling the Run() method. The Run() method
58	continues until the application is told to quit. Once Run() returns you
59	should then delete the BApplication object to free its memory usage.
60
61	Typically, you initialize the BApplication object in the programs main()
62	function. A typical main() function looks something like this:
63
64\code
65#include Application.h
66
67main()
68{
69	/* Vendor is your vendor name, application is your application name */
70	BApplication *app = new BApplication("application/x-vnd.vendor-application");
71	app->Run();
72	delete app;
73
74	return 0;
75}
76\endcode
77
78	\since BeOS R3
79*/
80
81
82/*!
83	\fn BApplication::BApplication(const char* signature)
84	\brief Initialize a BApplication with the passed in \a signature.
85
86	The new BApplication is, by default, not running yet. If you have
87	everything set up properly call Run() to start the application.
88
89	You should call InitCheck() to check for constructor initialization
90	errors.
91
92	\param signature The \a signature of the application.
93
94	\since BeOS R3
95*/
96
97
98/*!
99	\fn BApplication::BApplication(const char* signature, status_t* _error)
100	\brief Initialize a BApplication with the passed in \a signature and a
101	       pointer to an error message.
102
103	Any error that occurs while constructing the BApplication will be
104	set to the \a _error pointer. If \a _error points to a \c status_t
105	error then you should not call Run().
106
107	Alternately, you can call InitCheck() to check for constructor 
108	initialization errors.
109
110	\param signature The \a signature of the application.
111	\param _error A pointer to a \c status_t set by the BApplication
112		constructor.
113
114	\since BeOS R5
115*/
116
117/*!
118	\fn status_t BApplication::InitCheck() const
119	\brief Returns the status of the constructor.
120
121	\returns If initialization succeeded returns \c B_OK, otherwise returns an
122	         error status.
123
124	\since BeOS R5
125*/
126
127
128/*!
129	\name Archiving
130*/
131
132
133//! @{
134
135
136/*!
137	\fn BApplication::BApplication(BMessage* data)
138	\brief Initialize a BApplication object from a message.
139
140	The message must contain the signature of the application you wish to
141	initialize in the "mime_sig" variable.
142
143	\param data The message to initialize the BApplication from.
144
145	\since BeOS R3
146*/
147
148
149/*!
150	\fn status_t BApplication::Archive(BMessage* data, bool deep) const
151	\brief Archive the BApplication object into a BMessage.
152
153	\sa BArchivable::Archive()
154
155	\since BeOS R3
156*/
157
158
159/*!
160	\fn BArchivable* BApplication::Instantiate(BMessage* data)
161	\brief Restores the BApplication object from a BMessage.
162
163	\sa BArchivable::Instantiate()
164
165	\since BeOS R3
166*/
167
168
169//! @}
170
171
172/*!
173	\fn BApplication::~BApplication()
174	\brief Destructor Method
175
176	\since BeOS R3
177*/
178
179
180/*!
181	\name Message Loop Control
182*/
183
184
185//! @{
186
187
188/*!
189	\fn thread_id BApplication::Run()
190	\brief Starts the message loop in the thread that it is called from,
191	       and doesn't return until the message loop stops.
192
193	Run() does not spawn a new thread.
194
195	\return The thread_id of the thread that the BApplication is called from.
196
197	\since BeOS R3
198*/
199
200
201/*!
202	\fn void BApplication::Quit()
203	\brief Tells the thread to finish processing the message queue, disallowing
204	       any new messages.
205
206	Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait
207	for the message queue to empty. Run() will be then able to return. 
208
209	Quit() doesn't delete the BApplication object after Run() is called. You
210	should delete the BApplication object yourself one Run() returns.
211	However Quit() does delete the object if it's called before the message loop
212	starts i.e. before Run() is called.
213
214	\since BeOS R3
215*/
216
217
218//! @}
219
220
221/*!
222	\name Hook Methods
223*/
224
225
226//! @{
227
228
229/*!
230	\fn bool BApplication::QuitRequested()
231	\brief Hook method that gets invoked when the BApplication receives a
232	       \c B_QUIT_REQUESTED message.
233
234	BApplication sends a QuitRequested() message to each of its BWindow objects.
235	If all of the BWindow s return \c true then the windows are
236	each destroyed (through BWindow::Quit()) and QuitRequested() returns
237	\c true. If any of the BWindow returns \c false, the BWindow s
238	are not destroyed and QuitRequested() returns \c false.
239
240	\return \c true if the application quit or \c false if the
241	        application failed to quit.
242
243	\since BeOS R3
244*/
245
246
247/*!
248	\fn void BApplication::ReadyToRun()
249	\brief Hook method that's invoked when the BApplication receives a
250	       \c B_READY_TO_RUN message.
251
252	The ReadyToRun() method is automatically called by the Run() method. It is
253	sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED messages
254	(if any) have already been handled. ReadyToRun() is the only message that
255	every running application is guaranteed to receive.
256
257	The default version of ReadyToRun() is empty. You should override the
258	ReadyToRun() method to do whatever you want to do. If you haven't
259	constructed any windows in your application yet then this would be a good
260	place to do so.
261
262	\since BeOS R3
263*/
264
265
266/*!
267	\fn void BApplication::ArgvReceived(int32 argc, char** argv)
268	\brief Hook method that gets invoked when the application receives a
269	       \c B_ARGV_RECEIVED message.
270
271	If command line arguments are specified when the application is launched
272	from the the shell, or if \c argv/argc values are passed to
273	BRoster::Launch(), then this method is executed.
274
275	\warning ArgvReceived() is not called if no command line arguments are
276	specified, or if BRoster::Launch() was called without any \c argv/argc
277	values.
278
279	The arguments passed to ArgvReceived() are the constructed in the same way
280	as those passed to command line programs. The number of command line
281	arguments is passed in \a argc and the arguments themselves are passed as an
282	array of strings in \a argv. The first \a argv string is the name of the
283	program and the rest of the strings are the command line arguments.
284
285	BRoster::Launch() adds the program name to the front of the \a argv array
286	and increments the \a argc value.
287
288	The \c B_ARGV_RECEIVED message (if sent) is sent only once, just
289	before the \c B_READY_TO_RUN message is sent. However, if you try to
290	relaunch an application that is already running and the application is set
291	to \c B_EXCLUSIVE_LAUNCH or \c B_SINGLE_LAUNCH then the application will
292	generate a \c B_ARGV_RECEIVED message and send it to the already running
293	instance. Thus in this case the \c B_ARGV_RECEIVED message can show
294	up at any time.
295
296	\since BeOS R3
297*/
298
299
300/*!
301	\fn void BApplication::AppActivated(bool active)
302	\brief Hook method that gets invoked when the application receives
303	\c B_APP_ACTIVATED message.
304
305	The message is sent whenever the application changes its active application
306	status. The active flag set to is \c true when the application becomes
307	active and is set to \c false when the application becomes inactive.
308
309	The application becomes activated in response to a user action such as
310	clicking on or unhiding one of its windows. The application can have its
311	active status set programmatically by calling either the BWindow::Activate()
312	or BRoster::ActivateApp() methods.
313
314	This method is called after ReadyToRun() provided the application is
315	displaying a window that can be set active.
316
317	\since BeOS R3
318*/
319
320
321/*!
322	\fn void BApplication::RefsReceived(BMessage* message)
323	\brief Hook method that gets invoked when the application receives a
324	       \c B_REFS_RECEIVED message.
325
326	The message is sent in response to a user action such as a user
327	drag-and-dropping a file on your app's icon or opening a file that the
328	application is set to handle. You can use the IsLaunching() method to
329	discern whether the message arrived when the application is launched or
330	after the application has already been running.
331
332	The default implementation is empty. You can override this method to do
333	something with the received refs. Typically you create BEntry or BFile
334	objects from the passed in refs.
335
336	\param message contains a single field named "be:refs" that contains one
337	       or more entry_ref (\c B_REF_TYPE) items, one for each file sent.
338
339	\since BeOS R3
340*/
341
342
343/*!
344	\fn void BApplication::AboutRequested()
345	\brief Hook method that gets invoked when the BApplication receives a
346	       \c B_ABOUT_REQUESTED message.
347
348	You should override this method to pop an alert to provide information
349	about the application.
350
351	The default implementation pops a basic alert dialog.
352
353	\since BeOS R3
354*/
355
356
357//! @}
358
359
360/*!
361	\name Cursor
362*/
363
364
365//! @{
366
367
368/*!
369	\fn BApplication::ShowCursor()
370	\brief Restores the cursor.
371
372	\since BeOS R3
373*/
374
375
376/*!
377	\fn void BApplication::HideCursor()
378	\brief Hides the cursor from the screen.
379
380	\since BeOS R3
381*/
382
383
384/*!
385	\fn void BApplication::ObscureCursor()
386	\brief Hides the cursor until the mouse is moved.
387
388	\since BeOS R3
389*/
390
391
392/*!
393	\fn bool BApplication::IsCursorHidden() const
394	\brief Returns whether or not the cursor is hidden.
395
396	\returns \c true if the cursor is hidden, \c false if not.
397
398	\since BeOS R3
399*/
400
401
402/*!
403	\fn void BApplication::SetCursor(const void* cursor)
404	\brief Sets the \a cursor to be used when the application is active.
405
406	You can pass one of the pre-defined cursor constants such as
407	\c B_HAND_CURSOR or \c B_I_BEAM_CURSOR or you can create your own pass
408	in your own cursor image. The cursor data format is described in the BCursor
409	class.
410
411	\param cursor The cursor data to set the cursor to.
412
413	\since BeOS R3
414*/
415
416
417/*!
418	\fn void BApplication::SetCursor(const BCursor* cursor, bool sync)
419	\brief Sets the \a cursor to be used when the application is active
420	       with \a sync immediately option.
421
422	The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand
423	cursor and \c B_CURSOR_I_BEAM for the I-beam cursor.
424
425	\param cursor A BCursor object to set the \a cursor to.
426	\param sync synchronize the cursor immediately.
427
428	\since BeOS R5
429*/
430
431
432//! @}
433
434
435/*!
436	\name Info
437*/
438
439
440//! @{
441
442
443/*!
444	\fn int32 BApplication::CountWindows() const
445	\brief Returns the number of windows created by the application.
446
447	\returns the number of windows created by the application.
448
449	\since BeOS R3
450*/
451
452
453/*!
454	\fn BWindow* BApplication::WindowAt(int32 index) const
455	\brief Returns the BWindow object at the specified \a index in the
456	       application's window list.
457
458	If \a index is out of range, this function returns \c NULL.
459
460	\warning Locking the BApplication object doesn't lock the window list.
461
462	\param index The \a index of the desired BWindow.
463
464	\returns The BWindow object at the specified \a index or \c NULL
465	         if the \a index is out of range.
466
467	\since BeOS R3
468*/
469
470
471/*!
472	\fn int32 BApplication::CountLoopers() const
473	\brief Returns the number of BLoopers created by the application.
474
475	\warning This method may return \c B_ERROR.
476
477	\returns The number of BLoopers in the application.
478
479	\since BeOS R5
480*/
481
482
483/*!
484	\fn BLooper* BApplication::LooperAt(int32 index) const
485	\brief Returns the BLooper object at the specified index in the
486	       application's looper list.
487
488	If index is out of range, this function returns \c NULL.
489
490	\returns The BLooper object at the specified \a index or \c NULL
491	         if the \a index is out of range.
492
493	\since BeOS R5
494*/
495
496
497//! @}
498
499
500/*!
501	\name Status
502*/
503
504
505//! @{
506
507
508/*!
509	\fn bool BApplication::IsLaunching() const
510	\brief Returns whether or not the application is in the process of
511	       launching.
512
513	\returns \c true if the application is launching, \c false if the
514	         application is already running.
515
516	\since BeOS R3
517*/
518
519
520/*!
521	\fn const char* BApplication::Signature() const
522	\brief Returns the signature of the Application
523
524	\since Haiku R1
525*/
526
527
528/*!
529	\fn status_t BApplication::GetAppInfo(app_info *info) const
530	\brief Fills out the \a info parameter with information about the
531	       application.
532
533	This is equivalent to
534	be_roster->GetRunningAppInfo(be_app->Team(), info);
535
536	\returns \c B_NO_INIT on an error or \c B_OK if all goes well.
537
538	\sa BRoster::GetAppInfo()
539
540	\since BeOS R3
541*/
542
543
544/*!
545	\fn BResources* BApplication::AppResources()
546	\brief Returns a BResources object for the application.
547
548	\since BeOS R5
549*/
550
551
552//! @}
553
554
555/*!
556	\name Message Mechanics
557*/
558
559
560//! @{
561
562
563/*!
564	\fn void BApplication::MessageReceived(BMessage *message)
565	\copydoc BHandler::MessageReceived()
566*/
567
568
569/*!
570	\fn void BApplication::DispatchMessage(BMessage *message,
571		BHandler *handler)
572	\copydoc BLooper::DispatchMessage()
573*/
574
575
576//! @}
577
578
579/*!
580	\name Pulse
581*/
582
583
584//! @{
585
586
587/*!
588	\fn void BApplication::Pulse()
589	\brief Hook method that gets invoked when the BApplication receives a
590	       \c B_PULSE message.
591
592	An action is performed each time app_server calls the Pulse() method. 
593	The pulse rate is set by SetPulseRate(). You can implement Pulse() to do
594	anything you want. The default version does nothing. The pulse granularity
595	is no better than once per 100,000 microseconds.
596
597	\sa SetPulseRate()
598
599	\since BeOS R3
600*/
601
602
603/*!
604	\fn void BApplication::SetPulseRate(bigtime_t rate)
605	\brief Sets the interval that the \c B_PULSE messages are sent.
606
607	If the \a rate is set to 0 then the \c B_PULSE messages are not sent.
608	The pulse rate can be no faster than once per 100,000 microseconds or so.
609
610	\param rate The rate at which \c B_PULSE messages are sent to the
611	       application.
612
613	\since BeOS R3
614*/
615
616
617//! @}
618
619
620/*!
621	\name Scripting
622*/
623
624
625//! @{
626
627
628/*!
629	\fn BHandler* BApplication::ResolveSpecifier(BMessage* message,
630		int32 index, BMessage *specifier, int32 what, const char *property)
631	\copydoc BHandler::ResolveSpecifier()
632*/
633
634
635/*!
636	\fn status_t BApplication::GetSupportedSuites(BMessage* data)
637	\copydoc BHandler::GetSupportedSuites()
638*/
639
640
641//! @}
642
643
644/*!
645	\name Lifecycle Management
646*/
647
648
649//! @{
650
651
652/*!
653	\fn status_t BApplication::RegisterLooper(BLooper* looper)
654	\brief Register a looper to quit when the application quits
655
656	There are situations where you create BLooper objects, that you may want to
657	have BApplication quit properly, when the application is quitting. This
658	method allows you to add Loopers under management of BApplication.
659
660	Note that Windows are automatically handled by BApplication, so there is no
661	need to manually register BWindow-based loopers using this method.
662
663	\returns \c B_OK when the looper was registered without an issue,
664		\c B_BAD_VALUE when you try to register a BWindow, or \c B_ERROR
665		when the looper was already registered.
666
667	\since Haiku R1
668*/
669
670
671/*!
672	\fn status_t BApplication::UnregisterLooper(BLooper* looper)
673	\brief Remove a previously registered Looper from the quit-list
674
675	If a looper has been added to the quit list using
676	BApplication::RegisterLooper, they can be unregistered using this method.
677	You should do this in the case the looper quits before the application
678	does.
679
680	Note that Windows are automatically handled by BApplication, so you don't
681	have to use this function to unregister windows.
682
683	\returns \c B_OK when the looper has been removed, \c B_BAD_VALUE when you
684	try to unregister a BWindow, or \c B_ERROR when the looper was not
685	previously registered.
686
687	\since Haiku R1
688*/
689
690
691//! @}
692