d14a1e2856
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@24541 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
|