.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.AppConsole:

==========================================================================================================================================
|phoenix_title|  **wx.AppConsole**
==========================================================================================================================================

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

Note that it is not intended for this class to be used directly from Python. It is wrapped just for inheriting its methods in :class:`App`. 

It is used to: 

- set and get application-wide properties (see :meth:`wx.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 :meth:`wx.AppConsole.HandleEvent`   and :meth:`wx.AppConsole.ProcessPendingEvents` );  
- initiate application processing via :meth:`wx.App.OnInit` ;  
- allow default processing of events not handled by other objects in the application (see :meth:`wx.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 :ref:`wx.GetApp`  function (which returns a reference to your application object) to be visible to other files. 





         



.. seealso:: :ref:`App Overview <app overview>`, :ref:`wx.App`, :ref:`wx.AppTraits`, :ref:`wx.EventLoopBase`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>AppConsole</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.AppConsole_inheritance.png" alt="Inheritance diagram of AppConsole" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.AppConsole.html" title="wx.AppConsole" alt="" coords="117,160,239,189"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="50,83,167,112"/> <area shape="rect" id="node3" href="wx.EventFilter.html" title="wx.EventFilter" alt="" coords="191,83,306,112"/> <area shape="rect" id="node4" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> <area shape="rect" id="node5" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="117,5,223,35"/> </map> 
   </p>
   </div>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.App`

|


|method_summary| Methods Summary
================================

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


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.AppConsole.AppDisplayName`                                            See :meth:`~wx.AppConsole.GetAppDisplayName` and :meth:`~wx.AppConsole.SetAppDisplayName`
:attr:`~wx.AppConsole.AppName`                                                   See :meth:`~wx.AppConsole.GetAppName` and :meth:`~wx.AppConsole.SetAppName`
:attr:`~wx.AppConsole.ClassName`                                                 See :meth:`~wx.AppConsole.GetClassName` and :meth:`~wx.AppConsole.SetClassName`
:attr:`~wx.AppConsole.Traits`                                                    See :meth:`~wx.AppConsole.GetTraits`
:attr:`~wx.AppConsole.VendorDisplayName`                                         See :meth:`~wx.AppConsole.GetVendorDisplayName` and :meth:`~wx.AppConsole.SetVendorDisplayName`
:attr:`~wx.AppConsole.VendorName`                                                See :meth:`~wx.AppConsole.GetVendorName` and :meth:`~wx.AppConsole.SetVendorName`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.AppConsole(EvtHandler, EventFilter)

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



   .. method:: DeletePendingEvents(self)

      Deletes the pending events of all EvtHandlers of this application.                  

      See :meth:`wx.EvtHandler.DeletePendingEvents`   for warnings about deleting the pending events.                   





   .. method:: 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.                   





   .. method:: FilterEvent(self, event)

      Overridden :ref:`wx.EventFilter`  method.                  

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

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


      :param `event`: 
      :type `event`: wx.Event




      :rtype: `int`








   .. method:: GetAppDisplayName(self)

      Returns the user-readable application name.                  

      The difference between this string and the one returned by :meth:`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 :meth:`SetAppDisplayName` , it will be returned by this function. Otherwise, if :meth:`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 :meth:`String.Capitalize` . 

                

      :rtype: `string`







      .. versionadded:: 2.9.0 
     








   .. method:: GetAppName(self)

      Returns the application name.                  

      If :meth:`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. 

                

      :rtype: `string`







      .. seealso:: :meth:`GetAppDisplayName`     








   .. method:: 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. 

                

      :rtype: `string`







      .. seealso:: :meth:`SetClassName`     








   .. staticmethod:: GetInstance()

      Returns the one and only global application object.                  

      Usually :ref:`wx.TheApp`  is used instead. 

                

      :rtype: :ref:`wx.AppConsole`







      .. seealso:: :meth:`SetInstance` , :meth:`wx.App.GetGUIInstance`     








   .. method:: GetMainLoop(self)

      Returns the main event loop instance, i.e. the event loop which is started by :meth:`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 non-NULL main event loop into :meth:`OnEventLoopEnter` .                  

      :rtype: :ref:`wx.EventLoopBase`








   .. method:: GetTraits(self)

      Returns a pointer to the :ref:`wx.AppTraits`  object for the application.                  

      If you want to customize the :ref:`wx.AppTraits`  object, you must override the :meth:`CreateTraits`   function.                  

      :rtype: :ref:`wx.AppTraits`








   .. method:: GetVendorDisplayName(self)

      Returns the user-readable vendor name.                  

      The difference between this string and the one returned by :meth:`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 :meth:`GetVendorName` . 

                

      :rtype: `string`







      .. versionadded:: 2.9.0 
     








   .. method:: GetVendorName(self)

      Returns the application's vendor name.                  

      :rtype: `string`








   .. method:: HasPendingEvents(self)

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

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

      :rtype: `bool`








   .. staticmethod:: IsMainLoopRunning()

      Returns ``True`` if the main event loop is currently running, i.e. if the application is inside :meth:`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.                  

      :rtype: `bool`








   .. method:: IsScheduledForDestruction(self, object)

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

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


      :param `object`: 
      :type `object`: wx.Object




      :rtype: `bool`








   .. method:: MainLoop(self)

      Called by wxWidgets on creation of the application.                  

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

                

      :rtype: `int`







      :returns: 

         0 under X, and the wParam of the ``WM_QUIT`` message under Windows.   








   .. method:: OnEventLoopEnter(self, loop)

      Called by :meth:`wx.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 :meth:`wx.EventLoopBase.IsMain`   to perform initialization specific for the app's main event loop. 

                


      :param `loop`: 
      :type `loop`: wx.EventLoopBase






      .. seealso:: :meth:`OnEventLoopExit`     








   .. method:: OnEventLoopExit(self, loop)

      Called by :meth:`wx.EventLoopBase.OnExit`   for each event loop which is exited.                  

                


      :param `loop`: 
      :type `loop`: wx.EventLoopBase






      .. seealso:: :meth:`OnEventLoopEnter`     








   .. method:: 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 :meth:`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.                  

      :rtype: `int`








   .. method:: OnInit(self)

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

      You may use :meth:`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 :meth:`OnInit` . 

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

      :rtype: `bool`








   .. method:: 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 :meth:`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.                  

      :rtype: `int`








   .. method:: ProcessPendingEvents(self)

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

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

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

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





   .. method:: ResumeProcessingOfPendingEvents(self)

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





   .. method:: 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 :meth:`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 :meth:`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.                  


      :param `object`: 
      :type `object`: wx.Object







   .. method:: SetAppDisplayName(self, name)

      Set the application name to be used in the user-visible places such as window titles.                  

      See :meth:`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 :meth:`GetAppDisplayName` .                  


      :param `name`: 
      :type `name`: string







   .. method:: 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 :meth:`SetAppDisplayName`   is used instead. 

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

                


      :param `name`: 
      :type `name`: string






      .. seealso:: :meth:`GetAppName`     








   .. method:: SetCLocale(self)

      Sets the C locale to the default locale for the current environment.                  

      It is advised to call this to ensure that the underlying toolkit uses the locale in which the numbers and monetary amounts are shown in the format expected by user and so on. 

      Calling this function is roughly equivalent to calling ::

          setlocale(LC_ALL, "")

      but performs additional toolkit-specific tasks under some platforms and so should be used instead of  ``setlocale()``   itself. Alternatively, you can use  :ref:`wx.Locale`  to change the locale with more control. 

      Notice that this does `not`  change the global C++ locale, you need to do it explicitly if you want, e.g. ::



      but be warned that locale support in C++ standard library can be poor or worse under some platforms. 

                 



      .. versionadded:: 2.9.5 
     








   .. method:: SetClassName(self, name)

      Sets the class name of the application.                  

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

                


      :param `name`: 
      :type `name`: string






      .. seealso:: :meth:`GetClassName`     








   .. staticmethod:: SetInstance(app)

      Allows external code to modify global :ref:`wx.TheApp`, but you should really know what you're doing if you call it.                  




      :param `app`: Replacement for the global application object.  
      :type `app`: wx.AppConsole




                  



      .. seealso:: :meth:`GetInstance`     








   .. method:: SetVendorDisplayName(self, name)

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

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


      :param `name`: 
      :type `name`: string







   .. method:: 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. 

                


      :param `name`: 
      :type `name`: string






      .. seealso:: :meth:`GetVendorName`     








   .. method:: SuspendProcessingOfPendingEvents(self)

      Temporary suspends processing of the pending events.                  

                 



      .. seealso:: :meth:`ResumeProcessingOfPendingEvents`     








   .. method:: UsesEventLoop(self)

      Returns ``True`` if the application is using an event loop.                  

      This function always returns ``True`` for the GUI applications which must use an event loop but by default only returns ``True`` for the console programs if an event loop is already running as it can't know whether one will be created in the future. 

      Thus, it only makes sense to override it in console applications which do use an event loop, to return ``True`` instead of checking if there is a currently active event loop.                  

      :rtype: `bool`








   .. method:: Yield(self, onlyIfNeeded=False)

      Yields control to pending messages in the event loop.                  

      This method is a convenient wrapper for `EvtLoopBase.Yield().` If the main loop is currently running, it calls this method on it. Otherwise it creates a temporary event loop and uses it instead, which can be useful to process pending messages during the program startup, before the main loop is created. 

      Use extreme caution when calling this function as, just as `EvtLoopBase.Yield(),` it can result in unexpected reentrances.                  


      :param `onlyIfNeeded`: 
      :type `onlyIfNeeded`: bool




      :rtype: `bool`








   .. attribute:: AppDisplayName

      See :meth:`~wx.AppConsole.GetAppDisplayName` and :meth:`~wx.AppConsole.SetAppDisplayName`


   .. attribute:: AppName

      See :meth:`~wx.AppConsole.GetAppName` and :meth:`~wx.AppConsole.SetAppName`


   .. attribute:: ClassName

      See :meth:`~wx.AppConsole.GetClassName` and :meth:`~wx.AppConsole.SetClassName`


   .. attribute:: Traits

      See :meth:`~wx.AppConsole.GetTraits`


   .. attribute:: VendorDisplayName

      See :meth:`~wx.AppConsole.GetVendorDisplayName` and :meth:`~wx.AppConsole.SetVendorDisplayName`


   .. attribute:: VendorName

      See :meth:`~wx.AppConsole.GetVendorName` and :meth:`~wx.AppConsole.SetVendorName`