5f933e58ef
includes several new tools. As part of the change the location of the pacakge has changed as well, it is now accessible as "from wxPython import py" (or "from wx import py" using the new namespace.) There are still some transition moudules in the wxPython.lib.PyCrust mackage that will issue a warning and then import what is needed from the new package. These will be removed in a future release. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@20104 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
359 lines
12 KiB
Python
359 lines
12 KiB
Python
"""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
|