.. include:: headings.inc .. _PyApp: ========================================================================================================================================== |phoenix_title| **PyApp** ========================================================================================================================================== The :ref:`App` class represents the application itself when ``USE_GUI=1`` . In addition to the features provided by :ref:`AppConsole` it keeps track of the `top window` (see :meth:`~PyApp.SetTopWindow`) and adds support for video modes (see SetVideoMode()). In general, application-wide settings for GUI-only apps are accessible from :ref:`App` (or from :ref:`SystemSettings` or :ref:`SystemOptions` classes). .. _PyApp-events: |events| Events Emitted by this Class ===================================== Event macros for events emitted by this class: - EVT_QUERY_END_SESSION: Process a query end session event, supplying the member function. See :ref:`CloseEvent`. - EVT_END_SESSION: Process an end session event, supplying the member function. See :ref:`CloseEvent`. - EVT_ACTIVATE_APP: Process a ``wxEVT_ACTIVATE_APP`` event. See :ref:`ActivateEvent`. - EVT_HIBERNATE: Process a hibernate event. See :ref:`ActivateEvent`. - EVT_DIALUP_CONNECTED: A connection with the network was established. See `DialUpEvent`. - EVT_DIALUP_DISCONNECTED: The connection with the network was lost. See `DialUpEvent`. - EVT_IDLE: Process a ``wxEVT_IDLE`` event. See :ref:`IdleEvent`. .. seealso:: :ref:`App Overview `, :ref:`AppTraits`, :ref:`EventLoopBase`, :ref:`SystemSettings` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **PyApp** .. raw:: html

