@class wxAppConsole
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
{
*/
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
@return @false if the event loop should stop and @true otherwise.
- @see Pending()
+ @see Pending(), wxEventLoopBase
*/
virtual bool Dispatch();
*/
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
*/
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.
*/
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
*/
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);
*/
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
*/
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).
/**
@class wxApp
- 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 <em>top window</em> (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
{
*/
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.
*/
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.
/**
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()
*/
*/
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.
*/
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.
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.
// ============================================================================
-/** @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 <tt>className& wxGetApp()</tt>.
-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */
//@{
/**
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.
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
//@{
/**
projects / wxWidgets.git / blobdiff