X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/eb6a4098a0f2e9ae55e72ad960b3dfc134d177c9..d14a1e28567de23c586bc80017073d0c39f8d18f:/wxPython/wx/py/wxd/App.py

diff --git a/wxPython/wx/py/wxd/App.py b/wxPython/wx/py/wxd/App.py
new file mode 100644
index 0000000000..8da71fecf6
--- /dev/null
+++ b/wxPython/wx/py/wxd/App.py
@@ -0,0 +1,358 @@
+"""Decorator classes for documentation and shell scripting.
+"""
+
+__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
+__cvsid__ = "$Id$"
+__revision__ = "$Revision$"[11:-2]
+
+
+# These are not the real wxPython classes. These are Python versions
+# for documentation purposes. They are also used to apply docstrings
+# to the real wxPython classes, which are SWIG-generated wrappers for
+# C-language classes.
+
+
+from Base import EvtHandler
+import Parameters as wx
+
+try:
+    True
+except NameError:
+    True = 1==1
+    False = 1==0
+
+
+class PyApp(EvtHandler):
+    """Python Application base class.
+
+    It is used to:
+
+    - set and get application-wide properties;
+
+    - implement the windowing system message or event loop;
+
+    - initiate application processing via App.OnInit;
+
+    - allow default processing of events not handled by other objects
+      in the application."""
+
+    def __init__(self):
+        """Create a PyApp instance."""
+        pass
+
+    def Dispatch(self):
+        """Dispatches the next event in the windowing system event
+        queue.
+
+        This can be used for programming event loops."""
+        pass
+
+    def 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, which wxPython does automatically."""
+        pass
+
+    def GetAppName(self):
+        """Return the application name."""
+        pass
+
+    def GetAssertMode(self):
+        """Return the current assertion mode."""
+        pass
+
+    def GetAuto3D(self):
+        """Returns True if 3D control mode is on, False otherwise.
+        Windows only."""
+        pass
+
+    def GetClassName(self):
+        """Return the class name of the application."""
+        pass
+
+    def GetExitOnFrameDelete(self):
+        """Returns True if the application will exit when the
+        top-level window is deleted, False otherwise."""
+        pass
+
+    def GetPrintMode(self):
+        """Deprecated."""
+        pass
+
+    def GetTopWindow(self):
+        """Return the top window.
+
+        If the top window hasn't been set using App.SetTopWindow,
+        this method will find the first top-level window (frame or
+        dialog) and return that."""
+        pass
+
+    def GetUseBestVisual(self):
+        """Return True if the application will use the best visual on
+        systems that support different visuals, False otherwise."""
+        pass
+
+    def GetVendorName(self):
+        """Return the application's vendor name."""
+        pass
+
+    def Initialized(self):
+        """Return True if the application has been initialized
+        (i.e. if App.OnInit has returned successfully). This can be
+        useful for error message routines to determine which method of
+        output is best for the current state of the program (some
+        windowing systems may not like dialogs to pop up before the
+        main loop has been entered)."""
+        pass
+
+    def MainLoop(self):
+        """Called by wxWindows 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."""
+        pass
+
+    def OnAssert(self, file, line, cond, msg):
+        """Called when an assert failure occurs, i.e. the condition
+        specified in ASSERT macro evaluated to FALSE. It is only
+        called in debug mode (when __WXDEBUG__ is defined) as asserts
+        are not left in the release code at all.
+
+        The base class version show the default assert failure dialog
+        box proposing to the user to stop the program, continue or
+        ignore all subsequent asserts.
+
+        file is the name of the source file where the assert occured
+
+        line is the line number in this file where the assert occured
+
+        cond is the condition of the failed assert in string form
+
+        msg is the message specified as argument to ASSERT_MSG or
+        FAIL_MSG, will be NULL if just ASSERT or FAIL was used"""
+        pass
+
+    def OnExit(self):
+        """Provide 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 wxWindows cleanup."""
+        pass
+
+    def OnInit(self):
+        """This must be provided by the application, and will usually
+        create the application's main window, optionally calling
+        App.SetTopWindow.
+
+        Return True to continue processing, False to exit the
+        application."""
+        pass
+
+    def OnInitGui(self):
+        """Called just after the platform's GUI has been initialized,
+        but before the App.OnInit() gets called. Rarely needed in
+        practice. Unlike App.OnInit(), does not need to return
+        True/False."""
+        pass
+    
+    def Pending(self):
+        """Return True if unprocessed events are in the window system
+        event queue."""
+        pass
+
+    def ProcessIdle(self):
+        """Sends the EVT_IDLE event and is called inside the MainLoop.
+        
+        You only need this if you implement your own main loop."""
+        pass
+
+    def SetAppName(self, name):
+        """Set the name of the application."""
+        pass
+
+    def SetAssertMode(self, mode):
+        """Lets you control how C++ assertions are processed.
+
+        Valid modes are: PYAPP_ASSERT_SUPPRESS,
+        PYAPP_ASSERT_EXCEPTION, and PYAPP_ASSERT_DIALOG.  Using
+        _SUPPRESS will give you behavior like the old final builds and
+        the assert will be ignored, _EXCEPTION is the new default
+        described above, and _DIALOG is like the default in 2.3.3.1
+        and prior hybrid builds.  You can also combine _EXCEPTION and
+        _DIALOG if you wish, although I don't know why you would."""
+        pass
+
+    def SetAuto3D(self, auto3D):
+        """Switches automatic 3D controls on or off.  Windows only.
+
+        If auto3D is True, all controls will be created with 3D
+        appearances unless overridden for a control or dialog.  The
+        default is True."""
+        pass
+
+    def SetClassName(self, name):
+        """Set the class name of the application."""
+        pass
+
+    def SetExitOnFrameDelete(self, flag):
+        """If flag is True (the default), the application will exit
+        when the top-level frame is deleted.  If False, the
+        application will continue to run."""
+        pass
+
+    def SetPrintMode(self, mode):
+        """Deprecated."""
+        pass
+
+    def SetTopWindow(self, window):
+        """Set the 'top' window.
+
+        You can call this from within App.OnInit to let wxWindows
+        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,
+        wxWindows just uses the first frame or dialog in its top-level
+        window list, when it needs to use the top window."""
+        pass
+
+    def SetUseBestVisual(self, flag):
+        """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 App instance and won't have any effect when called later
+        on.
+
+        This function currently only has effect under GTK."""
+        pass
+
+    def SetVendorName(self, name):
+        """Sets the name of application's vendor.  The name will be
+        used in registry access."""
+        pass
+
+    def Yield(self, onlyIfNeeded=False):
+        """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
+        wx.SafeYield for a better function.
+
+        Calling Yield() recursively is normally an error and an assert
+        failure is raised in debug build if such situation is
+        detected.  However if the the onlyIfNeeded parameter is True,
+        the method will just silently return False instead."""
+        pass
+
+
+from wxPython.wx import wxPlatform
+_redirect = (wxPlatform == '__WXMSW__' or wxPlatform == '__WXMAC__')
+del wxPlatform
+
+
+class App(PyApp):
+    """The main application class.
+
+    Inherit from this class and implement an OnInit method that
+    creates a frame and then calls self.SetTopWindow(frame)."""
+
+    def __init__(self, redirect=_redirect, filename=None, useBestVisual=False):
+        """Create an App instance.
+
+        redirect defaults to True on Windows and Mac. If redirect is
+        True, stdio goes to an output window or a file if filename is
+        not None."""
+        pass
+
+
+del _redirect
+
+
+class PyOnDemandOutputWindow:
+    """Used by App to display stdout and stderr messages if app is
+    created using App(redirect=True).  Mostly useful on Windows or
+    Mac where apps aren't always launched from the command line."""
+    pass
+
+
+class PySimpleApp(App):
+    """Use instead of App for simple apps with a simple frame or
+    dialog, particularly for testing."""
+
+    def __init__(self, flag=0):
+        """Create a PySimpleApp instance.
+
+        flag is the same as App's redirect parameter to redirect stdio."""
+        pass
+
+    def OnInit(self):
+        """Automatically does a wx.InitAllImageHandlers()."""
+        pass
+
+
+class PyWidgetTester(App):
+    """Use instead of App for testing widgets. Provides a frame
+    containing an instance of a widget.
+
+    Create a PyWidgetTester instance with the desired size for the
+    frame, then create the widget and show the frame using SetWidget."""
+
+    def __init__(self, size=(250, 100)):
+        """Create a PyWidgetTester instance, with no stdio redirection.
+
+        size is for the frame to hold the widget."""
+        pass
+
+    def OnInit(self):
+        """Creates a frame that will hold the widget to be tested."""
+        pass
+
+    def SetWidget(self, widgetClass, *args):
+        """Create a widgetClass instance using the supplied args and
+        with a frame as parent, then show the frame."""
+        pass
+
+
+class SingleInstanceChecker:
+    """Allows one to check that only a single instance of a program is
+    running. To do it, you should create an object of this class. As
+    long as this object is alive, calls to IsAnotherRunning() from
+    other processes will return True.
+
+    As the object should have the life span as big as possible, it
+    makes sense to create it either as a global or in App.OnInit()."""
+
+    def __init__(self, name, path=wx.EmptyString):
+        """Create a SingleInstanceChecker instance.
+
+        name should be as unique as possible. It is used as the mutex
+        name under Win32 and the lock file name under Unix.
+        App.GetAppName() and wx.GetUserId() are commonly used.
+
+        path is optional and is ignored under Win32 and used as the
+        directory to create the lock file in under Unix (default is
+        wx.GetHomeDir())."""
+        pass
+
+    def Create(self, name, path=wx.EmptyString):
+        """Create a SingleInstanceChecker instance."""
+        pass
+
+    def IsAnotherRunning(self):
+        """Return True if another copy of this program is already running."""
+        pass