Adding overview docs and a couple tweaks to the demo.

[wxWidgets.git] / wxPython / src / _event.i

diff --git a/wxPython/src/_event.i b/wxPython/src/_event.i
index 979fbf16049de7adcd1e937fedcf9b28a258f1fd..0632593d0e8792339eb4ceddcf9cf24b84a178c6 100644 (file)
--- a/wxPython/src/_event.i
+++ b/wxPython/src/_event.i
@@ -149,6 +149,7 @@ wxEventType wxNewEventType();
 %constant wxEventType wxEVT_ICONIZE;
 %constant wxEventType wxEVT_MAXIMIZE;
 %constant wxEventType wxEVT_MOUSE_CAPTURE_CHANGED;
 %constant wxEventType wxEVT_ICONIZE;
 %constant wxEventType wxEVT_MAXIMIZE;
 %constant wxEventType wxEVT_MOUSE_CAPTURE_CHANGED;

+%constant wxEventType wxEVT_MOUSE_CAPTURE_LOST;

 %constant wxEventType wxEVT_PAINT;
 %constant wxEventType wxEVT_ERASE_BACKGROUND;
 %constant wxEventType wxEVT_NC_PAINT;
 %constant wxEventType wxEVT_PAINT;
 %constant wxEventType wxEVT_ERASE_BACKGROUND;
 %constant wxEventType wxEVT_NC_PAINT;


@@ -235,6 +236,7 @@ EVT_WINDOW_CREATE = wx.PyEventBinder( wxEVT_CREATE )
 EVT_WINDOW_DESTROY = wx.PyEventBinder( wxEVT_DESTROY )
 EVT_SET_CURSOR = wx.PyEventBinder( wxEVT_SET_CURSOR )
 EVT_MOUSE_CAPTURE_CHANGED = wx.PyEventBinder( wxEVT_MOUSE_CAPTURE_CHANGED )
 EVT_WINDOW_DESTROY = wx.PyEventBinder( wxEVT_DESTROY )
 EVT_SET_CURSOR = wx.PyEventBinder( wxEVT_SET_CURSOR )
 EVT_MOUSE_CAPTURE_CHANGED = wx.PyEventBinder( wxEVT_MOUSE_CAPTURE_CHANGED )

+EVT_MOUSE_CAPTURE_LOST = wx.PyEventBinder( wxEVT_MOUSE_CAPTURE_LOST )         

 
 EVT_LEFT_DOWN = wx.PyEventBinder( wxEVT_LEFT_DOWN )
 EVT_LEFT_UP = wx.PyEventBinder( wxEVT_LEFT_UP )
 
 EVT_LEFT_DOWN = wx.PyEventBinder( wxEVT_LEFT_DOWN )
 EVT_LEFT_UP = wx.PyEventBinder( wxEVT_LEFT_UP )


