wxPython/wx/py/wxd/App.py

   1 """Decorator classes for documentation and shell scripting.
   2 """
   3
   4 __author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
   5 __cvsid__ = "$Id$"
   6 __revision__ = "$Revision$"[11:-2]
   7
   8
   9 # These are not the real wxPython classes. These are Python versions
  10 # for documentation purposes. They are also used to apply docstrings
  11 # to the real wxPython classes, which are SWIG-generated wrappers for
  12 # C-language classes.
  13
  14
  15 from Base import EvtHandler
  16 import Parameters as wx
  17
  18 try:
  19     True
  20 except NameError:
  21     True = 1==1
  22     False = 1==0
  23
  24
  25 class PyApp(EvtHandler):
  26     """Python Application base class.
  27
  28     It is used to:
  29
  30     - set and get application-wide properties;
  31
  32     - implement the windowing system message or event loop;
  33
  34     - initiate application processing via App.OnInit;
  35
  36     - allow default processing of events not handled by other objects
  37       in the application."""
  38
  39     def __init__(self):
  40         """Create a PyApp instance."""
  41         pass
  42
  43     def Dispatch(self):
  44         """Dispatches the next event in the windowing system event
  45         queue.
  46
  47         This can be used for programming event loops."""
  48         pass
  49
  50     def ExitMainLoop(self):
  51         """Call this to explicitly exit the main message (event) loop.
  52
  53         You should normally exit the main loop (and the application)
  54         by deleting the top window, which wxPython does automatically."""
  55         pass
  56
  57     def GetAppName(self):
  58         """Return the application name."""
  59         pass
  60
  61     def GetAssertMode(self):
  62         """Return the current assertion mode."""
  63         pass
  64
  65     def GetAuto3D(self):
  66         """Returns True if 3D control mode is on, False otherwise.
  67         Windows only."""
  68         pass
  69
  70     def GetClassName(self):
  71         """Return the class name of the application."""
  72         pass
  73
  74     def GetExitOnFrameDelete(self):
  75         """Returns True if the application will exit when the
  76         top-level window is deleted, False otherwise."""
  77         pass
  78
  79     def GetPrintMode(self):
  80         """Deprecated."""
  81         pass
  82
  83     def GetTopWindow(self):
  84         """Return the top window.
  85
  86         If the top window hasn't been set using App.SetTopWindow,
  87         this method will find the first top-level window (frame or
  88         dialog) and return that."""
  89         pass
  90
  91     def GetUseBestVisual(self):
  92         """Return True if the application will use the best visual on
  93         systems that support different visuals, False otherwise."""
  94         pass
  95
  96     def GetVendorName(self):
  97         """Return the application's vendor name."""
  98         pass
  99
 100     def Initialized(self):
 101         """Return True if the application has been initialized
 102         (i.e. if App.OnInit has returned successfully). This can be
 103         useful for error message routines to determine which method of
 104         output is best for the current state of the program (some
 105         windowing systems may not like dialogs to pop up before the
 106         main loop has been entered)."""
 107         pass
 108
 109     def MainLoop(self):
 110         """Called by wxWindows on creation of the application.
 111         Override this if you wish to provide your own
 112         (environment-dependent) main loop.
 113
 114         Return 0 under X, and the wParam of the WM_QUIT message under
 115         Windows."""
 116         pass
 117
 118     def OnAssert(self, file, line, cond, msg):
 119         """Called when an assert failure occurs, i.e. the condition
 120         specified in ASSERT macro evaluated to FALSE. It is only
 121         called in debug mode (when __WXDEBUG__ is defined) as asserts
 122         are not left in the release code at all.
 123
 124         The base class version show the default assert failure dialog
 125         box proposing to the user to stop the program, continue or
 126         ignore all subsequent asserts.
 127
 128         file is the name of the source file where the assert occured
 129
 130         line is the line number in this file where the assert occured
 131
 132         cond is the condition of the failed assert in string form
 133
 134         msg is the message specified as argument to ASSERT_MSG or
 135         FAIL_MSG, will be NULL if just ASSERT or FAIL was used"""
 136         pass
 137
 138     def OnExit(self):
 139         """Provide this member function for any processing which needs
 140         to be done as the application is about to exit.  OnExit is
 141         called after destroying all application windows and controls,
 142         but before wxWindows cleanup."""
 143         pass
 144
 145     def OnInit(self):
 146         """This must be provided by the application, and will usually
 147         create the application's main window, optionally calling
 148         App.SetTopWindow.
 149
 150         Return True to continue processing, False to exit the
 151         application."""
 152         pass
 153
 154     def OnInitGui(self):
 155         """Called just after the platform's GUI has been initialized,
 156         but before the App.OnInit() gets called. Rarely needed in
 157         practice. Unlike App.OnInit(), does not need to return
 158         True/False."""
 159         pass
 160
 161     def Pending(self):
 162         """Return True if unprocessed events are in the window system
 163         event queue."""
 164         pass
 165
 166     def ProcessIdle(self):
 167         """Sends the EVT_IDLE event and is called inside the MainLoop.
 168
 169         You only need this if you implement your own main loop."""
 170         pass
 171
 172     def SetAppName(self, name):
 173         """Set the name of the application."""
 174         pass
 175
 176     def SetAssertMode(self, mode):
 177         """Lets you control how C++ assertions are processed.
 178
 179         Valid modes are: PYAPP_ASSERT_SUPPRESS,
 180         PYAPP_ASSERT_EXCEPTION, and PYAPP_ASSERT_DIALOG.  Using
 181         _SUPPRESS will give you behavior like the old final builds and
 182         the assert will be ignored, _EXCEPTION is the new default
 183         described above, and _DIALOG is like the default in 2.3.3.1
 184         and prior hybrid builds.  You can also combine _EXCEPTION and
 185         _DIALOG if you wish, although I don't know why you would."""
 186         pass
 187
 188     def SetAuto3D(self, auto3D):
 189         """Switches automatic 3D controls on or off.  Windows only.
 190
 191         If auto3D is True, all controls will be created with 3D
 192         appearances unless overridden for a control or dialog.  The
 193         default is True."""
 194         pass
 195
 196     def SetClassName(self, name):
 197         """Set the class name of the application."""
 198         pass
 199
 200     def SetExitOnFrameDelete(self, flag):
 201         """If flag is True (the default), the application will exit
 202         when the top-level frame is deleted.  If False, the
 203         application will continue to run."""
 204         pass
 205
 206     def SetPrintMode(self, mode):
 207         """Deprecated."""
 208         pass
 209
 210     def SetTopWindow(self, window):
 211         """Set the 'top' window.
 212
 213         You can call this from within App.OnInit to let wxWindows
 214         know which is the main window.  You don't have to set the top
 215         window; it is only a convenience so that (for example) certain
 216         dialogs without parents can use a specific window as the top
 217         window.  If no top window is specified by the application,
 218         wxWindows just uses the first frame or dialog in its top-level
 219         window list, when it needs to use the top window."""
 220         pass
 221
 222     def SetUseBestVisual(self, flag):
 223         """Allows the programmer to specify whether the application
 224         will use the best visual on systems that support several
 225         visual on the same display.  This is typically the case under
 226         Solaris and IRIX, where the default visual is only 8-bit
 227         whereas certain applications are supposed to run in TrueColour
 228         mode.
 229
 230         Note that this function has to be called in the constructor of
 231         the App instance and won't have any effect when called later
 232         on.
 233
 234         This function currently only has effect under GTK."""
 235         pass
 236
 237     def SetVendorName(self, name):
 238         """Sets the name of application's vendor.  The name will be
 239         used in registry access."""
 240         pass
 241
 242     def Yield(self, onlyIfNeeded=False):
 243         """Yields control to pending messages in the windowing system.
 244         This can be useful, for example, when a time-consuming process
 245         writes to a text window.  Without an occasional yield, the
 246         text window will not be updated properly, and on systems with
 247         cooperative multitasking, such as Windows 3.1 other processes
 248         will not respond.
 249
 250         Caution should be exercised, however, since yielding may allow
 251         the user to perform actions which are not compatible with the
 252         current task.  Disabling menu items or whole menus during
 253         processing can avoid unwanted reentrance of code: see
 254         wx.SafeYield for a better function.
 255
 256         Calling Yield() recursively is normally an error and an assert
 257         failure is raised in debug build if such situation is
 258         detected.  However if the the onlyIfNeeded parameter is True,
 259         the method will just silently return False instead."""
 260         pass
 261
 262
 263 from wxPython.wx import wxPlatform
 264 _redirect = (wxPlatform == '__WXMSW__' or wxPlatform == '__WXMAC__')
 265 del wxPlatform
 266
 267
 268 class App(PyApp):
 269     """The main application class.
 270
 271     Inherit from this class and implement an OnInit method that
 272     creates a frame and then calls self.SetTopWindow(frame)."""
 273
 274     def __init__(self, redirect=_redirect, filename=None, useBestVisual=False):
 275         """Create an App instance.
 276
 277         redirect defaults to True on Windows and Mac. If redirect is
 278         True, stdio goes to an output window or a file if filename is
 279         not None."""
 280         pass
 281
 282
 283 del _redirect
 284
 285
 286 class PyOnDemandOutputWindow:
 287     """Used by App to display stdout and stderr messages if app is
 288     created using App(redirect=True).  Mostly useful on Windows or
 289     Mac where apps aren't always launched from the command line."""
 290     pass
 291
 292
 293 class PySimpleApp(App):
 294     """Use instead of App for simple apps with a simple frame or
 295     dialog, particularly for testing."""
 296
 297     def __init__(self, flag=0):
 298         """Create a PySimpleApp instance.
 299
 300         flag is the same as App's redirect parameter to redirect stdio."""
 301         pass
 302
 303     def OnInit(self):
 304         """Automatically does a wx.InitAllImageHandlers()."""
 305         pass
 306
 307
 308 class PyWidgetTester(App):
 309     """Use instead of App for testing widgets. Provides a frame
 310     containing an instance of a widget.
 311
 312     Create a PyWidgetTester instance with the desired size for the
 313     frame, then create the widget and show the frame using SetWidget."""
 314
 315     def __init__(self, size=(250, 100)):
 316         """Create a PyWidgetTester instance, with no stdio redirection.
 317
 318         size is for the frame to hold the widget."""
 319         pass
 320
 321     def OnInit(self):
 322         """Creates a frame that will hold the widget to be tested."""
 323         pass
 324
 325     def SetWidget(self, widgetClass, *args):
 326         """Create a widgetClass instance using the supplied args and
 327         with a frame as parent, then show the frame."""
 328         pass
 329
 330
 331 class SingleInstanceChecker:
 332     """Allows one to check that only a single instance of a program is
 333     running. To do it, you should create an object of this class. As
 334     long as this object is alive, calls to IsAnotherRunning() from
 335     other processes will return True.
 336
 337     As the object should have the life span as big as possible, it
 338     makes sense to create it either as a global or in App.OnInit()."""
 339
 340     def __init__(self, name, path=wx.EmptyString):
 341         """Create a SingleInstanceChecker instance.
 342
 343         name should be as unique as possible. It is used as the mutex
 344         name under Win32 and the lock file name under Unix.
 345         App.GetAppName() and wx.GetUserId() are commonly used.
 346
 347         path is optional and is ignored under Win32 and used as the
 348         directory to create the lock file in under Unix (default is
 349         wx.GetHomeDir())."""
 350         pass
 351
 352     def Create(self, name, path=wx.EmptyString):
 353         """Create a SingleInstanceChecker instance."""
 354         pass
 355
 356     def IsAnotherRunning(self):
 357         """Return True if another copy of this program is already running."""
 358         pass