]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: app.h | |
e54c96f1 | 3 | // Purpose: interface of wxApp |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
8064223b | 9 | |
23324ae1 | 10 | /** |
8064223b | 11 | @class wxAppConsole |
7c913512 | 12 | |
8064223b | 13 | This class is essential for writing console-only or hybrid apps without |
f045c7f5 FM |
14 | having to define @c wxUSE_GUI=0. |
15 | ||
16 | It is used to: | |
17 | @li set and get application-wide properties (see wxAppConsole::CreateTraits | |
18 | and wxAppConsole::SetXXX functions) | |
19 | @li implement the windowing system message or event loop: events in fact are | |
20 | supported even in console-mode applications (see wxAppConsole::HandleEvent | |
21 | and wxAppConsole::ProcessPendingEvents); | |
22 | @li initiate application processing via wxApp::OnInit; | |
23 | @li allow default processing of events not handled by other | |
24 | objects in the application (see wxAppConsole::FilterEvent) | |
25 | @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions) | |
26 | ||
27 | You should use the macro IMPLEMENT_APP(appClass) in your application | |
28 | implementation file to tell wxWidgets how to create an instance of your | |
29 | application class. | |
7c913512 | 30 | |
f045c7f5 FM |
31 | Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function |
32 | (which returns a reference to your application object) to be visible to other | |
33 | files. | |
7c913512 | 34 | |
23324ae1 FM |
35 | @library{wxbase} |
36 | @category{appmanagement} | |
7c913512 | 37 | |
84094285 | 38 | @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase |
23324ae1 | 39 | */ |
8064223b | 40 | class wxAppConsole : public wxEvtHandler |
23324ae1 | 41 | { |
8064223b | 42 | protected: |
23324ae1 | 43 | /** |
8064223b | 44 | Creates the wxAppTraits object when GetTraits() needs it for the first time. |
23324ae1 | 45 | |
8064223b | 46 | @see wxAppTraits |
23324ae1 | 47 | */ |
8064223b | 48 | virtual wxAppTraits* CreateTraits(); |
23324ae1 | 49 | |
8064223b | 50 | public: |
3c4f71cc | 51 | |
23324ae1 | 52 | /** |
8064223b | 53 | Destructor. |
23324ae1 | 54 | */ |
8064223b | 55 | virtual ~wxAppConsole(); |
23324ae1 FM |
56 | |
57 | /** | |
58 | Dispatches the next event in the windowing system event queue. | |
8064223b FM |
59 | Blocks until an event appears if there are none currently |
60 | (use Pending() if this is not wanted). | |
61 | ||
23324ae1 | 62 | This can be used for programming event loops, e.g. |
96d7cc9b FM |
63 | |
64 | @code | |
65 | while (app.Pending()) | |
66 | Dispatch(); | |
67 | @endcode | |
3c4f71cc | 68 | |
8064223b FM |
69 | @return @false if the event loop should stop and @true otherwise. |
70 | ||
4cc4bfaf | 71 | @see Pending() |
23324ae1 | 72 | */ |
8064223b | 73 | virtual bool Dispatch(); |
23324ae1 FM |
74 | |
75 | /** | |
76 | Call this to explicitly exit the main message (event) loop. | |
77 | You should normally exit the main loop (and the application) by deleting | |
78 | the top window. | |
79 | */ | |
80 | virtual void ExitMainLoop(); | |
81 | ||
82 | /** | |
83 | This function is called before processing any event and allows the application | |
96d7cc9b FM |
84 | to preempt the processing of some events. |
85 | ||
86 | If this method returns -1 the event is processed normally, otherwise either | |
87 | @true or @false should be returned and the event processing stops immediately | |
88 | considering that the event had been already processed (for the former return | |
89 | value) or that it is not going to be processed at all (for the latter one). | |
23324ae1 | 90 | */ |
8064223b | 91 | virtual int FilterEvent(wxEvent& event); |
23324ae1 FM |
92 | |
93 | /** | |
3c4f71cc VS |
94 | Returns the user-readable application name. |
95 | ||
328fafa1 VZ |
96 | The difference between this string and the one returned by GetAppName() |
97 | is that this one is meant to be shown to the user and so should be used | |
98 | for the window titles, page headers and so on while the other one | |
99 | should be only used internally, e.g. for the file names or | |
100 | configuration file keys. By default, returns the application name as | |
101 | returned by GetAppName() capitalized using wxString::Capitalize(). | |
3c4f71cc | 102 | |
1e24c2af | 103 | @since 2.9.0 |
23324ae1 | 104 | */ |
328f5751 | 105 | wxString GetAppDisplayName() const; |
23324ae1 FM |
106 | |
107 | /** | |
108 | Returns the application name. | |
3c4f71cc | 109 | |
23324ae1 | 110 | @remarks wxWidgets sets this to a reasonable default before calling |
4cc4bfaf | 111 | OnInit(), but the application can reset it at will. |
3c4f71cc | 112 | |
4cc4bfaf | 113 | @see GetAppDisplayName() |
23324ae1 | 114 | */ |
328f5751 | 115 | wxString GetAppName() const; |
23324ae1 FM |
116 | |
117 | /** | |
118 | Gets the class name of the application. The class name may be used in a | |
96d7cc9b | 119 | platform specific manner to refer to the application. |
3c4f71cc | 120 | |
4cc4bfaf | 121 | @see SetClassName() |
23324ae1 | 122 | */ |
328f5751 | 123 | wxString GetClassName() const; |
23324ae1 | 124 | |
23324ae1 FM |
125 | /** |
126 | Returns the one and only global application object. | |
fac938f8 | 127 | Usually wxTheApp is used instead. |
3c4f71cc | 128 | |
4cc4bfaf | 129 | @see SetInstance() |
23324ae1 | 130 | */ |
4cc4bfaf | 131 | static wxAppConsole* GetInstance(); |
23324ae1 | 132 | |
23324ae1 FM |
133 | /** |
134 | Returns a pointer to the wxAppTraits object for the application. | |
135 | If you want to customize the wxAppTraits object, you must override the | |
136 | CreateTraits() function. | |
137 | */ | |
4cc4bfaf | 138 | wxAppTraits* GetTraits(); |
23324ae1 | 139 | |
23324ae1 FM |
140 | /** |
141 | Returns the user-readable vendor name. The difference between this string | |
96d7cc9b FM |
142 | and the one returned by GetVendorName() is that this one is meant to be shown |
143 | to the user and so should be used for the window titles, page headers and so on | |
144 | while the other one should be only used internally, e.g. for the file names or | |
145 | configuration file keys. | |
146 | ||
23324ae1 | 147 | By default, returns the same string as GetVendorName(). |
3c4f71cc | 148 | |
1e24c2af | 149 | @since 2.9.0 |
23324ae1 | 150 | */ |
8064223b | 151 | const wxString& GetVendorDisplayName() const; |
23324ae1 FM |
152 | |
153 | /** | |
154 | Returns the application's vendor name. | |
155 | */ | |
8064223b | 156 | const wxString& GetVendorName() const; |
23324ae1 FM |
157 | |
158 | /** | |
4cc4bfaf FM |
159 | This function simply invokes the given method @a func of the specified |
160 | event handler @a handler with the @a event as parameter. It exists solely | |
23324ae1 | 161 | to allow to catch the C++ exceptions which could be thrown by all event |
96d7cc9b FM |
162 | handlers in the application in one place: if you want to do this, override |
163 | this function in your wxApp-derived class and add try/catch clause(s) to it. | |
23324ae1 | 164 | */ |
8064223b | 165 | virtual void HandleEvent(wxEvtHandler* handler, |
23324ae1 | 166 | wxEventFunction func, |
328f5751 | 167 | wxEvent& event) const; |
23324ae1 | 168 | |
23324ae1 FM |
169 | /** |
170 | Returns @true if the main event loop is currently running, i.e. if the | |
171 | application is inside OnRun(). | |
96d7cc9b | 172 | |
23324ae1 FM |
173 | This can be useful to test whether events can be dispatched. For example, |
174 | if this function returns @false, non-blocking sockets cannot be used because | |
175 | the events from them would never be processed. | |
176 | */ | |
177 | static bool IsMainLoopRunning(); | |
178 | ||
d181e877 FM |
179 | /** |
180 | Returns @true if called from inside Yield(). | |
181 | */ | |
182 | bool IsYielding() const; | |
183 | ||
f045c7f5 FM |
184 | /** |
185 | Process all pending events; it is necessary to call this function to | |
186 | process posted events. | |
187 | ||
188 | This happens during each event loop iteration in GUI mode but if there is | |
189 | no main loop, it may be also called directly. | |
190 | */ | |
191 | virtual void ProcessPendingEvents(); | |
192 | ||
23324ae1 | 193 | /** |
d9faa1fe | 194 | Called in response of an "open-application" Apple event. |
23324ae1 | 195 | Override this to create a new document in your app. |
d9faa1fe FM |
196 | |
197 | @onlyfor{wxmac} | |
23324ae1 | 198 | */ |
8064223b | 199 | virtual void MacNewFile(); |
23324ae1 FM |
200 | |
201 | /** | |
d9faa1fe | 202 | Called in response of an "open-document" Apple event. |
96d7cc9b FM |
203 | |
204 | You need to override this method in order to open a document file after the | |
205 | user double clicked on it or if the document file was dropped on either the | |
206 | running application or the application icon in Finder. | |
d9faa1fe FM |
207 | |
208 | @onlyfor{wxmac} | |
23324ae1 | 209 | */ |
8064223b | 210 | virtual void MacOpenFile(const wxString& fileName); |
23324ae1 FM |
211 | |
212 | /** | |
d9faa1fe FM |
213 | Called in response of a "get-url" Apple event. |
214 | ||
215 | @onlyfor{wxmac} | |
23324ae1 | 216 | */ |
8064223b | 217 | virtual void MacOpenURL(const wxString& url); |
23324ae1 FM |
218 | |
219 | /** | |
d9faa1fe FM |
220 | Called in response of a "print-document" Apple event. |
221 | ||
222 | @onlyfor{wxmac} | |
23324ae1 | 223 | */ |
8064223b | 224 | virtual void MacPrintFile(const wxString& fileName); |
23324ae1 FM |
225 | |
226 | /** | |
d9faa1fe FM |
227 | Called in response of a "reopen-application" Apple event. |
228 | ||
229 | @onlyfor{wxmac} | |
23324ae1 | 230 | */ |
8064223b | 231 | virtual void MacReopenApp(); |
23324ae1 FM |
232 | |
233 | /** | |
234 | Called by wxWidgets on creation of the application. Override this if you wish | |
235 | to provide your own (environment-dependent) main loop. | |
3c4f71cc | 236 | |
d29a9a8a | 237 | @return 0 under X, and the wParam of the WM_QUIT message under Windows. |
23324ae1 FM |
238 | */ |
239 | virtual int MainLoop(); | |
240 | ||
241 | /** | |
242 | This function is called when an assert failure occurs, i.e. the condition | |
e54c96f1 | 243 | specified in wxASSERT() macro evaluated to @false. |
96d7cc9b | 244 | |
23324ae1 FM |
245 | It is only called in debug mode (when @c __WXDEBUG__ is defined) as |
246 | asserts are not left in the release code at all. | |
23324ae1 FM |
247 | The base class version shows the default assert failure dialog box proposing to |
248 | the user to stop the program, continue or ignore all subsequent asserts. | |
3c4f71cc | 249 | |
7c913512 | 250 | @param file |
4cc4bfaf | 251 | the name of the source file where the assert occurred |
7c913512 | 252 | @param line |
4cc4bfaf | 253 | the line number in this file where the assert occurred |
7c913512 | 254 | @param func |
4cc4bfaf FM |
255 | the name of the function where the assert occurred, may be |
256 | empty if the compiler doesn't support C99 __FUNCTION__ | |
7c913512 | 257 | @param cond |
4cc4bfaf | 258 | the condition of the failed assert in text form |
7c913512 | 259 | @param msg |
96d7cc9b FM |
260 | the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will |
261 | be @NULL if just wxASSERT or wxFAIL was used | |
23324ae1 | 262 | */ |
8d483c9b FM |
263 | virtual void OnAssertFailure(const wxChar *file, |
264 | int line, | |
265 | const wxChar *func, | |
266 | const wxChar *cond, | |
267 | const wxChar *msg); | |
23324ae1 FM |
268 | |
269 | /** | |
270 | Called when command line parsing fails (i.e. an incorrect command line option | |
271 | was specified by the user). The default behaviour is to show the program usage | |
272 | text and abort the program. | |
96d7cc9b | 273 | |
7c913512 | 274 | Return @true to continue normal execution or @false to return |
23324ae1 | 275 | @false from OnInit() thus terminating the program. |
3c4f71cc | 276 | |
4cc4bfaf | 277 | @see OnInitCmdLine() |
23324ae1 | 278 | */ |
8064223b | 279 | virtual bool OnCmdLineError(wxCmdLineParser& parser); |
23324ae1 FM |
280 | |
281 | /** | |
282 | Called when the help option (@c --help) was specified on the command line. | |
283 | The default behaviour is to show the program usage text and abort the program. | |
96d7cc9b | 284 | |
7c913512 | 285 | Return @true to continue normal execution or @false to return |
23324ae1 | 286 | @false from OnInit() thus terminating the program. |
3c4f71cc | 287 | |
4cc4bfaf | 288 | @see OnInitCmdLine() |
23324ae1 | 289 | */ |
8064223b | 290 | virtual bool OnCmdLineHelp(wxCmdLineParser& parser); |
23324ae1 FM |
291 | |
292 | /** | |
293 | Called after the command line had been successfully parsed. You may override | |
294 | this method to test for the values of the various parameters which could be | |
295 | set from the command line. | |
96d7cc9b | 296 | |
23324ae1 FM |
297 | Don't forget to call the base class version unless you want to suppress |
298 | processing of the standard command line options. | |
96d7cc9b FM |
299 | Return @true to continue normal execution or @false to return @false from |
300 | OnInit() thus terminating the program. | |
3c4f71cc | 301 | |
4cc4bfaf | 302 | @see OnInitCmdLine() |
23324ae1 | 303 | */ |
8064223b | 304 | virtual bool OnCmdLineParsed(wxCmdLineParser& parser); |
23324ae1 FM |
305 | |
306 | /** | |
307 | This function is called if an unhandled exception occurs inside the main | |
308 | application event loop. It can return @true to ignore the exception and to | |
309 | continue running the loop or @false to exit the loop and terminate the | |
310 | program. In the latter case it can also use C++ @c throw keyword to | |
311 | rethrow the current exception. | |
96d7cc9b | 312 | |
23324ae1 FM |
313 | The default behaviour of this function is the latter in all ports except under |
314 | Windows where a dialog is shown to the user which allows him to choose between | |
315 | the different options. You may override this function in your class to do | |
316 | something more appropriate. | |
96d7cc9b | 317 | |
7c913512 | 318 | Finally note that if the exception is rethrown from here, it can be caught in |
23324ae1 FM |
319 | OnUnhandledException(). |
320 | */ | |
321 | virtual bool OnExceptionInMainLoop(); | |
322 | ||
323 | /** | |
324 | Override this member function for any processing which needs to be | |
325 | done as the application is about to exit. OnExit is called after | |
326 | destroying all application windows and controls, but before | |
7c913512 | 327 | wxWidgets cleanup. Note that it is not called at all if |
23324ae1 | 328 | OnInit() failed. |
96d7cc9b FM |
329 | |
330 | The return value of this function is currently ignored, return the same | |
331 | value as returned by the base class method if you override it. | |
23324ae1 FM |
332 | */ |
333 | virtual int OnExit(); | |
334 | ||
335 | /** | |
336 | This function may be called if something fatal happens: an unhandled | |
337 | exception under Win32 or a a fatal signal under Unix, for example. However, | |
7c913512 | 338 | this will not happen by default: you have to explicitly call |
e54c96f1 | 339 | wxHandleFatalExceptions() to enable this. |
96d7cc9b | 340 | |
23324ae1 FM |
341 | Generally speaking, this function should only show a message to the user and |
342 | return. You may attempt to save unsaved data but this is not guaranteed to | |
343 | work and, in fact, probably won't. | |
3c4f71cc | 344 | |
e54c96f1 | 345 | @see wxHandleFatalExceptions() |
23324ae1 | 346 | */ |
8064223b | 347 | virtual void OnFatalException(); |
23324ae1 FM |
348 | |
349 | /** | |
350 | This must be provided by the application, and will usually create the | |
96d7cc9b FM |
351 | application's main window, optionally calling SetTopWindow(). |
352 | ||
353 | You may use OnExit() to clean up anything initialized here, provided | |
23324ae1 | 354 | that the function returns @true. |
96d7cc9b | 355 | |
23324ae1 FM |
356 | Notice that if you want to to use the command line processing provided by |
357 | wxWidgets you have to call the base class version in the derived class | |
358 | OnInit(). | |
96d7cc9b | 359 | |
23324ae1 FM |
360 | Return @true to continue processing, @false to exit the application |
361 | immediately. | |
362 | */ | |
8064223b | 363 | virtual bool OnInit(); |
23324ae1 FM |
364 | |
365 | /** | |
96d7cc9b FM |
366 | Called from OnInit() and may be used to initialize the parser with the |
367 | command line options for this application. The base class versions adds | |
368 | support for a few standard options only. | |
23324ae1 | 369 | */ |
8064223b | 370 | virtual void OnInitCmdLine(wxCmdLineParser& parser); |
23324ae1 FM |
371 | |
372 | /** | |
373 | This virtual function is where the execution of a program written in wxWidgets | |
374 | starts. The default implementation just enters the main loop and starts | |
96d7cc9b FM |
375 | handling the events until it terminates, either because ExitMainLoop() has |
376 | been explicitly called or because the last frame has been deleted and | |
377 | GetExitOnFrameDelete() flag is @true (this is the default). | |
378 | ||
23324ae1 FM |
379 | The return value of this function becomes the exit code of the program, so it |
380 | should return 0 in case of successful termination. | |
381 | */ | |
382 | virtual int OnRun(); | |
383 | ||
384 | /** | |
7c913512 | 385 | This function is called when an unhandled C++ exception occurs inside |
96d7cc9b FM |
386 | OnRun() (the exceptions which occur during the program startup and shutdown |
387 | might not be caught at all). Notice that by now the main event loop has been | |
388 | terminated and the program will exit, if you want to prevent this from happening | |
389 | (i.e. continue running after catching an exception) you need to override | |
390 | OnExceptionInMainLoop(). | |
391 | ||
23324ae1 FM |
392 | The default implementation shows information about the exception in debug build |
393 | but does nothing in the release build. | |
394 | */ | |
395 | virtual void OnUnhandledException(); | |
396 | ||
397 | /** | |
398 | Returns @true if unprocessed events are in the window system event queue. | |
3c4f71cc | 399 | |
4cc4bfaf | 400 | @see Dispatch() |
23324ae1 FM |
401 | */ |
402 | virtual bool Pending(); | |
403 | ||
8064223b | 404 | /** |
328fafa1 VZ |
405 | Set the application name to be used in the user-visible places such as |
406 | window titles. | |
407 | ||
408 | See GetAppDisplayName() for more about the differences between the | |
8064223b | 409 | display name and name. |
328fafa1 VZ |
410 | |
411 | Notice that if this function is called, the name is used as is, without | |
412 | any capitalization as done by default by GetAppDisplayName(). | |
8064223b FM |
413 | */ |
414 | void SetAppDisplayName(const wxString& name); | |
415 | ||
416 | /** | |
417 | Sets the name of the application. This name should be used for file names, | |
418 | configuration file entries and other internal strings. For the user-visible | |
419 | strings, such as the window titles, the application display name set by | |
420 | SetAppDisplayName() is used instead. | |
421 | ||
422 | By default the application name is set to the name of its executable file. | |
423 | ||
424 | @see GetAppName() | |
425 | */ | |
426 | void SetAppName(const wxString& name); | |
427 | ||
428 | /** | |
429 | Sets the class name of the application. This may be used in a platform specific | |
430 | manner to refer to the application. | |
431 | ||
432 | @see GetClassName() | |
433 | */ | |
434 | void SetClassName(const wxString& name); | |
435 | ||
436 | /** | |
437 | Allows external code to modify global ::wxTheApp, but you should really | |
438 | know what you're doing if you call it. | |
439 | ||
440 | @param app | |
441 | Replacement for the global application object. | |
442 | ||
443 | @see GetInstance() | |
444 | */ | |
445 | static void SetInstance(wxAppConsole* app); | |
446 | ||
447 | /** | |
448 | Set the vendor name to be used in the user-visible places. | |
449 | See GetVendorDisplayName() for more about the differences between the | |
450 | display name and name. | |
451 | */ | |
452 | void SetVendorDisplayName(const wxString& name); | |
453 | ||
454 | /** | |
455 | Sets the name of application's vendor. The name will be used | |
456 | in registry access. A default name is set by wxWidgets. | |
457 | ||
458 | @see GetVendorName() | |
459 | */ | |
460 | void SetVendorName(const wxString& name); | |
461 | ||
462 | /** | |
463 | Yields control to pending messages in the windowing system. | |
464 | ||
465 | This can be useful, for example, when a time-consuming process writes to a | |
466 | text window. Without an occasional yield, the text window will not be updated | |
467 | properly, and on systems with cooperative multitasking, such as Windows 3.1 | |
468 | other processes will not respond. | |
469 | ||
470 | Caution should be exercised, however, since yielding may allow the | |
471 | user to perform actions which are not compatible with the current task. | |
472 | Disabling menu items or whole menus during processing can avoid unwanted | |
473 | reentrance of code: see ::wxSafeYield for a better function. | |
d181e877 | 474 | You can avoid unwanted reentrancies also using IsYielding(). |
8064223b FM |
475 | |
476 | Note that Yield() will not flush the message logs. This is intentional as | |
477 | calling Yield() is usually done to quickly update the screen and popping up | |
478 | a message box dialog may be undesirable. If you do wish to flush the log | |
479 | messages immediately (otherwise it will be done during the next idle loop | |
480 | iteration), call wxLog::FlushActive. | |
481 | ||
482 | Calling Yield() recursively is normally an error and an assert failure is | |
483 | raised in debug build if such situation is detected. However if the | |
484 | @a onlyIfNeeded parameter is @true, the method will just silently | |
485 | return @false instead. | |
486 | */ | |
487 | virtual bool Yield(bool onlyIfNeeded = false); | |
488 | ||
489 | /** | |
490 | Number of command line arguments (after environment-specific processing). | |
491 | */ | |
492 | int argc; | |
493 | ||
494 | /** | |
495 | Command line arguments (after environment-specific processing). | |
496 | ||
497 | Under Windows and Linux/Unix, you should parse the command line | |
498 | arguments and check for files to be opened when starting your | |
499 | application. Under OS X, you need to override MacOpenFile() | |
500 | since command line arguments are used differently there. | |
501 | ||
502 | You may use the wxCmdLineParser to parse command line arguments. | |
503 | */ | |
504 | wxChar** argv; | |
505 | }; | |
506 | ||
507 | ||
508 | ||
509 | ||
510 | /** | |
511 | @class wxApp | |
8064223b | 512 | |
f045c7f5 | 513 | The wxApp class represents the application itself when @c wxUSE_GUI=1. |
8064223b | 514 | |
f045c7f5 FM |
515 | In addition to the features provided by wxAppConsole it keeps track of |
516 | the <em>top window</em> (see SetTopWindow()) and adds support for | |
517 | video modes (see SetVideoMode()). | |
8064223b | 518 | |
f045c7f5 | 519 | In general, application-wide settings for GUI-only apps are accessible |
84094285 | 520 | from wxApp (or from wxSystemSettings or wxSystemOptions classes). |
8064223b FM |
521 | |
522 | @library{wxbase} | |
523 | @category{appmanagement} | |
524 | ||
84094285 | 525 | @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings |
8064223b FM |
526 | */ |
527 | class wxApp : public wxAppConsole | |
528 | { | |
529 | public: | |
530 | /** | |
531 | Constructor. Called implicitly with a definition of a wxApp object. | |
532 | */ | |
533 | wxApp(); | |
534 | ||
535 | /** | |
536 | Destructor. Will be called implicitly on program exit if the wxApp | |
537 | object is created on the stack. | |
538 | */ | |
539 | virtual ~wxApp(); | |
540 | ||
f045c7f5 FM |
541 | /** |
542 | Get display mode that is used use. This is only used in framebuffer | |
543 | wxWin ports (such as wxMGL or wxDFB). | |
544 | */ | |
545 | virtual wxVideoMode GetDisplayMode() const; | |
546 | ||
8064223b FM |
547 | /** |
548 | Returns @true if the application will exit when the top-level frame is deleted. | |
549 | ||
550 | @see SetExitOnFrameDelete() | |
551 | */ | |
552 | bool GetExitOnFrameDelete() const; | |
553 | ||
f045c7f5 FM |
554 | /** |
555 | Return the layout direction for the current locale or @c wxLayout_Default | |
556 | if it's unknown. | |
557 | */ | |
558 | virtual wxLayoutDirection GetLayoutDirection() const; | |
559 | ||
8064223b FM |
560 | /** |
561 | Returns @true if the application will use the best visual on systems that support | |
562 | different visuals, @false otherwise. | |
563 | ||
564 | @see SetUseBestVisual() | |
565 | */ | |
566 | bool GetUseBestVisual() const; | |
567 | ||
568 | /** | |
569 | Returns a pointer to the top window. | |
570 | ||
afc31d8a FM |
571 | @remarks |
572 | If the top window hasn't been set using SetTopWindow(), this function | |
573 | will find the first top-level window (frame or dialog or instance of | |
574 | wxTopLevelWindow) from the internal top level window list and return that. | |
8064223b FM |
575 | |
576 | @see SetTopWindow() | |
577 | */ | |
578 | virtual wxWindow* GetTopWindow() const; | |
579 | ||
580 | /** | |
581 | Returns @true if the application is active, i.e. if one of its windows is | |
582 | currently in the foreground. | |
583 | ||
584 | If this function returns @false and you need to attract users attention to | |
585 | the application, you may use wxTopLevelWindow::RequestUserAttention to do it. | |
586 | */ | |
8d483c9b | 587 | virtual bool IsActive() const; |
8064223b | 588 | |
23324ae1 | 589 | /** |
96d7cc9b FM |
590 | Windows-only function for processing a message. This function is called |
591 | from the main message loop, checking for windows that may wish to process it. | |
592 | ||
593 | The function returns @true if the message was processed, @false otherwise. | |
594 | If you use wxWidgets with another class library with its own message loop, | |
595 | you should make sure that this function is called to allow wxWidgets to | |
3c4f71cc | 596 | receive messages. For example, to allow co-existence with the Microsoft |
96d7cc9b | 597 | Foundation Classes, override the PreTranslateMessage function: |
3c4f71cc | 598 | |
96d7cc9b FM |
599 | @code |
600 | // Provide wxWidgets message loop compatibility | |
601 | BOOL CTheApp::PreTranslateMessage(MSG *msg) | |
602 | { | |
603 | if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg)) | |
604 | return true; | |
605 | else | |
606 | return CWinApp::PreTranslateMessage(msg); | |
607 | } | |
608 | @endcode | |
d9faa1fe FM |
609 | |
610 | @onlyfor{wxmsw} | |
23324ae1 | 611 | */ |
4cc4bfaf | 612 | bool ProcessMessage(WXMSG* msg); |
23324ae1 FM |
613 | |
614 | /** | |
615 | Sends idle events to a window and its children. | |
23324ae1 FM |
616 | Please note that this function is internal to wxWidgets and shouldn't be used |
617 | by user code. | |
3c4f71cc | 618 | |
23324ae1 | 619 | @remarks These functions poll the top-level windows, and their children, |
96d7cc9b FM |
620 | for idle event processing. If @true is returned, more OnIdle |
621 | processing is requested by one or more window. | |
3c4f71cc | 622 | |
4cc4bfaf | 623 | @see wxIdleEvent |
23324ae1 | 624 | */ |
8d483c9b | 625 | virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); |
23324ae1 | 626 | |
f045c7f5 FM |
627 | /** |
628 | Set display mode to use. This is only used in framebuffer wxWin | |
629 | ports (such as wxMGL or wxDFB). This method should be called from | |
630 | wxApp::OnInitGui. | |
631 | */ | |
632 | virtual bool SetDisplayMode(const wxVideoMode& info); | |
633 | ||
23324ae1 FM |
634 | /** |
635 | Allows the programmer to specify whether the application will exit when the | |
636 | top-level frame is deleted. | |
3c4f71cc | 637 | |
7c913512 | 638 | @param flag |
96d7cc9b FM |
639 | If @true (the default), the application will exit when the top-level frame |
640 | is deleted. If @false, the application will continue to run. | |
3c4f71cc | 641 | |
96d7cc9b | 642 | @see GetExitOnFrameDelete(), @ref overview_app_shutdown |
23324ae1 FM |
643 | */ |
644 | void SetExitOnFrameDelete(bool flag); | |
645 | ||
646 | /** | |
96d7cc9b | 647 | Allows external code to modify global ::wxTheApp, but you should really |
23324ae1 | 648 | know what you're doing if you call it. |
3c4f71cc | 649 | |
7c913512 | 650 | @param app |
4cc4bfaf | 651 | Replacement for the global application object. |
3c4f71cc | 652 | |
4cc4bfaf | 653 | @see GetInstance() |
23324ae1 FM |
654 | */ |
655 | static void SetInstance(wxAppConsole* app); | |
656 | ||
657 | /** | |
96d7cc9b FM |
658 | Allows runtime switching of the UI environment theme. |
659 | ||
660 | Currently implemented for wxGTK2-only. | |
23324ae1 | 661 | Return @true if theme was successfully changed. |
3c4f71cc | 662 | |
7c913512 | 663 | @param theme |
4cc4bfaf | 664 | The name of the new theme or an absolute path to a gtkrc-theme-file |
23324ae1 | 665 | */ |
8064223b | 666 | virtual bool SetNativeTheme(const wxString& theme); |
23324ae1 FM |
667 | |
668 | /** | |
96d7cc9b FM |
669 | Sets the 'top' window. You can call this from within OnInit() to let wxWidgets |
670 | know which is the main window. You don't have to set the top window; | |
23324ae1 | 671 | it is only a convenience so that (for example) certain dialogs without parents |
afc31d8a FM |
672 | can use a specific window as the top window. |
673 | ||
674 | If no top window is specified by the application, wxWidgets just uses the | |
675 | first frame or dialog (or better, any wxTopLevelWindow) in its top-level | |
676 | window list, when it needs to use the top window. | |
677 | If you previously called SetTopWindow() and now you need to restore this | |
678 | automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode. | |
3c4f71cc | 679 | |
7c913512 | 680 | @param window |
4cc4bfaf | 681 | The new top window. |
3c4f71cc | 682 | |
4cc4bfaf | 683 | @see GetTopWindow(), OnInit() |
23324ae1 FM |
684 | */ |
685 | void SetTopWindow(wxWindow* window); | |
686 | ||
687 | /** | |
688 | Allows the programmer to specify whether the application will use the best | |
96d7cc9b FM |
689 | visual on systems that support several visual on the same display. This is typically |
690 | the case under Solaris and IRIX, where the default visual is only 8-bit whereas | |
691 | certain applications are supposed to run in TrueColour mode. | |
692 | ||
693 | Note that this function has to be called in the constructor of the wxApp | |
23324ae1 | 694 | instance and won't have any effect when called later on. |
23324ae1 | 695 | This function currently only has effect under GTK. |
3c4f71cc | 696 | |
7c913512 | 697 | @param flag |
4cc4bfaf | 698 | If @true, the app will use the best visual. |
96d7cc9b FM |
699 | @param forceTrueColour |
700 | If @true then the application will try to force using a TrueColour | |
701 | visual and abort the app if none is found. | |
23324ae1 | 702 | */ |
4cc4bfaf | 703 | void SetUseBestVisual(bool flag, bool forceTrueColour = false); |
23324ae1 FM |
704 | }; |
705 | ||
706 | ||
e54c96f1 | 707 | |
23324ae1 FM |
708 | // ============================================================================ |
709 | // Global functions/macros | |
710 | // ============================================================================ | |
711 | ||
23324ae1 | 712 | |
8af7f7c1 BP |
713 | /** @ingroup group_funcmacro_rtti */ |
714 | //@{ | |
23324ae1 FM |
715 | |
716 | /** | |
f045c7f5 | 717 | This is used in headers to create a forward declaration of the ::wxGetApp() |
8af7f7c1 | 718 | function implemented by IMPLEMENT_APP(). |
96d7cc9b | 719 | |
eea9220d | 720 | It creates the declaration <tt>className& wxGetApp()</tt>. |
8af7f7c1 BP |
721 | |
722 | @header{wx/app.h} | |
723 | ||
23324ae1 | 724 | Example: |
4cc4bfaf | 725 | |
23324ae1 | 726 | @code |
8af7f7c1 | 727 | DECLARE_APP(MyApp) |
23324ae1 FM |
728 | @endcode |
729 | */ | |
7baebf86 | 730 | #define DECLARE_APP( className ) |
23324ae1 FM |
731 | |
732 | /** | |
96d7cc9b FM |
733 | This is used in the application class implementation file to make the |
734 | application class known to wxWidgets for dynamic construction. | |
8af7f7c1 BP |
735 | |
736 | @header{wx/app.h} | |
737 | ||
96d7cc9b FM |
738 | Example: |
739 | ||
740 | @code | |
741 | IMPLEMENT_APP(MyApp) | |
742 | @endcode | |
743 | ||
8af7f7c1 BP |
744 | @see DECLARE_APP(). |
745 | */ | |
7baebf86 | 746 | #define IMPLEMENT_APP( className ) |
8af7f7c1 BP |
747 | |
748 | //@} | |
749 | ||
750 | ||
751 | ||
8cd06fb5 BP |
752 | /** |
753 | The global pointer to the singleton wxApp object. | |
754 | ||
755 | @see wxApp::GetInstance() | |
756 | */ | |
757 | wxApp *wxTheApp; | |
758 | ||
759 | ||
760 | ||
39fb8056 FM |
761 | /** @ingroup group_funcmacro_appinitterm */ |
762 | //@{ | |
23324ae1 | 763 | |
23324ae1 | 764 | /** |
8cd06fb5 BP |
765 | This function doesn't exist in wxWidgets but it is created by using the |
766 | IMPLEMENT_APP() macro. | |
96d7cc9b | 767 | |
39fb8056 FM |
768 | Thus, before using it anywhere but in the same module where this macro is |
769 | used, you must make it available using DECLARE_APP(). | |
96d7cc9b FM |
770 | |
771 | The advantage of using this function compared to directly using the global | |
8cd06fb5 BP |
772 | ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't |
773 | allow you to access the functions specific to your application class but | |
774 | not present in wxApp while wxGetApp() returns the object of the right type. | |
027c1c27 BP |
775 | |
776 | @header{wx/app.h} | |
23324ae1 | 777 | */ |
8cd06fb5 | 778 | wxAppDerivedClass& wxGetApp(); |
23324ae1 | 779 | |
23324ae1 | 780 | /** |
4cc4bfaf | 781 | If @a doIt is @true, the fatal exceptions (also known as general protection |
23324ae1 FM |
782 | faults under Windows or segmentation violations in the Unix world) will be |
783 | caught and passed to wxApp::OnFatalException. | |
96d7cc9b | 784 | |
8cd06fb5 BP |
785 | By default, i.e. before this function is called, they will be handled in |
786 | the normal way which usually just means that the application will be | |
787 | terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false | |
788 | will restore this default behaviour. | |
4cc4bfaf | 789 | |
8cd06fb5 BP |
790 | Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION |
791 | is 1 and under Windows platform this requires a compiler with support for | |
792 | SEH (structured exception handling) which currently means only Microsoft | |
793 | Visual C++ or a recent Borland C++ version. | |
027c1c27 BP |
794 | |
795 | @header{wx/app.h} | |
23324ae1 | 796 | */ |
96d7cc9b | 797 | bool wxHandleFatalExceptions(bool doIt = true); |
23324ae1 | 798 | |
23324ae1 FM |
799 | /** |
800 | This function is used in wxBase only and only if you don't create | |
801 | wxApp object at all. In this case you must call it from your | |
802 | @c main() function before calling any other wxWidgets functions. | |
96d7cc9b | 803 | |
23324ae1 | 804 | If the function returns @false the initialization could not be performed, |
96d7cc9b FM |
805 | in this case the library cannot be used and wxUninitialize() shouldn't be |
806 | called neither. | |
807 | ||
808 | This function may be called several times but wxUninitialize() must be | |
809 | called for each successful call to this function. | |
027c1c27 BP |
810 | |
811 | @header{wx/app.h} | |
23324ae1 FM |
812 | */ |
813 | bool wxInitialize(); | |
814 | ||
815 | /** | |
96d7cc9b FM |
816 | This function is for use in console (wxBase) programs only. It must be called |
817 | once for each previous successful call to wxInitialize(). | |
027c1c27 BP |
818 | |
819 | @header{wx/app.h} | |
23324ae1 | 820 | */ |
96d7cc9b | 821 | void wxUninitialize(); |
23324ae1 | 822 | |
8cd06fb5 BP |
823 | /** |
824 | This function wakes up the (internal and platform dependent) idle system, | |
825 | i.e. it will force the system to send an idle event even if the system | |
826 | currently @e is idle and thus would not send any idle event until after | |
827 | some other event would get sent. This is also useful for sending events | |
828 | between two threads and is used by the corresponding functions | |
829 | wxPostEvent() and wxEvtHandler::AddPendingEvent(). | |
027c1c27 BP |
830 | |
831 | @header{wx/app.h} | |
8cd06fb5 BP |
832 | */ |
833 | void wxWakeUpIdle(); | |
834 | ||
23324ae1 FM |
835 | /** |
836 | Calls wxApp::Yield. | |
96d7cc9b FM |
837 | |
838 | @deprecated | |
23324ae1 FM |
839 | This function is kept only for backwards compatibility. Please use |
840 | the wxApp::Yield method instead in any new code. | |
027c1c27 BP |
841 | |
842 | @header{wx/app.h} | |
23324ae1 FM |
843 | */ |
844 | bool wxYield(); | |
845 | ||
39fb8056 | 846 | /** |
c933f8f8 FM |
847 | This function is similar to wxYield(), except that it disables the user |
848 | input to all program windows before calling wxYield() and re-enables it | |
849 | again afterwards. If @a win is not @NULL, this window will remain enabled, | |
39fb8056 FM |
850 | allowing the implementation of some limited user interaction. |
851 | Returns the result of the call to ::wxYield. | |
027c1c27 BP |
852 | |
853 | @header{wx/app.h} | |
39fb8056 FM |
854 | */ |
855 | bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false); | |
23324ae1 | 856 | |
23324ae1 | 857 | /** |
39fb8056 FM |
858 | This function initializes wxWidgets in a platform-dependent way. Use this if you |
859 | are not using the default wxWidgets entry code (e.g. main or WinMain). | |
7c913512 | 860 | |
39fb8056 FM |
861 | For example, you can initialize wxWidgets from an Microsoft Foundation Classes |
862 | (MFC) application using this function. | |
863 | ||
864 | @note This overload of wxEntry is available under all platforms. | |
865 | ||
866 | @see wxEntryStart() | |
027c1c27 BP |
867 | |
868 | @header{wx/app.h} | |
39fb8056 FM |
869 | */ |
870 | int wxEntry(int& argc, wxChar** argv); | |
871 | ||
872 | /** | |
873 | See wxEntry(int&,wxChar**) for more info about this function. | |
874 | ||
875 | Notice that under Windows CE platform, and only there, the type of @a pCmdLine | |
876 | is @c wchar_t *, otherwise it is @c char *, even in Unicode build. | |
7c913512 | 877 | |
23324ae1 | 878 | @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static |
96d7cc9b FM |
879 | function wxApp::CleanUp. For example, if exiting from an MFC application |
880 | that also uses wxWidgets: | |
881 | @code | |
882 | int CTheApp::ExitInstance() | |
883 | { | |
884 | // OnExit isn't called by CleanUp so must be called explicitly. | |
885 | wxTheApp->OnExit(); | |
886 | wxApp::CleanUp(); | |
3c4f71cc | 887 | |
96d7cc9b FM |
888 | return CWinApp::ExitInstance(); |
889 | } | |
890 | @endcode | |
7c913512 | 891 | |
027c1c27 | 892 | @header{wx/app.h} |
23324ae1 | 893 | */ |
7c913512 | 894 | int wxEntry(HINSTANCE hInstance, |
4cc4bfaf FM |
895 | HINSTANCE hPrevInstance = NULL, |
896 | char* pCmdLine = NULL, | |
7c913512 | 897 | int nCmdShow = SW_SHOWNORMAL); |
39fb8056 FM |
898 | |
899 | //@} | |
900 | ||
901 | ||
902 | ||
903 | /** @ingroup group_funcmacro_procctrl */ | |
904 | //@{ | |
905 | ||
906 | /** | |
907 | Exits application after calling wxApp::OnExit. | |
908 | ||
909 | Should only be used in an emergency: normally the top-level frame | |
910 | should be deleted (after deleting all other frames) to terminate the | |
911 | application. See wxCloseEvent and wxApp. | |
027c1c27 BP |
912 | |
913 | @header{wx/app.h} | |
39fb8056 FM |
914 | */ |
915 | void wxExit(); | |
916 | ||
23324ae1 FM |
917 | //@} |
918 |