Merged the wxPy_newswig branch into the HEAD branch (main trunk)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@24541 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/wx/py/wxd/Base.py

@@ -0,0 +1,206 @@
+"""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.
+
+
+import Parameters as wx
+
+
+class Object:
+    """Base class for all other wxPython classes."""
+    
+    def __init__(self):
+        """Create a Object instance."""
+        pass
+
+    def Destroy(self):
+        """Destroy the Object instance."""
+        pass
+
+    def GetClassName(self):
+        """Return the name of the class."""
+        pass
+
+
+class EvtHandler(Object):
+    """Base class that can handle events from the windowing system.
+
+    If the handler is part of a chain, the destructor will unlink
+    itself and restore the previous and next handlers so that they
+    point to each other."""
+
+    def __init__(self):
+        """Create a EvtHandler instance."""
+        pass
+
+    def AddPendingEvent(self, event):
+        """Post an event to be processed later.
+
+        event is an Event instance to add to process queue.
+
+        The difference between sending an event (using the
+        ProcessEvent method) and posting it is that in the first case
+        the event is processed before the function returns, while in
+        the second case, the function returns immediately and the
+        event will be processed sometime later (usually during the
+        next event loop iteration).
+
+        A copy of event is made by the function, so the original can
+        be deleted as soon as function returns (it is common that the
+        original is created on the stack).  This requires that the
+        Event::Clone method be implemented by event so that it can
+        be duplicated and stored until it gets processed.
+
+        This is also the method to call for inter-thread
+        communication.  It will post events safely between different
+        threads which means that this method is thread-safe by using
+        critical sections where needed.  In a multi-threaded program,
+        you often need to inform the main GUI thread about the status
+        of other working threads and such notification should be done
+        using this method.
+
+        This method automatically wakes up idle handling if the
+        underlying window system is currently idle and thus would not
+        send any idle events.  (Waking up idle handling is done
+        calling WakeUpIdle.)"""
+        pass
+
+    def Connect(self, id, lastId, eventType, func):
+        """Connects the given function dynamically with the event
+        handler, id and event type.  This is an alternative to the use
+        of static event tables.
+
+        id is the identifier (or first of the identifier range) to be
+        associated with the event handler function.
+
+        lastId is the second part of the identifier range to be
+        associated with the event handler function.
+
+        eventType is the event type to be associated with this event
+        handler.
+
+        function is the event handler function.
+
+        userData is data to be associated with the event table entry."""
+        pass
+
+    def Disconnect(self, id, lastId=-1, eventType=wx.EVT_NULL):
+        """Disconnects the given function dynamically from the event
+        handler, using the specified parameters as search criteria and
+        returning True if a matching function has been found and
+        removed.  This method can only disconnect functions which have
+        been added using the EvtHandler.Connect method. There is no
+        way to disconnect functions connected using the (static) event
+        tables.
+
+        id is the identifier (or first of the identifier range) to be
+        associated with the event handler function.
+
+        lastId is the second part of the identifier range to be
+        associated with the event handler function.
+
+        eventType is the event type to be associated with this event
+        handler.
+
+        function is the event handler function.
+
+        userData is data to be associated with the event table entry."""
+        pass
+
+    def GetEvtHandlerEnabled(self):
+        """Return True if the event handler is enabled, False
+        otherwise."""
+        pass
+
+    def GetNextHandler(self):
+        """Return the next handler in the chain."""
+        pass
+
+    def GetPreviousHandler(self):
+        """Return the previous handler in the chain."""
+        pass
+
+    def ProcessEvent(self, event):
+        """Processes an event, searching event tables and calling zero
+        or more suitable event handler function(s).  Return True if a
+        suitable event handler function was found and executed, and
+        the function did not call Event.Skip().
+
+        event is an Event to process.
+
+        Normally, your application would not call this function: it is
+        called in the wxPython implementation to dispatch incoming
+        user interface events to the framework (and application).
+
+        However, you might need to call it if implementing new
+        functionality (such as a new control) where you define new
+        event types, as opposed to allowing the user to override
+        virtual functions.
+
+        An instance where you might actually override the ProcessEvent
+        function is where you want to direct event processing to event
+        handlers not normally noticed by wxWindows.  For example, in
+        the document/view architecture, documents and views are
+        potential event handlers.  When an event reaches a frame,
+        ProcessEvent will need to be called on the associated document
+        and view in case event handler functions are associated with
+        these objects.  The property classes library (Property) also
+        overrides ProcessEvent for similar reasons.
+
+        The normal order of event table searching is as follows:
+
+        1. If the object is disabled (via a call to
+        EvtHandler.SetEvtHandlerEnabled) the function skips to step
+        (6).
+
+        2. If the object is a Window, ProcessEvent is recursively
+        called on the window's Validator.  If this returns TRUE, the
+        function exits.
+
+        3. SearchEventTable is called for this event handler.  If this
+        fails, the base class table is tried, and so on until no more
+        tables exist or an appropriate function was found, in which
+        case the function exits.
+
+        4. The search is applied down the entire chain of event
+        handlers (usually the chain has a length of one).  If this
+        succeeds, the function exits.
+
+        5. If the object is a Window and the event is a
+        CommandEvent, ProcessEvent is recursively applied to the
+        parent window's event handler.  If this returns TRUE, the
+        function exits.
+
+        6. Finally, ProcessEvent is called on the App object.
+
+        See also:
+
+        EvtHandler::SearchEventTable"""
+        pass
+
+    def SetEvtHandlerEnabled(self, enabled):
+        """Enable or disable the event handler.
+
+        You can use this function to avoid having to remove the event
+        handler from the chain, for example when implementing a dialog
+        editor and changing from edit to test mode."""
+        pass
+
+    def SetNextHandler(self, handler):
+        """Set the pointer to the next handler."""
+        pass
+
+    def SetPreviousHandler(self, handler):
+        """Set the pointer to the previous handler."""
+        pass
+
+