@@ -431,14 +433,13 @@ it returns false. Note: Exists only for optimization purposes.", "");
 
     DocDeclStr(
         void , Skip(bool skip = true),
 
     DocDeclStr(
         void , Skip(bool skip = true),

-        "Called by an event handler, it controls whether additional event
-handlers bound to this event will be called after the current event
-handler returns.  Skip(false) (the default setting) will prevent
-additional event handlers from being called and control will be
-returned to the sender of the event immediately after the current
-handler has finished.  Skip(True) will cause the event processing
-system to continue searching for a handler function for this event.
-", "");
+        "This method can be used inside an event handler to control whether
+further event handlers bound to this event will be called after the
+current one returns. Without Skip() (or equivalently if Skip(False) is
+used), the event will not be processed any more. If Skip(True) is
+called, the event processing system continues searching for a further
+handler function for this event, even though it has been processed
+already in the current handler.", "");

 
     DocDeclStr(
         bool , GetSkipped() const,
 
     DocDeclStr(
         bool , GetSkipped() const,


@@ -473,6 +474,13 @@ example, you can use the value returned by an earlier call to
     // all derived classes must implement it because otherwise wxPostEvent()
     // for them wouldn't work (it needs to do a copy of the event)
     virtual wxEvent *Clone() /* =0*/;
     // all derived classes must implement it because otherwise wxPostEvent()
     // for them wouldn't work (it needs to do a copy of the event)
     virtual wxEvent *Clone() /* =0*/;

+
+    %property(EventObject, GetEventObject, SetEventObject, doc="See `GetEventObject` and `SetEventObject`");
+    %property(EventType, GetEventType, SetEventType, doc="See `GetEventType` and `SetEventType`");
+    %property(Id, GetId, SetId, doc="See `GetId` and `SetId`");
+    %property(Skipped, GetSkipped, doc="See `GetSkipped`");
+    %property(Timestamp, GetTimestamp, SetTimestamp, doc="See `GetTimestamp` and `SetTimestamp`");
+    

 };
 
 
 };
 
 


@@ -601,6 +609,12 @@ deselection), or a boolean value representing the value of a checkbox.", "");
 
     virtual wxEvent *Clone() const;
 
 
     virtual wxEvent *Clone() const;
 

+    %property(ClientData, GetClientData, SetClientData, doc="See `GetClientData` and `SetClientData`");
+    %property(ClientObject, GetClientObject, SetClientObject, doc="See `GetClientObject` and `SetClientObject`");
+    %property(ExtraLong, GetExtraLong, SetExtraLong, doc="See `GetExtraLong` and `SetExtraLong`");
+    %property(Int, GetInt, SetInt, doc="See `GetInt` and `SetInt`");
+    %property(Selection, GetSelection, doc="See `GetSelection`");
+    %property(String, GetString, SetString, doc="See `GetString` and `SetString`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -663,8 +677,8 @@ Events
     EVT_SCROLL_PAGEDOWN         page down events
     EVT_SCROLL_THUMBTRACK       thumbtrack events (frequent events sent
                                 as the user drags the 'thumb')
     EVT_SCROLL_PAGEDOWN         page down events
     EVT_SCROLL_THUMBTRACK       thumbtrack events (frequent events sent
                                 as the user drags the 'thumb')

-    EVT_SCROLL_THUMBRELEASE     thumb release events.
-    EVT_SCROLL_ENDSCROLL        End of scrolling
+    EVT_SCROLL_THUMBRELEASE     thumb release events
+    EVT_SCROLL_CHANGED          End of scrolling

     =======================     ==========================================
 
 Note
     =======================     ==========================================
 
 Note


@@ -672,17 +686,17 @@ Note
     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually
     dragging the thumb using the mouse and releasing it (This
     EVT_SCROLL_THUMBRELEASE event is also followed by an
     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually
     dragging the thumb using the mouse and releasing it (This
     EVT_SCROLL_THUMBRELEASE event is also followed by an

-    EVT_SCROLL_ENDSCROLL event).
+    EVT_SCROLL_CHANGED event).

 
 

-    The EVT_SCROLL_ENDSCROLL event also occurs when using the keyboard
+    The EVT_SCROLL_CHANGED event also occurs when using the keyboard

     to change the thumb position, and when clicking next to the thumb
     (In all these cases the EVT_SCROLL_THUMBRELEASE event does not
     happen).
 
     to change the thumb position, and when clicking next to the thumb
     (In all these cases the EVT_SCROLL_THUMBRELEASE event does not
     happen).
 

-    In short, the EVT_SCROLL_ENDSCROLL event is triggered when
+    In short, the EVT_SCROLL_CHANGED event is triggered when

     scrolling/ moving has finished. The only exception (unfortunately)
     is that changing the thumb position using the mousewheel does give
     scrolling/ moving has finished. The only exception (unfortunately)
     is that changing the thumb position using the mousewheel does give

-    a EVT_SCROLL_THUMBRELEASE event but NOT an EVT_SCROLL_ENDSCROLL
+    a EVT_SCROLL_THUMBRELEASE event but NOT an EVT_SCROLL_CHANGED

     event.
 ");
 
     event.
 ");
 


@@ -705,6 +719,9 @@ the scrollbar.", "");
 
     void SetOrientation(int orient);
     void SetPosition(int pos);
 
     void SetOrientation(int orient);
     void SetPosition(int pos);

+    
+    %property(Orientation, GetOrientation, SetOrientation, doc="See `GetOrientation` and `SetOrientation`");
+    %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`");

 };
 
 
 };
 
 


@@ -727,8 +744,8 @@ Events
     EVT_SCROLLWIN_PAGEDOWN         page down events
     EVT_SCROLLWIN_THUMBTRACK       thumbtrack events (frequent events sent
                                    as the user drags the 'thumb')
     EVT_SCROLLWIN_PAGEDOWN         page down events
     EVT_SCROLLWIN_THUMBTRACK       thumbtrack events (frequent events sent
                                    as the user drags the 'thumb')

-    EVT_SCROLLWIN_THUMBRELEASE     thumb release events.
-    EVT_SCROLLWIN_ENDSCROLL        End of scrolling
+    EVT_SCROLLWIN_THUMBRELEASE     thumb release events
+    EVT_SCROLLWIN_CHANGED          End of scrolling

     ==========================     ==========================================
 
 :see: `wx.ScrollEvent`
     ==========================     ==========================================
 
 :see: `wx.ScrollEvent`


@@ -753,6 +770,9 @@ need to query the window itself for the current position in that case.", "");
 
     void SetOrientation(int orient);
     void SetPosition(int pos);
 
     void SetOrientation(int orient);
     void SetPosition(int pos);

+
+    %property(Orientation, GetOrientation, SetOrientation, doc="See `GetOrientation` and `SetOrientation`");
+    %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -822,6 +842,9 @@ enum
 class  wxMouseEvent : public wxEvent
 {
 public:
 class  wxMouseEvent : public wxEvent
 {
 public:

+    // turn off this typemap
+    %typemap(out) wxMouseEvent*;    
+    

     DocCtorStr(
         wxMouseEvent(wxEventType mouseType = wxEVT_NULL),
 "Constructs a wx.MouseEvent.  Valid event types are:
     DocCtorStr(
         wxMouseEvent(wxEventType mouseType = wxEVT_NULL),
 "Constructs a wx.MouseEvent.  Valid event types are:


@@ -840,6 +863,8 @@ public:
     * wxEVT_MOTION
     * wxEVT_MOUSEWHEEL ", "");
 
     * wxEVT_MOTION
     * wxEVT_MOUSEWHEEL ", "");
 

+    // Turn it back on again
+    %typemap(out) wxMouseEvent* { $result = wxPyMake_wxObject($1, $owner); }

 
     DocDeclStr(
         bool , IsButton() const,
 
     DocDeclStr(
         bool , IsButton() const,


@@ -1089,6 +1114,15 @@ public:
     int           m_wheelRotation;
     int           m_wheelDelta;
     int           m_linesPerAction;
     int           m_wheelRotation;
     int           m_wheelDelta;
     int           m_linesPerAction;

+
+    %property(Button, GetButton, doc="See `GetButton`");
+    %property(LinesPerAction, GetLinesPerAction, doc="See `GetLinesPerAction`");
+    %property(LogicalPosition, GetLogicalPosition, doc="See `GetLogicalPosition`");
+    %property(Position, GetPosition, doc="See `GetPosition`");
+    %property(WheelDelta, GetWheelDelta, doc="See `GetWheelDelta`");
+    %property(WheelRotation, GetWheelRotation, doc="See `GetWheelRotation`");
+    %property(X, GetX, doc="See `GetX`");
+    %property(Y, GetY, doc="See `GetY`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1131,6 +1165,9 @@ public:
         bool , HasCursor() const,
         "Returns true if the cursor specified by this event is a valid cursor.", "");
 
         bool , HasCursor() const,
         "Returns true if the cursor specified by this event is a valid cursor.", "");
 

+    %property(Cursor, GetCursor, SetCursor, doc="See `GetCursor` and `SetCursor`");
+    %property(X, GetX, doc="See `GetX`");
+    %property(Y, GetY, doc="See `GetY`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1312,7 +1349,8 @@ Note that in Unicode build, the returned value is meaningful only if
 the user entered a character that can be represented in current
 locale's default charset. You can obtain the corresponding Unicode
 character using `GetUnicodeKey`.", "");
 the user entered a character that can be represented in current
 locale's default charset. You can obtain the corresponding Unicode
 character using `GetUnicodeKey`.", "");

-    %pythoncode { KeyCode = GetKeyCode }
+    
+//    %pythoncode { KeyCode = GetKeyCode }  this will be hidden by the property

 
 
     %extend {
 
 
     %extend {


@@ -1393,6 +1431,15 @@ public:
 
     wxUint32      m_rawCode;
     wxUint32      m_rawFlags;
 
     wxUint32      m_rawCode;
     wxUint32      m_rawFlags;

+
+    %property(KeyCode, GetKeyCode, doc="See `GetKeyCode`");
+    %property(Modifiers, GetModifiers, doc="See `GetModifiers`");
+    %property(Position, GetPosition, doc="See `GetPosition`");
+    %property(RawKeyCode, GetRawKeyCode, doc="See `GetRawKeyCode`");
+    %property(RawKeyFlags, GetRawKeyFlags, doc="See `GetRawKeyFlags`");
+    %property(UnicodeKey, GetUnicodeKey, SetUnicodeKey, doc="See `GetUnicodeKey` and `SetUnicodeKey`");
+    %property(X, GetX, doc="See `GetX`");
+    %property(Y, GetY, doc="See `GetY`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1438,9 +1485,11 @@ event.", "");
         }
     }
 
         }
     }
 

-public:

     wxSize m_size;
     wxRect m_rect;
     wxSize m_size;
     wxRect m_rect;

+    
+    %property(Rect, GetRect, SetRect, doc="See `GetRect` and `SetRect`");
+    %property(Size, GetSize, SetSize, doc="See `GetSize` and `SetSize`");

 };
 
 
 };
 
 


@@ -1470,6 +1519,10 @@ public:
         m_pos =  property(GetPosition, SetPosition)
         m_rect = property(GetRect, SetRect)
     }
         m_pos =  property(GetPosition, SetPosition)
         m_rect = property(GetRect, SetRect)
     }

+
+    %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`");
+    %property(Rect, GetRect, SetRect, doc="See `GetRect` and `SetRect`");
+    

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1531,6 +1584,8 @@ public:
         "Returns the device context the event handler should draw upon.  If
 ``None`` is returned then create a temporary `wx.ClientDC` and use
 that instead.", "");
         "Returns the device context the event handler should draw upon.  If
 ``None`` is returned then create a temporary `wx.ClientDC` and use
 that instead.", "");

+
+    %property(DC, GetDC, doc="See `GetDC`"); 

 };
 
 
 };
 
 