Inheritance diagram of PyApp

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~PyApp.__init__` Constructor. :meth:`~PyApp.GetAssertMode` Returns the current mode for how the application responds to asserts. :meth:`~PyApp.GetDisplayMode` Get display mode that is used use. :meth:`~PyApp.GetExitOnFrameDelete` Returns ``True`` if the application will exit when the top-level frame is deleted. :meth:`~PyApp.GetLayoutDirection` Return the layout direction for the current locale or ``Layout_Default`` if it's unknown. :meth:`~PyApp.GetTopWindow` Returns a pointer to the top window. :meth:`~PyApp.GetUseBestVisual` Returns ``True`` if the application will use the best visual on systems that support different visuals, ``False`` otherwise. :meth:`~PyApp.IsActive` Returns ``True`` if the application is active, i.e. :meth:`~PyApp.IsDisplayAvailable` Returns True if the application is able to connect to the system's :meth:`~PyApp.MacHideApp` Hide all application windows just as the user can do with the :meth:`~PyApp.MacNewFile` Called in response of an "open-application" Apple event. :meth:`~PyApp.MacOpenFile` Called in response of an "open-document" Apple event. :meth:`~PyApp.MacOpenFiles` Called in response of an openFiles message with Cocoa, or an "open-document" Apple event with Carbon. :meth:`~PyApp.MacOpenURL` Called in response of a "get-url" Apple event. :meth:`~PyApp.MacPrintFile` Called in response of a "print-document" Apple event. :meth:`~PyApp.MacReopenApp` Called in response of a "reopen-application" Apple event. :meth:`~PyApp.SafeYield` This function is similar to :func:`Yield`, except that it disables the user input to all program windows before calling :meth:`AppConsole.Yield` and re-enables it again afterwards. :meth:`~PyApp.SafeYieldFor` Works like :meth:`SafeYield` with `onlyIfNeeded` == ``True`` except that it allows the caller to specify a mask of events to be processed. :meth:`~PyApp.SetAssertMode` Set the mode indicating how the application responds to assertion :meth:`~PyApp.SetDisplayMode` Set display mode to use. :meth:`~PyApp.SetExitOnFrameDelete` Allows the programmer to specify whether the application will exit when the top-level frame is deleted. :meth:`~PyApp.SetNativeTheme` Allows runtime switching of the UI environment theme. :meth:`~PyApp.SetTopWindow` Sets the 'top' window. :meth:`~PyApp.SetUseBestVisual` Allows the programmer to specify whether the application will use the best visual on systems that support several visual on the same display. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~PyApp.AssertMode` See :meth:`~PyApp.GetAssertMode` and :meth:`~PyApp.SetAssertMode` :attr:`~PyApp.DisplayMode` See :meth:`~PyApp.GetDisplayMode` and :meth:`~PyApp.SetDisplayMode` :attr:`~PyApp.ExitOnFrameDelete` See :meth:`~PyApp.GetExitOnFrameDelete` and :meth:`~PyApp.SetExitOnFrameDelete` :attr:`~PyApp.LayoutDirection` See :meth:`~PyApp.GetLayoutDirection` :attr:`~PyApp.TopWindow` See :meth:`~PyApp.GetTopWindow` and :meth:`~PyApp.SetTopWindow` :attr:`~PyApp.UseBestVisual` See :meth:`~PyApp.GetUseBestVisual` and :meth:`~PyApp.SetUseBestVisual` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: PyApp(AppConsole) The App class represents the application itself when USE_GUI=1. **Possible constructors**:: PyApp() .. method:: __init__(self) Constructor. Called implicitly with a definition of a :ref:`App` object. .. method:: GetAssertMode(self) Returns the current mode for how the application responds to asserts. :rtype: :ref:`AppAssertMode` .. method:: GetDisplayMode(self) Get display mode that is used use. This is only used in framebuffer wxWidgets ports such as wxDFB. :rtype: :ref:`VideoMode` .. method:: GetExitOnFrameDelete(self) Returns ``True`` if the application will exit when the top-level frame is deleted. :rtype: `bool` .. seealso:: :meth:`SetExitOnFrameDelete` .. method:: GetLayoutDirection(self) Return the layout direction for the current locale or ``Layout_Default`` if it's unknown. :rtype: :ref:`LayoutDirection` .. method:: GetTopWindow(self) Returns a pointer to the top window. :rtype: :ref:`Window` .. note:: If the top window hasn't been set using :meth:`SetTopWindow` , this function will find the first top-level window (frame or dialog or instance of :ref:`TopLevelWindow`) from the internal top level window list and return that. .. seealso:: :meth:`SetTopWindow` .. method:: GetUseBestVisual(self) Returns ``True`` if the application will use the best visual on systems that support different visuals, ``False`` otherwise. :rtype: `bool` .. seealso:: :meth:`SetUseBestVisual` .. method:: IsActive(self) Returns ``True`` if the application is active, i.e. if one of its windows is currently in the foreground. If this function returns ``False`` and you need to attract users attention to the application, you may use :meth:`TopLevelWindow.RequestUserAttention` to do it. :rtype: `bool` .. staticmethod:: IsDisplayAvailable() Returns True if the application is able to connect to the system's display, or whatever the equivallent is for the platform. :rtype: `bool` .. method:: MacHideApp(self) Hide all application windows just as the user can do with the system Hide command. Mac only. .. method:: MacNewFile(self) Called in response of an "open-application" Apple event. Override this to create a new document in your app. .. availability:: Only available for OSX. .. method:: MacOpenFile(self, fileName) Called in response of an "open-document" Apple event. :param `fileName`: :type `fileName`: string .. deprecated:: 2.9.4 This function is kept mostly for backwards compatibility. Please override :meth:`App.MacOpenFiles` method instead in any new code. .. availability:: Only available for OSX. .. method:: MacOpenFiles(self, fileNames) Called in response of an openFiles message with Cocoa, or an "open-document" Apple event with Carbon. You need to override this method in order to open one or more document files after the user float clicked on it or if the files and/or folders were dropped on either the application in the dock or the application icon in Finder. By default this method calls MacOpenFile for each file/folder. :param `fileNames`: :type `fileNames`: list of strings .. versionadded:: 2.9.3 .. availability:: Only available for OSX. .. method:: MacOpenURL(self, url) Called in response of a "get-url" Apple event. :param `url`: :type `url`: string .. availability:: Only available for OSX. .. method:: MacPrintFile(self, fileName) Called in response of a "print-document" Apple event. :param `fileName`: :type `fileName`: string .. availability:: Only available for OSX. .. method:: MacReopenApp(self) Called in response of a "reopen-application" Apple event. .. availability:: Only available for OSX. .. method:: SafeYield(self, win, onlyIfNeeded) This function is similar to :func:`Yield`, except that it disables the user input to all program windows before calling :meth:`AppConsole.Yield` and re-enables it again afterwards. If `win` is not ``None``, this window will remain enabled, allowing the implementation of some limited user interaction. Returns the result of the call to :meth:`AppConsole.Yield` . :param `win`: :type `win`: Window :param `onlyIfNeeded`: :type `onlyIfNeeded`: bool :rtype: `bool` .. seealso:: :func:`SafeYield` .. method:: SafeYieldFor(self, win, eventsToProcess) Works like :meth:`SafeYield` with `onlyIfNeeded` == ``True`` except that it allows the caller to specify a mask of events to be processed. See `AppConsole.YieldFor` for more info. :param `win`: :type `win`: Window :param `eventsToProcess`: :type `eventsToProcess`: long :rtype: `bool` .. method:: SetAssertMode(self, AppAssertMode) Set the mode indicating how the application responds to assertion statements. Valid settings are a combination of these flags: - ``APP_ASSERT_SUPPRESS`` - ``APP_ASSERT_EXCEPTION`` - ``APP_ASSERT_DIALOG`` - ``APP_ASSERT_LOG`` The default behavior is to raise a wx.wxAssertionError exception. :param `wxAppAssertMode`: :type `wxAppAssertMode`: AppAssertMode .. method:: SetDisplayMode(self, info) Set display mode to use. This is only used in framebuffer wxWidgets ports such as wxDFB. :param `info`: :type `info`: VideoMode :rtype: `bool` .. method:: SetExitOnFrameDelete(self, flag) Allows the programmer to specify whether the application will exit when the top-level frame is deleted. :param `flag`: If ``True`` (the default), the application will exit when the top-level frame is deleted. If ``False``, the application will continue to run. :type `flag`: bool .. seealso:: :meth:`GetExitOnFrameDelete` , :ref:`Application Shutdown ` .. method:: SetNativeTheme(self, theme) Allows runtime switching of the UI environment theme. Currently implemented for GTK2-only. Return ``True`` if theme was successfully changed. :param `theme`: The name of the new theme or an absolute path to a gtkrc-theme-file :type `theme`: string :rtype: `bool` .. method:: SetTopWindow(self, window) Sets the 'top' window. You can call this from within :meth:`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 (or better, any :ref:`TopLevelWindow`) in its top-level window list, when it needs to use the top window. If you previously called :meth:`SetTopWindow` and now you need to restore this automatic behaviour you can call :: wx.App.SetTopWindow(None) :param `window`: The new top window. :type `window`: Window .. seealso:: :meth:`GetTopWindow` , :meth:`OnInit` .. method:: SetUseBestVisual(self, flag, forceTrueColour=False) Allows the programmer to specify whether the application will use the best visual on systems that support several visual on the same display. This is typically the case under Solaris and ``IRIX``, where the default visual is only 8-bit whereas certain applications are supposed to run in TrueColour mode. Note that this function has to be called in the constructor of the :ref:`App` instance and won't have any effect when called later on. This function currently only has effect under GTK. :param `flag`: If ``True``, the app will use the best visual. :type `flag`: bool :param `forceTrueColour`: If ``True`` then the application will try to force using a TrueColour visual and abort the app if none is found. :type `forceTrueColour`: bool .. attribute:: AssertMode See :meth:`~PyApp.GetAssertMode` and :meth:`~PyApp.SetAssertMode` .. attribute:: DisplayMode See :meth:`~PyApp.GetDisplayMode` and :meth:`~PyApp.SetDisplayMode` .. attribute:: ExitOnFrameDelete See :meth:`~PyApp.GetExitOnFrameDelete` and :meth:`~PyApp.SetExitOnFrameDelete` .. attribute:: LayoutDirection See :meth:`~PyApp.GetLayoutDirection` .. attribute:: TopWindow See :meth:`~PyApp.GetTopWindow` and :meth:`~PyApp.SetTopWindow` .. attribute:: UseBestVisual See :meth:`~PyApp.GetUseBestVisual` and :meth:`~PyApp.SetUseBestVisual`