Navigation

Table Of Contents

Previous topic

AppAssertMode

Next topic

AppTraits

This Page

phoenix_title AppConsole

This class is essential for writing console-only or hybrid apps without having to define USE_GUI=0 .

It is used to:

  • set and get application-wide properties (see AppConsole.CreateTraits and AppConsole.SetXXX functions)
  • implement the windowing system message or event loop: events in fact are supported even in console-mode applications (see AppConsole.HandleEvent and AppConsole.ProcessPendingEvents );
  • initiate application processing via App.OnInit ;
  • allow default processing of events not handled by other objects in the application (see AppConsole.FilterEvent )
  • implement Apple-specific event handlers (see AppConsole.MacXXX functions)

You should use the macro IMPLEMENT_APP in your application implementation file to tell wxWidgets how to create an instance of your application class.

Use DECLARE_APP in a header file if you want the GetApp function (which returns a reference to your application object) to be visible to other files.

See also

App Overview, App, AppTraits, EventLoopBase


class_hierarchy Inheritance Diagram

Inheritance diagram for class AppConsole

Inheritance diagram of AppConsole


sub_classes Known Subclasses

App


method_summary Methods Summary

DeletePendingEvents Deletes the pending events of all EvtHandlers of this application.
ExitMainLoop Call this to explicitly exit the main message (event) loop.
FilterEvent Overridden EventFilter method.
GetAppDisplayName Returns the user-readable application name.
GetAppName Returns the application name.
GetClassName Gets the class name of the application.
GetInstance Returns the one and only global application object.
GetMainLoop Returns the main event loop instance, i.e.
GetTraits Returns a pointer to the AppTraits object for the application.
GetVendorDisplayName Returns the user-readable vendor name.
GetVendorName Returns the application’s vendor name.
HasPendingEvents Returns True if there are pending events on the internal pending event list.
IsMainLoopRunning Returns True if the main event loop is currently running, i.e.
IsScheduledForDestruction Check if the object had been scheduled for destruction with ScheduleForDestruction .
MainLoop Called by wxWidgets on creation of the application.
OnEventLoopEnter Called by EventLoopBase.SetActive : you can override this function and put here the code which needs an active event loop.
OnEventLoopExit Called by EventLoopBase.OnExit for each event loop which is exited.
OnExit Override this member function for any processing which needs to be done as the application is about to exit.
OnInit This must be provided by the application, and will usually create the application’s main window, optionally calling SetTopWindow().
OnRun This virtual function is where the execution of a program written in wxWidgets starts.
ProcessPendingEvents Process all pending events; it is necessary to call this function to process events posted with EvtHandler.QueueEvent or EvtHandler.AddPendingEvent .
ResumeProcessingOfPendingEvents Resume processing of the pending events previously stopped because of a call to SuspendProcessingOfPendingEvents .
ScheduleForDestruction Delayed objects destruction.
SetAppDisplayName Set the application name to be used in the user-visible places such as window titles.
SetAppName Sets the name of the application.
SetClassName Sets the class name of the application.
SetInstance Allows external code to modify global TheApp , but you should really know what you’re doing if you call it.
SetVendorDisplayName Set the vendor name to be used in the user-visible places.
SetVendorName Sets the name of application’s vendor.
SuspendProcessingOfPendingEvents Temporary suspends processing of the pending events.
Yield  

api Class API


class AppConsole(EvtHandler, EventFilter)

This class is essential for writing console-only or hybrid apps without having to define USE_GUI=0.


Methods


DeletePendingEvents(self)

Deletes the pending events of all EvtHandlers of this application.

See EvtHandler.DeletePendingEvents for warnings about deleting the pending events.


ExitMainLoop(self)

Call this to explicitly exit the main message (event) loop.

You should normally exit the main loop (and the application) by deleting the top window.

This function simply calls EvtLoopBase.Exit() on the active loop.


FilterEvent(self, event)

Overridden EventFilter method.

This function is called before processing any event and allows the application to preempt the processing of some events, see EventFilter documentation for more information.

App implementation of this method always return -1 indicating that the event should be processed normally.

Parameters:event (Event) –
Return type:int

GetAppDisplayName(self)

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.

If the application name for display had been previously set by SetAppDisplayName , it will be returned by this function. Otherwise, if SetAppName had been called its value will be returned; also as is. Finally if none was called, this function returns the program name capitalized using String.Capitalize .

Return type:string

New in version 2.9.0.


GetAppName(self)

Returns the application name.

If SetAppName had been called, returns the string passed to it. Otherwise returns the program name, i.e. the value of argv [0] passed to the main() function.

Return type:string

See also

GetAppDisplayName


GetClassName(self)

Gets the class name of the application.

The class name may be used in a platform specific manner to refer to the application.

Return type:string

See also

SetClassName


static GetInstance()

Returns the one and only global application object.

Usually TheApp is used instead.

Return type: AppConsole

See also

SetInstance


GetMainLoop(self)

Returns the main event loop instance, i.e.

the event loop which is started by OnRun and which dispatches all events sent from the native toolkit to the application (except when new event loops are temporarily set-up). The returned value maybe None. Put initialization code which needs a not None main event loop into OnEventLoopEnter .

Return type: EventLoopBase

GetTraits(self)

Returns a pointer to the AppTraits object for the application.

If you want to customize the AppTraits object, you must override the CreateTraits function.

Return type: AppTraits

GetVendorDisplayName(self)

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 .

Return type:string

New in version 2.9.0.


GetVendorName(self)