@@ -1563,15 +1618,22 @@ window which is going to receive focus for the wxEVT_KILL_FOCUS event.
 Warning: the window returned may be None!", "");
 
     void SetWindow(wxWindow *win);
 Warning: the window returned may be None!", "");
 
     void SetWindow(wxWindow *win);

+
+    %property(Window, GetWindow, SetWindow, doc="See `GetWindow` and `SetWindow`");

 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 DocStr(wxChildFocusEvent,
 };
 
 //---------------------------------------------------------------------------
 %newgroup;
 
 DocStr(wxChildFocusEvent,

-"wx.ChildFocusEvent notifies the parent that a child has received the
-focus.  Unlike `wx.FocusEvent` it is propagated up the window
-heirarchy.", "");
+"A child focus event is sent to a (parent-)window when one of its child
+windows gains focus, so that the window could restore the focus back
+to its corresponding child if it loses it now and regains later.
+
+Notice that child window is the direct child of the window receiving
+the event, and so may not be the actual widget recieving focus if it
+is further down the containment heirarchy.  Use `wx.Window.FindFocus`
+to get the widget that is actually receiving focus.", "");

 
 
 class wxChildFocusEvent : public wxCommandEvent
 
 
 class wxChildFocusEvent : public wxCommandEvent


@@ -1583,8 +1645,10 @@ public:
 
     DocDeclStr(
         wxWindow *, GetWindow() const,
 
     DocDeclStr(
         wxWindow *, GetWindow() const,

-        "The window which has just received the focus.", "");
+        "The window, or (grand)parent of the window which has just received the
+focus.", "");

 
 

+    %property(Window, GetWindow, doc="See `GetWindow`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1629,6 +1693,7 @@ public:
         "Returns true if the application or window is being activated, false
 otherwise.", "");
 
         "Returns true if the application or window is being activated, false
 otherwise.", "");
 

+    %property(Active, GetActive, doc="See `GetActive`");

 };
 
 
 };
 
 


@@ -1709,6 +1774,8 @@ be used with the OPEN and CLOSE events.", "");
         "Returns the menu which is being opened or closed. This method should
 only be used with the OPEN and CLOSE events.", "");
 
         "Returns the menu which is being opened or closed. This method should
 only be used with the OPEN and CLOSE events.", "");
 

+    %property(Menu, GetMenu, doc="See `GetMenu`");
+    %property(MenuId, GetMenuId, doc="See `GetMenuId`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -1789,6 +1856,7 @@ event. Vetoing a window close event is not possible if the calling
 code wishes to force the application to exit, and so this function
 must be called to check this.", "");
 
 code wishes to force the application to exit, and so this function
 must be called to check this.", "");
 

+    %property(LoggingOff, GetLoggingOff, SetLoggingOff, doc="See `GetLoggingOff` and `SetLoggingOff`");

 };
 
 
 };
 
 


