wxPython/wx/py/wxd/Base.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 import Parameters as wx
  16
  17
  18 class Object:
  19     """Base class for all other wxPython classes."""
  20
  21     def __init__(self):
  22         """Create a Object instance."""
  23         pass
  24
  25     def Destroy(self):
  26         """Destroy the Object instance."""
  27         pass
  28
  29     def GetClassName(self):
  30         """Return the name of the class."""
  31         pass
  32
  33
  34 class EvtHandler(Object):
  35     """Base class that can handle events from the windowing system.
  36
  37     If the handler is part of a chain, the destructor will unlink
  38     itself and restore the previous and next handlers so that they
  39     point to each other."""
  40
  41     def __init__(self):
  42         """Create a EvtHandler instance."""
  43         pass
  44
  45     def AddPendingEvent(self, event):
  46         """Post an event to be processed later.
  47
  48         event is an Event instance to add to process queue.
  49
  50         The difference between sending an event (using the
  51         ProcessEvent method) and posting it is that in the first case
  52         the event is processed before the function returns, while in
  53         the second case, the function returns immediately and the
  54         event will be processed sometime later (usually during the
  55         next event loop iteration).
  56
  57         A copy of event is made by the function, so the original can
  58         be deleted as soon as function returns (it is common that the
  59         original is created on the stack).  This requires that the
  60         Event::Clone method be implemented by event so that it can
  61         be duplicated and stored until it gets processed.
  62
  63         This is also the method to call for inter-thread
  64         communication.  It will post events safely between different
  65         threads which means that this method is thread-safe by using
  66         critical sections where needed.  In a multi-threaded program,
  67         you often need to inform the main GUI thread about the status
  68         of other working threads and such notification should be done
  69         using this method.
  70
  71         This method automatically wakes up idle handling if the
  72         underlying window system is currently idle and thus would not
  73         send any idle events.  (Waking up idle handling is done
  74         calling WakeUpIdle.)"""
  75         pass
  76
  77     def Connect(self, id, lastId, eventType, func):
  78         """Connects the given function dynamically with the event
  79         handler, id and event type.  This is an alternative to the use
  80         of static event tables.
  81
  82         id is the identifier (or first of the identifier range) to be
  83         associated with the event handler function.
  84
  85         lastId is the second part of the identifier range to be
  86         associated with the event handler function.
  87
  88         eventType is the event type to be associated with this event
  89         handler.
  90
  91         function is the event handler function.
  92
  93         userData is data to be associated with the event table entry."""
  94         pass
  95
  96     def Disconnect(self, id, lastId=-1, eventType=wx.EVT_NULL):
  97         """Disconnects the given function dynamically from the event
  98         handler, using the specified parameters as search criteria and
  99         returning True if a matching function has been found and
 100         removed.  This method can only disconnect functions which have
 101         been added using the EvtHandler.Connect method. There is no
 102         way to disconnect functions connected using the (static) event
 103         tables.
 104
 105         id is the identifier (or first of the identifier range) to be
 106         associated with the event handler function.
 107
 108         lastId is the second part of the identifier range to be
 109         associated with the event handler function.
 110
 111         eventType is the event type to be associated with this event
 112         handler.
 113
 114         function is the event handler function.
 115
 116         userData is data to be associated with the event table entry."""
 117         pass
 118
 119     def GetEvtHandlerEnabled(self):
 120         """Return True if the event handler is enabled, False
 121         otherwise."""
 122         pass
 123
 124     def GetNextHandler(self):
 125         """Return the next handler in the chain."""
 126         pass
 127
 128     def GetPreviousHandler(self):
 129         """Return the previous handler in the chain."""
 130         pass
 131
 132     def ProcessEvent(self, event):
 133         """Processes an event, searching event tables and calling zero
 134         or more suitable event handler function(s).  Return True if a
 135         suitable event handler function was found and executed, and
 136         the function did not call Event.Skip().
 137
 138         event is an Event to process.
 139
 140         Normally, your application would not call this function: it is
 141         called in the wxPython implementation to dispatch incoming
 142         user interface events to the framework (and application).
 143
 144         However, you might need to call it if implementing new
 145         functionality (such as a new control) where you define new
 146         event types, as opposed to allowing the user to override
 147         virtual functions.
 148
 149         An instance where you might actually override the ProcessEvent
 150         function is where you want to direct event processing to event
 151         handlers not normally noticed by wxWindows.  For example, in
 152         the document/view architecture, documents and views are
 153         potential event handlers.  When an event reaches a frame,
 154         ProcessEvent will need to be called on the associated document
 155         and view in case event handler functions are associated with
 156         these objects.  The property classes library (Property) also
 157         overrides ProcessEvent for similar reasons.
 158
 159         The normal order of event table searching is as follows:
 160
 161         1. If the object is disabled (via a call to
 162         EvtHandler.SetEvtHandlerEnabled) the function skips to step
 163         (6).
 164
 165         2. If the object is a Window, ProcessEvent is recursively
 166         called on the window's Validator.  If this returns TRUE, the
 167         function exits.
 168
 169         3. SearchEventTable is called for this event handler.  If this
 170         fails, the base class table is tried, and so on until no more
 171         tables exist or an appropriate function was found, in which
 172         case the function exits.
 173
 174         4. The search is applied down the entire chain of event
 175         handlers (usually the chain has a length of one).  If this
 176         succeeds, the function exits.
 177
 178         5. If the object is a Window and the event is a
 179         CommandEvent, ProcessEvent is recursively applied to the
 180         parent window's event handler.  If this returns TRUE, the
 181         function exits.
 182
 183         6. Finally, ProcessEvent is called on the App object.
 184
 185         See also:
 186
 187         EvtHandler::SearchEventTable"""
 188         pass
 189
 190     def SetEvtHandlerEnabled(self, enabled):
 191         """Enable or disable the event handler.
 192
 193         You can use this function to avoid having to remove the event
 194         handler from the chain, for example when implementing a dialog
 195         editor and changing from edit to test mode."""
 196         pass
 197
 198     def SetNextHandler(self, handler):
 199         """Set the pointer to the next handler."""
 200         pass
 201
 202     def SetPreviousHandler(self, handler):
 203         """Set the pointer to the previous handler."""
 204         pass
 205
 206