Returns the application’s vendor name.

Return type:string

HasPendingEvents(self)

Returns True if there are pending events on the internal pending event list.

Whenever EvtHandler.QueueEvent or EvtHandler.AddPendingEvent are called (not only for App itself, but for any event handler of the application!), the internal App’s list of handlers with pending events is updated and this function will return True.

Return type:bool

static IsMainLoopRunning()

Returns True if the main event loop is currently running, i.e.

if the application is inside OnRun .

This can be useful to test whether events can be dispatched. For example, if this function returns False, non-blocking sockets cannot be used because the events from them would never be processed.

Return type:bool

IsScheduledForDestruction(self, object)

Check if the object had been scheduled for destruction with ScheduleForDestruction .

This function may be useful as an optimization to avoid doing something with an object which will be soon destroyed in any case.

Parameters:object (Object) –
Return type:bool

MainLoop(self)

Called by wxWidgets on creation of the application.

Override this if you wish to provide your own (environment-dependent) main loop.

Return type:int
Returns:0 under X, and the wParam of the WM_QUIT message under Windows.

OnEventLoopEnter(self, loop)

Called by EventLoopBase.SetActive : you can override this function and put here the code which needs an active event loop.

Note that this function is called whenever an event loop is activated; you may want to use EventLoopBase.IsMain to perform initialization specific for the app’s main event loop.

Parameters:loop (EventLoopBase) –

See also

OnEventLoopExit


OnEventLoopExit(self, loop)

Called by EventLoopBase.OnExit for each event loop which is exited.

Parameters:loop (EventLoopBase) –

See also

OnEventLoopEnter


OnExit(self)

Override this member function for any processing which needs to be done as the application is about to exit.

OnExit is called after destroying all application windows and controls, but before wxWidgets cleanup. Note that it is not called at all if OnInit failed.

The return value of this function is currently ignored, return the same value as returned by the base class method if you override it.

Return type:int

OnInit(self)

This must be provided by the application, and will usually create the application’s main window, optionally calling SetTopWindow().

You may use OnExit to clean up anything initialized here, provided that the function returns True.

Notice that if you want to use the command line processing provided by wxWidgets you have to call the base class version in the derived class OnInit .

Return True to continue processing, False to exit the application immediately.

Return type:bool

OnRun(self)

This virtual function is where the execution of a program written in wxWidgets starts.

The default implementation just enters the main loop and starts handling the events until it terminates, either because ExitMainLoop has been explicitly called or because the last frame has been deleted and GetExitOnFrameDelete() flag is True (this is the default).

The return value of this function becomes the exit code of the program, so it should return 0 in case of successful termination.

Return type:int

ProcessPendingEvents(self)

Process all pending events; it is necessary to call this function to process events posted with EvtHandler.QueueEvent or EvtHandler.AddPendingEvent .

This happens during each event loop iteration (see EventLoopBase) in GUI mode but it may be also called directly.

Note that this function does not only process the pending events for the App object itself (which derives from EvtHandler) but also the pending events for any event handler of this application.

This function will immediately return and do nothing if SuspendProcessingOfPendingEvents was called.


ResumeProcessingOfPendingEvents(self)

Resume processing of the pending events previously stopped because of a call to SuspendProcessingOfPendingEvents .


ScheduleForDestruction(self, object)

Delayed objects destruction.

In applications using events it may be unsafe for an event handler to delete the object which generated the event because more events may be still pending for the same object. In this case the handler may call ScheduleForDestruction instead. Schedule the object for destruction in the near future.

Notice that if the application is not using an event loop, i.e. if UsesEventLoop returns False, this method will simply delete the object immediately.

Examples of using this function inside wxWidgets itself include deleting the top level windows when they are closed and sockets when they are disconnected.

Parameters:object (Object) –

SetAppDisplayName(self, name)

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 .

Parameters:name (string) –

SetAppName(self, name)

Sets the name of the application.

This name should be used for file names, configuration file entries and other internal strings. For the user-visible strings, such as the window titles, the application display name set by SetAppDisplayName is used instead.

By default the application name is set to the name of its executable file.

Parameters:name (string) –

See also

GetAppName


SetClassName(self, name)

Sets the class name of the application.

This may be used in a platform specific manner to refer to the application.

Parameters:name (string) –

See also

GetClassName


static SetInstance(app)

Allows external code to modify global TheApp , but you should really know what you’re doing if you call it.

Parameters:app (AppConsole) – Replacement for the global application object.

See also

GetInstance


SetVendorDisplayName(self, name)

Set the vendor name to be used in the user-visible places.

See GetVendorDisplayName for more about the differences between the display name and name.

Parameters:name (string) –

SetVendorName(self, name)

Sets the name of application’s vendor.

The name will be used in registry access. A default name is set by wxWidgets.

Parameters:name (string) –

See also

GetVendorName


SuspendProcessingOfPendingEvents(self)

Temporary suspends processing of the pending events.

See also

ResumeProcessingOfPendingEvents


Yield(self, onlyIfNeeded=False)
Parameters:onlyIfNeeded (bool) –
Return type:bool

Properties


AppDisplayName

See GetAppDisplayName and SetAppDisplayName


AppName

See GetAppName and SetAppName


ClassName

See GetClassName and SetClassName


Traits

See GetTraits


VendorDisplayName

See GetVendorDisplayName and SetVendorDisplayName


VendorName

See GetVendorName and SetVendorName

© Copyright 2012, Andrea Gavana. Created using Sphinx 1.2pre.