@@ -1806,6 +1874,7 @@ public:
     void SetShow(bool show);
     bool GetShow() const;
 
     void SetShow(bool show);
     bool GetShow() const;
 

+    %property(Show, GetShow, SetShow, doc="See `GetShow` and `SetShow`");

 };
 
 
 };
 
 


@@ -1899,6 +1968,10 @@ public:
             return list;
         }
     }
             return list;
         }
     }

+
+    %property(Files, GetFiles, doc="See `GetFiles`");
+    %property(NumberOfFiles, GetNumberOfFiles, doc="See `GetNumberOfFiles`");
+    %property(Position, GetPosition, doc="See `GetPosition`");

 };
 
 
 };
 
 


@@ -2095,6 +2168,10 @@ The mode may be one of the following values:
 all windows, or only to those which specify that they will process the
 events.", "");
 
 all windows, or only to those which specify that they will process the
 events.", "");
 

+    %property(Checked, GetChecked, Check, doc="See `GetChecked`");
+    %property(Enabled, GetEnabled, Enable, doc="See `GetEnabled`");
+    %property(Shown, GetShown, Show, doc="See `GetShown`");
+    %property(Text, GetText, SetText, doc="See `GetText` and `SetText`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2144,6 +2221,31 @@ public:
         "Returns the window that gained the capture, or ``None`` if it was a
 non-wxWidgets window.", "");
 
         "Returns the window that gained the capture, or ``None`` if it was a
 non-wxWidgets window.", "");
 

+    %property(CapturedWindow, GetCapturedWindow, doc="See `GetCapturedWindow`");
+};
+
+//---------------------------------------------------------------------------
+%newgroup;
+
+DocStr(wxMouseCaptureLostEvent,
+"A mouse capture lost event is sent to a window that obtained mouse
+capture, which was subsequently loss due to \"external\" event, for
+example when a dialog box is shown or if another application captures
+the mouse.
+
+If this happens, this event is sent to all windows that are on the
+capture stack (i.e. a window that called `wx.Window.CaptureMouse`, but
+didn't call `wx.Window.ReleaseMouse` yet). The event is *not* sent
+if the capture changes because of a call to CaptureMouse or
+ReleaseMouse.
+
+This event is currently emitted under Windows only.
+", "");
+
+class wxMouseCaptureLostEvent : public wxEvent
+{
+public:
+    wxMouseCaptureLostEvent(wxWindowID winid = 0);

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2181,6 +2283,7 @@ public:
     void SetChangedWindow(wxWindow* win);
     wxWindow* GetChangedWindow();
 
     void SetChangedWindow(wxWindow* win);
     wxWindow* GetChangedWindow();
 

+    %property(ChangedWindow, GetChangedWindow, SetChangedWindow, doc="See `GetChangedWindow` and `SetChangedWindow`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2204,6 +2307,8 @@ public:
         "App should set this if it changes the palette.", "");
 
     bool GetPaletteRealized() const;
         "App should set this if it changes the palette.", "");
 
     bool GetPaletteRealized() const;

+
+    %property(PaletteRealized, GetPaletteRealized, SetPaletteRealized, doc="See `GetPaletteRealized` and `SetPaletteRealized`");    

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2286,6 +2391,10 @@ This is required for proper navogation over radio buttons.", "");
         WinChange,
         FromTab
     };
         WinChange,
         FromTab
     };

