X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..413eac73fd4e207a46f94821dd47feac3da7c287:/interface/wx/app.h
diff --git a/interface/wx/app.h b/interface/wx/app.h
index cf79e46a12..893ee20c6c 100644
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -9,17 +9,33 @@
/**
@class wxAppConsole
- @wxheader{app.h}
This class is essential for writing console-only or hybrid apps without
- having to define wxUSE_GUI=0.
+ having to define @c wxUSE_GUI=0.
+
+ It is used to:
+ @li set and get application-wide properties (see wxAppConsole::CreateTraits
+ and wxAppConsole::SetXXX functions)
+ @li implement the windowing system message or event loop: events in fact are
+ supported even in console-mode applications (see wxAppConsole::HandleEvent
+ and wxAppConsole::ProcessPendingEvents);
+ @li initiate application processing via wxApp::OnInit;
+ @li allow default processing of events not handled by other
+ objects in the application (see wxAppConsole::FilterEvent)
+ @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
+
+ You should use the macro IMPLEMENT_APP(appClass) in your application
+ implementation file to tell wxWidgets how to create an instance of your
+ application class.
- @todo MORE INFO
+ Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
+ (which returns a reference to your application object) to be visible to other
+ files.
@library{wxbase}
@category{appmanagement}
- @see @ref overview_app
+ @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
*/
class wxAppConsole : public wxEvtHandler
{
@@ -38,6 +54,12 @@ public:
*/
virtual ~wxAppConsole();
+
+ /**
+ @name Event-handling
+ */
+ //@{
+
/**
Dispatches the next event in the windowing system event queue.
Blocks until an event appears if there are none currently
@@ -52,7 +74,7 @@ public:
@return @false if the event loop should stop and @true otherwise.
- @see Pending()
+ @see Pending(), wxEventLoopBase
*/
virtual bool Dispatch();
@@ -74,80 +96,95 @@ public:
*/
virtual int FilterEvent(wxEvent& event);
- /**
- Returns the user-readable application name.
-
- The difference between this string and the one returned by GetAppName() is that
- this one is meant to be shown to the user and so should be used for the window
- titles, page headers and so on while the other one should be only used internally,
- e.g. for the file names or configuration file keys.
- By default, returns the same string as GetAppName().
- @since 2.9.0
+ /**
+ This function simply invokes the given method @a func of the specified
+ event handler @a handler with the @a event as parameter. It exists solely
+ to allow to catch the C++ exceptions which could be thrown by all event
+ handlers in the application in one place: if you want to do this, override
+ this function in your wxApp-derived class and add try/catch clause(s) to it.
*/
- wxString GetAppDisplayName() const;
+ virtual void HandleEvent(wxEvtHandler* handler,
+ wxEventFunction func,
+ wxEvent& event) const;
/**
- Returns the application name.
-
- @remarks wxWidgets sets this to a reasonable default before calling
- OnInit(), but the application can reset it at will.
-
- @see GetAppDisplayName()
+ Returns @true if called from inside Yield().
*/
- wxString GetAppName() const;
+ virtual bool IsYielding() const;
/**
- Gets the class name of the application. The class name may be used in a
- platform specific manner to refer to the application.
+ Process all pending events; it is necessary to call this function to
+ process posted events.
- @see SetClassName()
+ This happens during each event loop iteration in GUI mode but if there is
+ no main loop, it may be also called directly.
*/
- wxString GetClassName() const;
+ virtual void ProcessPendingEvents();
/**
- Returns the one and only global application object.
- Usually ::wxTheApp is usead instead.
+ Called by wxWidgets on creation of the application. Override this if you wish
+ to provide your own (environment-dependent) main loop.
- @see SetInstance()
+ @return 0 under X, and the wParam of the WM_QUIT message under Windows.
*/
- static wxAppConsole* GetInstance();
+ virtual int MainLoop();
/**
- Returns a pointer to the wxAppTraits object for the application.
- If you want to customize the wxAppTraits object, you must override the
- CreateTraits() function.
+ Returns @true if unprocessed events are in the window system event queue.
+
+ @see Dispatch()
*/
- wxAppTraits* GetTraits();
+ virtual bool Pending();
/**
- Returns the user-readable vendor name. The difference between this string
- and the one returned by GetVendorName() is that this one is meant to be shown
- to the user and so should be used for the window titles, page headers and so on
- while the other one should be only used internally, e.g. for the file names or
- configuration file keys.
+ Yields control to pending messages in the windowing system.
- By default, returns the same string as GetVendorName().
+ This can be useful, for example, when a time-consuming process writes to a
+ text window. Without an occasional yield, the text window will not be updated
+ properly, and on systems with cooperative multitasking, such as Windows 3.1
+ other processes will not respond.
- @since 2.9.0
+ Caution should be exercised, however, since yielding may allow the
+ user to perform actions which are not compatible with the current task.
+ Disabling menu items or whole menus during processing can avoid unwanted
+ reentrance of code: see ::wxSafeYield for a better function.
+ You can avoid unwanted reentrancies also using IsYielding().
+
+ Note that Yield() will not flush the message logs. This is intentional as
+ calling Yield() is usually done to quickly update the screen and popping up
+ a message box dialog may be undesirable. If you do wish to flush the log
+ messages immediately (otherwise it will be done during the next idle loop
+ iteration), call wxLog::FlushActive.
+
+ Calling Yield() recursively is normally an error and an assert failure is
+ raised in debug build if such situation is detected. However if the
+ @a onlyIfNeeded parameter is @true, the method will just silently
+ return @false instead.
*/
- const wxString& GetVendorDisplayName() const;
+ virtual bool Yield(bool onlyIfNeeded = false);
+
+ //@}
+
/**
- Returns the application's vendor name.
+ Allows external code to modify global ::wxTheApp, but you should really
+ know what you're doing if you call it.
+
+ @param app
+ Replacement for the global application object.
+
+ @see GetInstance()
*/
- const wxString& GetVendorName() const;
+ static void SetInstance(wxAppConsole* app);
/**
- This function simply invokes the given method @a func of the specified
- event handler @a handler with the @a event as parameter. It exists solely
- to allow to catch the C++ exceptions which could be thrown by all event
- handlers in the application in one place: if you want to do this, override
- this function in your wxApp-derived class and add try/catch clause(s) to it.
+ Returns the one and only global application object.
+ Usually wxTheApp is used instead.
+
+ @see SetInstance()
*/
- virtual void HandleEvent(wxEvtHandler* handler,
- wxEventFunction func,
- wxEvent& event) const;
+ static wxAppConsole* GetInstance();
/**
Returns @true if the main event loop is currently running, i.e. if the
@@ -159,6 +196,12 @@ public:
*/
static bool IsMainLoopRunning();
+
+ /**
+ @name Mac-specific functions
+ */
+ //@{
+
/**
Called in response of an "open-application" Apple event.
Override this to create a new document in your app.
@@ -199,13 +242,13 @@ public:
*/
virtual void MacReopenApp();
- /**
- Called by wxWidgets on creation of the application. Override this if you wish
- to provide your own (environment-dependent) main loop.
+ //@}
- @return 0 under X, and the wParam of the WM_QUIT message under Windows.
+
+ /**
+ @name Callbacks for application-wide "events"
*/
- virtual int MainLoop();
+ //@{
/**
This function is called when an assert failure occurs, i.e. the condition
@@ -363,17 +406,80 @@ public:
*/
virtual void OnUnhandledException();
+ //@}
+
+
/**
- Returns @true if unprocessed events are in the window system event queue.
+ @name Application informations
+ */
+ //@{
- @see Dispatch()
+ /**
+ Returns the user-readable application name.
+
+ The difference between this string and the one returned by GetAppName()
+ is that this one is meant to be shown to the user and so should be used
+ for the window titles, page headers and so on while the other one
+ should be only used internally, e.g. for the file names or
+ configuration file keys. By default, returns the application name as
+ returned by GetAppName() capitalized using wxString::Capitalize().
+
+ @since 2.9.0
*/
- virtual bool Pending();
+ wxString GetAppDisplayName() const;
+
+ /**
+ Returns the application name.
+
+ @remarks wxWidgets sets this to a reasonable default before calling
+ OnInit(), but the application can reset it at will.
+
+ @see GetAppDisplayName()
+ */
+ wxString GetAppName() const;
/**
- Set the application name to be used in the user-visible places such as window
- titles. See GetAppDisplayName() for more about the differences between the
+ Gets the class name of the application. The class name may be used in a
+ platform specific manner to refer to the application.
+
+ @see SetClassName()
+ */
+ wxString GetClassName() const;
+
+ /**
+ Returns a pointer to the wxAppTraits object for the application.
+ If you want to customize the wxAppTraits object, you must override the
+ CreateTraits() function.
+ */
+ wxAppTraits* GetTraits();
+
+ /**
+ Returns the user-readable vendor name. The difference between this string
+ and the one returned by GetVendorName() is that this one is meant to be shown
+ to the user and so should be used for the window titles, page headers and so on
+ while the other one should be only used internally, e.g. for the file names or
+ configuration file keys.
+
+ By default, returns the same string as GetVendorName().
+
+ @since 2.9.0
+ */
+ const wxString& GetVendorDisplayName() const;
+
+ /**
+ Returns the application's vendor name.
+ */
+ const wxString& GetVendorName() const;
+
+ /**
+ Set the application name to be used in the user-visible places such as
+ window titles.
+
+ See GetAppDisplayName() for more about the differences between the
display name and name.
+
+ Notice that if this function is called, the name is used as is, without
+ any capitalization as done by default by GetAppDisplayName().
*/
void SetAppDisplayName(const wxString& name);
@@ -397,17 +503,6 @@ public:
*/
void SetClassName(const wxString& name);
- /**
- Allows external code to modify global ::wxTheApp, but you should really
- know what you're doing if you call it.
-
- @param app
- Replacement for the global application object.
-
- @see GetInstance()
- */
- static void SetInstance(wxAppConsole* app);
-
/**
Set the vendor name to be used in the user-visible places.
See GetVendorDisplayName() for more about the differences between the
@@ -423,31 +518,8 @@ public:
*/
void SetVendorName(const wxString& name);
- /**
- Yields control to pending messages in the windowing system.
-
- This can be useful, for example, when a time-consuming process writes to a
- text window. Without an occasional yield, the text window will not be updated
- properly, and on systems with cooperative multitasking, such as Windows 3.1
- other processes will not respond.
-
- Caution should be exercised, however, since yielding may allow the
- user to perform actions which are not compatible with the current task.
- Disabling menu items or whole menus during processing can avoid unwanted
- reentrance of code: see ::wxSafeYield for a better function.
-
- Note that Yield() will not flush the message logs. This is intentional as
- calling Yield() is usually done to quickly update the screen and popping up
- a message box dialog may be undesirable. If you do wish to flush the log
- messages immediately (otherwise it will be done during the next idle loop
- iteration), call wxLog::FlushActive.
+ //@}
- Calling Yield() recursively is normally an error and an assert failure is
- raised in debug build if such situation is detected. However if the
- @a onlyIfNeeded parameter is @true, the method will just silently
- return @false instead.
- */
- virtual bool Yield(bool onlyIfNeeded = false);
/**
Number of command line arguments (after environment-specific processing).
@@ -472,28 +544,20 @@ public:
/**
@class wxApp
- @wxheader{app.h}
- The wxApp class represents the application itself. It is used to:
+ The wxApp class represents the application itself when @c wxUSE_GUI=1.
- @li set and get application-wide properties;
- @li implement the windowing system message or event loop;
- @li initiate application processing via wxApp::OnInit;
- @li allow default processing of events not handled by other
- objects in the application.
-
- You should use the macro IMPLEMENT_APP(appClass) in your application
- implementation file to tell wxWidgets how to create an instance of your
- application class.
+ In addition to the features provided by wxAppConsole it keeps track of
+ the top window (see SetTopWindow()) and adds support for
+ video modes (see SetVideoMode()).
- Use DECLARE_APP(appClass) in a header file if you want the wxGetApp function
- (which returns a reference to your application object) to be visible to other
- files.
+ In general, application-wide settings for GUI-only apps are accessible
+ from wxApp (or from wxSystemSettings or wxSystemOptions classes).
@library{wxbase}
@category{appmanagement}
- @see @ref overview_app
+ @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
*/
class wxApp : public wxAppConsole
{
@@ -509,6 +573,12 @@ public:
*/
virtual ~wxApp();
+ /**
+ Get display mode that is used use. This is only used in framebuffer
+ wxWin ports (such as wxMGL or wxDFB).
+ */
+ virtual wxVideoMode GetDisplayMode() const;
+
/**
Returns @true if the application will exit when the top-level frame is deleted.
@@ -516,6 +586,12 @@ public:
*/
bool GetExitOnFrameDelete() const;
+ /**
+ Return the layout direction for the current locale or @c wxLayout_Default
+ if it's unknown.
+ */
+ virtual wxLayoutDirection GetLayoutDirection() const;
+
/**
Returns @true if the application will use the best visual on systems that support
different visuals, @false otherwise.
@@ -527,9 +603,10 @@ public:
/**
Returns a pointer to the top window.
- @remarks If the top window hasn't been set using SetTopWindow(),
- this function will find the first top-level window
- (frame or dialog) and return that.
+ @remarks
+ If the top window hasn't been set using SetTopWindow(), this function
+ will find the first top-level window (frame or dialog or instance of
+ wxTopLevelWindow) from the internal top level window list and return that.
@see SetTopWindow()
*/
@@ -582,6 +659,13 @@ public:
*/
virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
+ /**
+ Set display mode to use. This is only used in framebuffer wxWin
+ ports (such as wxMGL or wxDFB). This method should be called from
+ wxApp::OnInitGui.
+ */
+ virtual bool SetDisplayMode(const wxVideoMode& info);
+
/**
Allows the programmer to specify whether the application will exit when the
top-level frame is deleted.
@@ -594,17 +678,6 @@ public:
*/
void SetExitOnFrameDelete(bool flag);
- /**
- Allows external code to modify global ::wxTheApp, but you should really
- know what you're doing if you call it.
-
- @param app
- Replacement for the global application object.
-
- @see GetInstance()
- */
- static void SetInstance(wxAppConsole* app);
-
/**
Allows runtime switching of the UI environment theme.
@@ -620,9 +693,13 @@ public:
Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
know which is the main window. You don't have to set the top window;
it is only a convenience so that (for example) certain dialogs without parents
- can use a specific window as the top window. If no top window is specified by the
- application, wxWidgets just uses the first frame or dialog in its top-level window
- list, when it needs to use the top window.
+ can use a specific window as the top window.
+
+ If no top window is specified by the application, wxWidgets just uses the
+ first frame or dialog (or better, any wxTopLevelWindow) in its top-level
+ window list, when it needs to use the top window.
+ If you previously called SetTopWindow() and now you need to restore this
+ automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.
@param window
The new top window.
@@ -657,11 +734,11 @@ public:
// ============================================================================
-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */
//@{
/**
- This is used in headers to create a forward declaration of the wxGetApp()
+ This is used in headers to create a forward declaration of the ::wxGetApp()
function implemented by IMPLEMENT_APP().
It creates the declaration className& wxGetApp().
@@ -705,7 +782,7 @@ wxApp *wxTheApp;
-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */
//@{
/**
@@ -791,9 +868,9 @@ void wxWakeUpIdle();
bool wxYield();
/**
- This function is similar to wxYield, except that it disables the user input to
- all program windows before calling wxYield and re-enables it again
- afterwards. If @a win is not @NULL, this window will remain enabled,
+ This function is similar to wxYield(), except that it disables the user
+ input to all program windows before calling wxYield() and re-enables it
+ again afterwards. If @a win is not @NULL, this window will remain enabled,
allowing the implementation of some limited user interaction.
Returns the result of the call to ::wxYield.
@@ -847,7 +924,7 @@ int wxEntry(HINSTANCE hInstance,
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
//@{
/**