+
+    %property(CurrentFocus, GetCurrentFocus, SetCurrentFocus, doc="See `GetCurrentFocus` and `SetCurrentFocus`");
+    %property(Direction, GetDirection, SetDirection, doc="See `GetDirection` and `SetDirection`");
+    

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2305,6 +2414,7 @@ public:
         wxWindow *, GetWindow() const,
         "Returns the window that this event refers to.", "");
 
         wxWindow *, GetWindow() const,
         "Returns the window that this event refers to.", "");
 

+    %property(Window, GetWindow, doc="See `GetWindow`");

 };
 
 
 };
 
 


@@ -2326,6 +2436,8 @@ public:
     DocDeclStr(
         wxWindow *, GetWindow() const,
         "Returns the window that this event refers to.", "");
     DocDeclStr(
         wxWindow *, GetWindow() const,
         "Returns the window that this event refers to.", "");

+
+    %property(Window, GetWindow, doc="See `GetWindow`");

 };
 
 
 };
 
 


@@ -2357,6 +2469,7 @@ be shown.", "");
         void , SetPosition(const wxPoint& pos),
         "Sets the position at which the menu should be shown.", "");
 
         void , SetPosition(const wxPoint& pos),
         "Sets the position at which the menu should be shown.", "");
 

+    %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`");

 };
 
 //---------------------------------------------------------------------------
 };
 
 //---------------------------------------------------------------------------


@@ -2550,6 +2663,7 @@ public:
         "Sets the date carried by the event, normally only used by the library
 internally.", "");
 
         "Sets the date carried by the event, normally only used by the library
 internally.", "");
 

+    %property(Date, GetDate, SetDate, doc="See `GetDate` and `SetDate`");

 
 };
 
 
 };