X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/aeee37c362c178e4b79702e8e61869cd9dcb65ff..46ae103b9f08fc4e447d16a6a92b03cf55ee3189:/wxPython/src/_event.i diff --git a/wxPython/src/_event.i b/wxPython/src/_event.i index 8feb6f6934..5331cb0fc8 100644 --- a/wxPython/src/_event.i +++ b/wxPython/src/_event.i @@ -113,7 +113,9 @@ wxEventType wxNewEventType(); %constant wxEventType wxEVT_SCROLL_PAGEDOWN; %constant wxEventType wxEVT_SCROLL_THUMBTRACK; %constant wxEventType wxEVT_SCROLL_THUMBRELEASE; -%constant wxEventType wxEVT_SCROLL_ENDSCROLL; +%constant wxEventType wxEVT_SCROLL_CHANGED; +%pythoncode { wxEVT_SCROLL_ENDSCROLL = wxEVT_SCROLL_CHANGED } + // Scroll events from wxWindow %constant wxEventType wxEVT_SCROLLWIN_TOP; @@ -163,6 +165,8 @@ wxEventType wxNewEventType(); %constant wxEventType wxEVT_UPDATE_UI; %constant wxEventType wxEVT_SIZING; %constant wxEventType wxEVT_MOVING; +%constant wxEventType wxEVT_HIBERNATE; + // Generic command events // Note: a click is a higher-level event than button down/up @@ -203,6 +207,7 @@ EVT_KILL_FOCUS = wx.PyEventBinder( wxEVT_KILL_FOCUS ) EVT_CHILD_FOCUS = wx.PyEventBinder( wxEVT_CHILD_FOCUS ) EVT_ACTIVATE = wx.PyEventBinder( wxEVT_ACTIVATE ) EVT_ACTIVATE_APP = wx.PyEventBinder( wxEVT_ACTIVATE_APP ) +EVT_HIBERNATE = wx.PyEventBinder( wxEVT_HIBERNATE ) EVT_END_SESSION = wx.PyEventBinder( wxEVT_END_SESSION ) EVT_QUERY_END_SESSION = wx.PyEventBinder( wxEVT_QUERY_END_SESSION ) EVT_DROP_FILES = wx.PyEventBinder( wxEVT_DROP_FILES ) @@ -270,7 +275,7 @@ EVT_SCROLLWIN_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLLWIN_PAGEDOWN ) EVT_SCROLLWIN_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBTRACK ) EVT_SCROLLWIN_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLLWIN_THUMBRELEASE ) -%# Scrolling from wxSlider and wxScrollBar +%# Scrolling from wx.Slider and wx.ScrollBar EVT_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, wxEVT_SCROLL_BOTTOM, wxEVT_SCROLL_LINEUP, @@ -279,7 +284,7 @@ EVT_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, wxEVT_SCROLL_PAGEDOWN, wxEVT_SCROLL_THUMBTRACK, wxEVT_SCROLL_THUMBRELEASE, - wxEVT_SCROLL_ENDSCROLL, + wxEVT_SCROLL_CHANGED, ]) EVT_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP ) @@ -290,9 +295,10 @@ EVT_SCROLL_PAGEUP = wx.PyEventBinder( wxEVT_SCROLL_PAGEUP ) EVT_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN ) EVT_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK ) EVT_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE ) -EVT_SCROLL_ENDSCROLL = wx.PyEventBinder( wxEVT_SCROLL_ENDSCROLL ) - -%# Scrolling from wxSlider and wxScrollBar, with an id +EVT_SCROLL_CHANGED = wx.PyEventBinder( wxEVT_SCROLL_CHANGED ) +EVT_SCROLL_ENDSCROLL = EVT_SCROLL_CHANGED + +%# Scrolling from wx.Slider and wx.ScrollBar, with an id EVT_COMMAND_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, wxEVT_SCROLL_BOTTOM, wxEVT_SCROLL_LINEUP, @@ -301,7 +307,7 @@ EVT_COMMAND_SCROLL = wx.PyEventBinder([ wxEVT_SCROLL_TOP, wxEVT_SCROLL_PAGEDOWN, wxEVT_SCROLL_THUMBTRACK, wxEVT_SCROLL_THUMBRELEASE, - wxEVT_SCROLL_ENDSCROLL, + wxEVT_SCROLL_CHANGED, ], 1) EVT_COMMAND_SCROLL_TOP = wx.PyEventBinder( wxEVT_SCROLL_TOP, 1) @@ -312,7 +318,8 @@ EVT_COMMAND_SCROLL_PAGEUP = wx.PyEventBinder( wxEVT_SCROLL_PAGEUP, 1) EVT_COMMAND_SCROLL_PAGEDOWN = wx.PyEventBinder( wxEVT_SCROLL_PAGEDOWN, 1) EVT_COMMAND_SCROLL_THUMBTRACK = wx.PyEventBinder( wxEVT_SCROLL_THUMBTRACK, 1) EVT_COMMAND_SCROLL_THUMBRELEASE = wx.PyEventBinder( wxEVT_SCROLL_THUMBRELEASE, 1) -EVT_COMMAND_SCROLL_ENDSCROLL = wx.PyEventBinder( wxEVT_SCROLL_ENDSCROLL, 1) +EVT_COMMAND_SCROLL_CHANGED = wx.PyEventBinder( wxEVT_SCROLL_CHANGED, 1) +EVT_COMMAND_SCROLL_ENDSCROLL = EVT_COMMAND_SCROLL_CHANGED EVT_BUTTON = wx.PyEventBinder( wxEVT_COMMAND_BUTTON_CLICKED, 1) EVT_CHECKBOX = wx.PyEventBinder( wxEVT_COMMAND_CHECKBOX_CLICKED, 1) @@ -357,22 +364,56 @@ EVT_CONTEXT_MENU = wx.PyEventBinder( wxEVT_CONTEXT_MENU ) //--------------------------------------------------------------------------- %newgroup; +DocStr(wxEvent, +"An event is a structure holding information about an event passed to a +callback or member function. wx.Event is an abstract base class for +other event classes", ""); + class wxEvent : public wxObject { public: // wxEvent(int winid = 0, wxEventType commandType = wxEVT_NULL); // *** This class is now an ABC ~wxEvent(); - void SetEventType(wxEventType typ); - wxEventType GetEventType() const; - wxObject *GetEventObject() const; - void SetEventObject(wxObject *obj); + DocDeclStr( + void , SetEventType(wxEventType typ), + "Sets the specific type of the event.", ""); + + DocDeclStr( + wxEventType , GetEventType() const, + "Returns the identifier of the given event type, such as +``wxEVT_COMMAND_BUTTON_CLICKED``.", ""); + + DocDeclStr( + wxObject *, GetEventObject() const, + "Returns the object (usually a window) associated with the event, if +any.", ""); + + DocDeclStr( + void , SetEventObject(wxObject *obj), + "Sets the originating object, or in other words, obj is normally the +object that is sending the event.", ""); + long GetTimestamp() const; void SetTimestamp(long ts = 0); - int GetId() const; - void SetId(int Id); + + DocDeclStr( + int , GetId() const, + "Returns the identifier associated with this event, such as a button +command id.", ""); + + DocDeclStr( + void , SetId(int Id), + "Set's the ID for the event. This is usually the ID of the window that +is sending the event, but it can also be a command id from a menu +item, etc.", ""); + - bool IsCommandEvent() const; + DocDeclStr( + bool , IsCommandEvent() const, + "Returns true if the event is or is derived from `wx.CommandEvent` else +it returns false. Note: Exists only for optimization purposes.", ""); + DocDeclStr( void , Skip(bool skip = true), @@ -385,18 +426,34 @@ handler has finished. Skip(True) will cause the event processing system to continue searching for a handler function for this event. ", ""); - bool GetSkipped() const; + DocDeclStr( + bool , GetSkipped() const, + "Returns true if the event handler should be skipped, false otherwise. +:see: `Skip`", ""); + - // Determine if this event should be propagating to the parent window. - bool ShouldPropagate() const; + DocDeclStr( + bool , ShouldPropagate() const, + "Test if this event should be propagated to the parent window or not, +i.e. if the propagation level is currently greater than 0.", ""); + // Stop an event from propagating to its parent window, returns the old // propagation level value - int StopPropagation(); + DocDeclStr( + int , StopPropagation(), + "Stop the event from propagating to its parent window. Returns the old +propagation level value which may be later passed to +`ResumePropagation` to allow propagating the event again.", ""); + - // Resume the event propagation by restoring the propagation level - // (returned by StopPropagation()) - void ResumePropagation(int propagationLevel); + DocDeclStr( + void , ResumePropagation(int propagationLevel), + "Resume the event propagation by restoring the propagation level. (For +example, you can use the value returned by an earlier call to +`StopPropagation`.) +", ""); + // this function is used to create a copy of the event polymorphically and // all derived classes must implement it because otherwise wxPostEvent() @@ -408,7 +465,10 @@ system to continue searching for a handler function for this event. //--------------------------------------------------------------------------- %newgroup; -// Helper class to temporarily change an event not to propagate. +DocStr(wxPropagationDisabler, +"Helper class to temporarily change an event not to propagate. Simply +create an instance of this class and then whe it is destroyed the +propogation of the event will be restored.", ""); class wxPropagationDisabler { public: @@ -417,7 +477,10 @@ public: }; -// Another one to temporarily lower propagation level. +DocStr( wxPropagateOnce, +"A helper class that will temporarily lower propagation level of an +event. Simply create an instance of this class and then whe it is +destroyed the propogation of the event will be restored.", ""); class wxPropagateOnce { public: @@ -428,6 +491,11 @@ public: //--------------------------------------------------------------------------- %newgroup; +DocStr(wxCommandEvent, +"This event class contains information about command events, which +originate from a variety of simple controls, as well as menus and +toolbars.", ""); + class wxCommandEvent : public wxEvent { public: @@ -443,25 +511,53 @@ public: // void *GetClientObject() const { return m_clientObject; } - // Get listbox selection if single-choice - int GetSelection() const; + DocDeclStr( + int , GetSelection() const, + "Returns item index for a listbox or choice selection event (not valid +for a deselection).", ""); + - // Set/Get listbox/choice selection string void SetString(const wxString& s); - wxString GetString() const; + DocDeclStr( + wxString , GetString() const, + "Returns item string for a listbox or choice selection event (not valid +for a deselection).", ""); + - // Get checkbox value - bool IsChecked() const; + DocDeclStr( + bool , IsChecked() const, + "This method can be used with checkbox and menu events: for the +checkboxes, the method returns true for a selection event and false +for a deselection one. For the menu events, this method indicates if +the menu item just has become checked or unchecked (and thus only +makes sense for checkable menu items).", ""); + %pythoncode { Checked = IsChecked } - // True if the listbox event was a selection. - bool IsSelection() const; + DocDeclStr( + bool , IsSelection() const, + "For a listbox or similar event, returns true if it is a selection, +false if it is a deselection.", ""); + void SetExtraLong(long extraLong); - long GetExtraLong() const; + DocDeclStr( + long , GetExtraLong() const, + "Returns extra information dependant on the event objects type. If the +event comes from a listbox selection, it is a boolean determining +whether the event was a selection (true) or a deselection (false). A +listbox deselection only occurs for multiple-selection boxes, and in +this case the index and string values are indeterminate and the +listbox must be examined by the application.", ""); + void SetInt(int i); - long GetInt() const; + DocDeclStr( + long , GetInt() const, + "Returns the integer identifier corresponding to a listbox, choice or +radiobox selection (only if the event was a selection, not a +deselection), or a boolean value representing the value of a checkbox.", ""); + virtual wxEvent *Clone() const; @@ -470,37 +566,103 @@ public: //--------------------------------------------------------------------------- %newgroup; -// this class adds a possibility to react (from the user) code to a control -// notification: allow or veto the operation being reported. +DocStr(wxNotifyEvent, +"An instance of this class (or one of its derived classes) is sent from +a control when the control's state is being changed and the control +allows that change to be prevented from happening. The event handler +can call `Veto` or `Allow` to tell the control what to do.", ""); + class wxNotifyEvent : public wxCommandEvent { public: wxNotifyEvent(wxEventType commandType = wxEVT_NULL, int winid = 0); - // veto the operation (usually it's allowed by default) - void Veto(); + DocDeclStr( + void , Veto(), + "Prevents the change announced by this event from happening. + +It is in general a good idea to notify the user about the reasons for +vetoing the change because otherwise the applications behaviour (which +just refuses to do what the user wants) might be quite surprising.", ""); + - // allow the operation if it was disabled by default - void Allow(); + DocDeclStr( + void , Allow(), + "This is the opposite of `Veto`: it explicitly allows the event to be +processed. For most events it is not necessary to call this method as +the events are allowed anyhow but some are forbidden by default (this +will be mentioned in the corresponding event description).", ""); + - // for implementation code only: is the operation allowed? - bool IsAllowed(); + DocDeclStr( + bool , IsAllowed(), + "Returns true if the change is allowed (`Veto` hasn't been called) or +false otherwise (if it was).", ""); + }; //--------------------------------------------------------------------------- %newgroup; -// Scroll event class, derived form wxCommandEvent. wxScrollEvents are -// sent by wxSlider and wxScrollBar. +DocStr(wxScrollEvent, +"A scroll event holds information about events sent from stand-alone +scrollbars and sliders. Note that scrolled windows do not send +instnaces of this event class, but send the `wx.ScrollWinEvent` +instead.", " + +Events +------- + ======================= ========================================== + EVT_SCROLL Used to bind all scroll events + EVT_SCROLL_TOP scroll-to-top events (minimum position) + EVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position) + EVT_SCROLL_LINEUP line up events + EVT_SCROLL_LINEDOWN line down events + EVT_SCROLL_PAGEUP page up events + 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 + ======================= ========================================== + +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 + EVT_SCROLL_ENDSCROLL event). + + The EVT_SCROLL_ENDSCROLL 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). + + In short, the EVT_SCROLL_ENDSCROLL event is triggered when + 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 + event. +"); + class wxScrollEvent : public wxCommandEvent { public: - wxScrollEvent(wxEventType commandType = wxEVT_NULL, - int winid = 0, int pos = 0, int orient = 0); + DocCtorStr( + wxScrollEvent(wxEventType commandType = wxEVT_NULL, + int winid = 0, int pos = 0, int orient = 0), + "", ""); - int GetOrientation() const; - int GetPosition() const; + DocDeclStr( + int , GetOrientation() const, + "Returns wx.HORIZONTAL or wx.VERTICAL, depending on the orientation of +the scrollbar.", ""); + + DocDeclStr( + int , GetPosition() const, + "Returns the position of the scrollbar.", ""); + void SetOrientation(int orient); void SetPosition(int pos); }; @@ -509,16 +671,46 @@ public: //--------------------------------------------------------------------------- %newgroup; -// ScrollWin event class, derived fom wxEvent. wxScrollWinEvents -// are sent by wxWindow. +DocStr(wxScrollWinEvent, +"A wx.ScrollWinEvent holds information about scrolling and is sent from +scrolling windows.", " + +Events +------- + ========================== ========================================== + EVT_SCROLLWIN Used to bind all scrolled window scroll events + EVT_SCROLLWIN_TOP scroll-to-top events (minimum position) + EVT_SCROLLWIN_BOTTOM scroll-to-bottom events (maximum position) + EVT_SCROLLWIN_LINEUP line up events + EVT_SCROLLWIN_LINEDOWN line down events + EVT_SCROLLWIN_PAGEUP page up events + 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 + ========================== ========================================== + +:see: `wx.ScrollEvent` +"); + class wxScrollWinEvent : public wxEvent { public: wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, int orient = 0); - int GetOrientation() const; - int GetPosition() const; + DocDeclStr( + int , GetOrientation() const, + "Returns wx.HORIZONTAL or wx.VERTICAL, depending on the orientation of +the scrollbar.", ""); + + DocDeclStr( + int , GetPosition() const, + "Returns the position of the scrollbar for the thumb track and release +events. Note that this field can't be used for the other events, you +need to query the window itself for the current position in that case.", ""); + void SetOrientation(int orient); void SetPosition(int pos); }; @@ -526,6 +718,55 @@ public: //--------------------------------------------------------------------------- %newgroup; + +DocStr(wxMouseEvent, +"This event class contains information about the events generated by +the mouse: they include mouse buttons press and release events and +mouse move events. + +All mouse events involving the buttons use ``wx.MOUSE_BTN_LEFT`` for +the left mouse button, ``wx.MOUSE_BTN_MIDDLE`` for the middle one and +``wx.MOUSE_BTN_RIGHT`` for the right one. Note that not all mice have +a middle button so a portable application should avoid relying on the +events from it. + +Note the difference between methods like `LeftDown` and `LeftIsDown`: +the former returns true when the event corresponds to the left mouse +button click while the latter returns true if the left mouse button is +currently being pressed. For example, when the user is dragging the +mouse you can use `LeftIsDown` to test whether the left mouse button +is (still) depressed. Also, by convention, if `LeftDown` returns true, +`LeftIsDown` will also return true in wxWidgets whatever the +underlying GUI behaviour is (which is platform-dependent). The same +applies, of course, to other mouse buttons as well.", " + +Events +------- + ================== ============================================== + EVT_LEFT_DOWN Left mouse button down event. The handler + of this event should normally call + event.Skip() to allow the default processing + to take place as otherwise the window under + mouse wouldn't get the focus. + EVT_LEFT_UP Left mouse button up event + EVT_LEFT_DCLICK Left mouse button double click event + EVT_MIDDLE_DOWN Middle mouse button down event + EVT_MIDDLE_UP Middle mouse button up event + EVT_MIDDLE_DCLICK Middle mouse button double click event + EVT_RIGHT_DOWN Right mouse button down event + EVT_RIGHT_UP Right mouse button up event + EVT_RIGHT_DCLICK Right mouse button double click event + EVT_MOTION Event sent when the mouse is moving + EVT_ENTER_WINDOW Event sent when the mouse enters the + boundaries of a window. + EVT_LEAVE_WINDOW Sent when the mouse leaves the window's bounds + EVT_MOUSEWHEEL Mouse scroll wheel event + EVT_MOUSE_EVENTS Binds all mouse events at once. + ================== ============================================== + +"); + + // the symbolic names for the mouse buttons enum { @@ -541,80 +782,205 @@ enum class wxMouseEvent : public wxEvent { public: - wxMouseEvent(wxEventType mouseType = wxEVT_NULL); + DocCtorStr( + wxMouseEvent(wxEventType mouseType = wxEVT_NULL), +"Constructs a wx.MouseEvent. Valid event types are: + + * wxEVT_ENTER_WINDOW + * wxEVT_LEAVE_WINDOW + * wxEVT_LEFT_DOWN + * wxEVT_LEFT_UP + * wxEVT_LEFT_DCLICK + * wxEVT_MIDDLE_DOWN + * wxEVT_MIDDLE_UP + * wxEVT_MIDDLE_DCLICK + * wxEVT_RIGHT_DOWN + * wxEVT_RIGHT_UP + * wxEVT_RIGHT_DCLICK + * wxEVT_MOTION + * wxEVT_MOUSEWHEEL ", ""); - // Was it a button event? (*doesn't* mean: is any button *down*?) - bool IsButton() const; - // Was it a down event from this (or any) button? - bool ButtonDown(int but = wxMOUSE_BTN_ANY) const; + DocDeclStr( + bool , IsButton() const, + "Returns true if the event was a mouse button event (not necessarily a +button down event - that may be tested using `ButtonDown`).", ""); + - // Was it a dclick event from this (or any) button? - bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; + DocDeclStr( + bool , ButtonDown(int but = wxMOUSE_BTN_ANY) const, + "If the argument is omitted, this returns true if the event was any +mouse button down event. Otherwise the argument specifies which +button-down event shold be checked for (see `Button` for the possible +values).", ""); + - // Was it a up event from this (or any) button? - bool ButtonUp(int but = wxMOUSE_BTN_ANY) const; + DocDeclStr( + bool , ButtonDClick(int but = wxMOUSE_BTN_ANY) const, + "If the argument is omitted, this returns true if the event was any +mouse double click event. Otherwise the argument specifies which +double click event to check for (see `Button` for the possible +values).", ""); + - // Was the given button changing state? - bool Button(int but) const; + DocDeclStr( + bool , ButtonUp(int but = wxMOUSE_BTN_ANY) const, + "If the argument is omitted, this returns true if the event was any +mouse button up event. Otherwise the argument specifies which button +up event to check for (see `Button` for the possible values).", ""); + + + DocDeclStr( + bool , Button(int button) const, + "Returns true if the identified mouse button is changing state. Valid +values of button are: + + ==================== ===================================== + wx.MOUSE_BTN_LEFT check if left button was pressed + wx.MOUSE_BTN_MIDDLE check if middle button was pressed + wx.MOUSE_BTN_RIGHT check if right button was pressed + wx.MOUSE_BTN_ANY check if any button was pressed + ==================== ===================================== +", ""); + // Was the given button in Down state? bool ButtonIsDown(int but) const; - // Get the button which is changing state (wxMOUSE_BTN_NONE if none) - int GetButton() const; + DocDeclStr( + int , GetButton() const, + "Returns the mouse button which generated this event or +wx.MOUSE_BTN_NONE if no button is involved (for mouse move, enter or +leave event, for example). Otherwise wx.MOUSE_BTN_LEFT is returned for +the left button down, up and double click events, wx.MOUSE_BTN_MIDDLE +and wx.MOUSE_BTN_RIGHT for the same events for the middle and the +right buttons respectively.", ""); + - // Find state of shift/control keys - bool ControlDown() const; - bool MetaDown() const; - bool AltDown() const; - bool ShiftDown() const; + DocDeclStr( + bool , ControlDown() const, + "Returns true if the control key was down at the time of the event.", ""); + + DocDeclStr( + bool , MetaDown() const, + "Returns true if the Meta key was down at the time of the event.", ""); + + + DocDeclStr( + bool , AltDown() const, + "Returns true if the Alt key was down at the time of the event.", ""); + + DocDeclStr( + bool , ShiftDown() const, + "Returns true if the Shift key was down at the time of the event.", ""); + DocDeclStr( bool , CmdDown() const, "\"Cmd\" is a pseudo key which is the same as Control for PC and Unix platforms but the special \"Apple\" (a.k.a as \"Command\") key on -Macs: it makes often sense to use it instead of, say, `ControlDown` +Macs. It often makes sense to use it instead of, say, `ControlDown` because Cmd key is used for the same thing under Mac as Ctrl -elsewhere. The Ctrl still exists, it's just not used for this +elsewhere. The Ctrl key still exists, it's just not used for this purpose. So for non-Mac platforms this is the same as `ControlDown` and Macs this is the same as `MetaDown`.", ""); - // Find which event was just generated - bool LeftDown() const; - bool MiddleDown() const; - bool RightDown() const; - bool LeftUp() const; - bool MiddleUp() const; - bool RightUp() const; + DocDeclStr( + bool , LeftDown() const, + "Returns true if the left mouse button state changed to down.", ""); + + DocDeclStr( + bool , MiddleDown() const, + "Returns true if the middle mouse button state changed to down.", ""); + + DocDeclStr( + bool , RightDown() const, + "Returns true if the right mouse button state changed to down.", ""); + + + + DocDeclStr( + bool , LeftUp() const, + "Returns true if the left mouse button state changed to up.", ""); + + DocDeclStr( + bool , MiddleUp() const, + "Returns true if the middle mouse button state changed to up.", ""); + + DocDeclStr( + bool , RightUp() const, + "Returns true if the right mouse button state changed to up.", ""); + + - bool LeftDClick() const; - bool MiddleDClick() const; - bool RightDClick() const; + + DocDeclStr( + bool , LeftDClick() const, + "Returns true if the event was a left button double click.", ""); + + DocDeclStr( + bool , MiddleDClick() const, + "Returns true if the event was a middle button double click.", ""); + + DocDeclStr( + bool , RightDClick() const, + "Returns true if the event was a right button double click.", ""); + - // Find the current state of the mouse buttons (regardless - // of current event type) - bool LeftIsDown(); - bool MiddleIsDown(); - bool RightIsDown(); + + DocDeclStr( + bool , LeftIsDown(), + "Returns true if the left mouse button is currently down, independent +of the current event type. - // True if a button is down and the mouse is moving - bool Dragging() const; +Please notice that it is not the same as LeftDown which returns true +if the left mouse button was just pressed. Rather, it describes the +state of the mouse button before the event happened. - // True if the mouse is moving, and no button is down - bool Moving() const; +This event is usually used in the mouse event handlers which process +\"move mouse\" messages to determine whether the user is (still) +dragging the mouse.", ""); + + DocDeclStr( + bool , MiddleIsDown(), + "Returns true if the middle mouse button is currently down, independent +of the current event type.", ""); + + DocDeclStr( + bool , RightIsDown(), + "Returns true if the right mouse button is currently down, independent +of the current event type.", ""); + - // True if the mouse is just entering the window - bool Entering() const; + + DocDeclStr( + bool , Dragging() const, + "Returns true if this was a dragging event (motion while a button is +depressed).", ""); + - // True if the mouse is just leaving the window - bool Leaving() const; + DocDeclStr( + bool , Moving() const, + "Returns true if this was a motion event and no mouse buttons were +pressed. If any mouse button is held pressed, then this method returns +false and Dragging returns true.", ""); + + + DocDeclStr( + bool , Entering() const, + "Returns true if the mouse was entering the window.", ""); + + + DocDeclStr( + bool , Leaving() const, + "Returns true if the mouse was leaving the window.", ""); + DocStr(GetPosition, // sets the docstring for both - "Returns the position of the mouse in window coordinates when the event -happened.", ""); + "Returns the pixel position of the mouse in window coordinates when the +event happened.", ""); wxPoint GetPosition(); DocDeclAName( @@ -622,35 +988,51 @@ happened.", ""); "GetPositionTuple() -> (x,y)", GetPositionTuple); - // Find the logical position of the event given the DC - wxPoint GetLogicalPosition(const wxDC& dc) const; - - // Get X position - wxCoord GetX() const; + DocDeclStr( + wxPoint , GetLogicalPosition(const wxDC& dc) const, + "Returns the logical mouse position in pixels (i.e. translated +according to the translation set for the DC, which usually indicates +that the window has been scrolled).", ""); + - // Get Y position - wxCoord GetY() const; + DocDeclStr( + wxCoord , GetX() const, + "Returns X coordinate of the physical mouse event position.", ""); + + DocDeclStr( + wxCoord , GetY() const, + "Returns Y coordinate of the physical mouse event position.", ""); + - // Get wheel rotation, positive or negative indicates direction of - // rotation. Current devices all send an event when rotation is equal to - // +/-WheelDelta, but this allows for finer resolution devices to be - // created in the future. Because of this you shouldn't assume that one - // event is equal to 1 line or whatever, but you should be able to either - // do partial line scrolling or wait until +/-WheelDelta rotation values - // have been accumulated before scrolling. - int GetWheelRotation() const; + DocDeclStr( + int , GetWheelRotation() const, + "Get wheel rotation, positive or negative indicates direction of +rotation. Current devices all send an event when rotation is equal to ++/-WheelDelta, but this allows for finer resolution devices to be +created in the future. Because of this you shouldn't assume that one +event is equal to 1 line or whatever, but you should be able to either +do partial line scrolling or wait until +/-WheelDelta rotation values +have been accumulated before scrolling.", ""); + - // Get wheel delta, normally 120. This is the threshold for action to be - // taken, and one such action (for example, scrolling one increment) - // should occur for each delta. - int GetWheelDelta() const; + DocDeclStr( + int , GetWheelDelta() const, + "Get wheel delta, normally 120. This is the threshold for action to be +taken, and one such action (for example, scrolling one increment) +should occur for each delta.", ""); + - // Returns the configured number of lines (or whatever) to be scrolled per - // wheel action. Defaults to one. - int GetLinesPerAction() const; + DocDeclStr( + int , GetLinesPerAction() const, + "Returns the configured number of lines (or whatever) to be scrolled +per wheel action. Defaults to three.", ""); + - // Is the system set to do page scrolling? - bool IsPageScroll() const; + DocDeclStr( + bool , IsPageScroll() const, + "Returns true if the system has been setup to do page scrolling with +the mouse wheel instead of line scrolling.", ""); + public: wxCoord m_x, m_y; @@ -673,17 +1055,42 @@ public: %newgroup; // Cursor set event + +DocStr(wxSetCursorEvent, +"A SetCursorEvent is generated when the mouse cursor is about to be set +as a result of mouse motion. This event gives the application the +chance to perform specific mouse cursor processing based on the +current position of the mouse within the window. Use the `SetCursor` +method to specify the cursor you want to be displayed.", ""); + class wxSetCursorEvent : public wxEvent { public: - wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); + DocCtorStr( + wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0), + "Construct a new `wx.SetCursorEvent`.", ""); - wxCoord GetX() const; - wxCoord GetY() const; + DocDeclStr( + wxCoord , GetX() const, + "Returns the X coordinate of the mouse in client coordinates.", ""); + + DocDeclStr( + wxCoord , GetY() const, + "Returns the Y coordinate of the mouse in client coordinates.", ""); + - void SetCursor(const wxCursor& cursor); - const wxCursor& GetCursor() const; - bool HasCursor() const; + DocDeclStr( + void , SetCursor(const wxCursor& cursor), + "Sets the cursor associated with this event.", ""); + + DocDeclStr( + const wxCursor& , GetCursor() const, + "Returns a reference to the cursor specified by this event.", ""); + + DocDeclStr( + bool , HasCursor() const, + "Returns true if the cursor specified by this event is a valid cursor.", ""); + }; //--------------------------------------------------------------------------- @@ -691,22 +1098,141 @@ public: // Keyboard input event class +DocStr(wxKeyEvent, +"This event class contains information about keypress and character +events. These events are only sent to the widget that currently has +the keyboard focus. + +Notice that there are three different kinds of keyboard events in +wxWidgets: key down and up events and char events. The difference +between the first two is clear - the first corresponds to a key press +and the second to a key release - otherwise they are identical. Just +note that if the key is maintained in a pressed state you will +typically get a lot of (automatically generated) down events but only +one up so it is wrong to assume that there is one up event +corresponding to each down one. + +Both key events provide untranslated key codes while the char event +carries the translated one. The untranslated code for alphanumeric +keys is always an upper case value. For the other keys it is one of +WXK_XXX values from the keycodes table. The translated key is, in +general, the character the user expects to appear as the result of the +key combination when typing the text into a text entry zone, for +example. + +A few examples to clarify this (all assume that CAPS LOCK is unpressed +and the standard US keyboard): when the 'A' key is pressed, the key +down event key code is equal to ASCII A == 65. But the char event key +code is ASCII a == 97. On the other hand, if you press both SHIFT and +'A' keys simultaneously , the key code in key down event will still be +just 'A' while the char event key code parameter will now be 'A' as +well. + +Although in this simple case it is clear that the correct key code +could be found in the key down event handler by checking the value +returned by `ShiftDown`, in general you should use EVT_CHAR for this +as for non alphanumeric keys or non-US keyboard layouts the +translation is keyboard-layout dependent and can only be done properly +by the system itself. + +Another kind of translation is done when the control key is pressed: +for example, for CTRL-A key press the key down event still carries the +same key code 'A' as usual but the char event will have key code of 1, +the ASCII value of this key combination. + +You may discover how the other keys on your system behave +interactively by running the KeyEvents sample in the wxPython demo and +pressing some keys while the blue box at the top has the keyboard +focus. + +**Note**: If a key down event is caught and the event handler does not +call event.Skip() then the coresponding char event will not +happen. This is by design and enables the programs that handle both +types of events to be a bit simpler. + +**Note for Windows programmers**: The key and char events in wxWidgets +are similar to but slightly different from Windows WM_KEYDOWN and +WM_CHAR events. In particular, Alt-x combination will generate a char +event in wxWidgets (unless it is used as an accelerator). + +**Tip**: be sure to call event.Skip() for events that you don't +process in key event function, otherwise menu shortcuts may cease to +work under Windows. +", " + +Events +------ + ================== ============================================== + wx.EVT_KEY_DOWN Sent when a keyboard key has been pressed + wx.EVT_KEY_UP Sent when a keyboard key has been released + wx.EVT_CHAR Sent for translated character events. + ================== ============================================== + + +Keycode Table +------------- + =========== ============== ======== ==================== ================= + WXK_BACK WXK_EXECUTE WXK_F1 WXK_NUMPAD_SPACE WXK_WINDOWS_LEFT + WXK_TAB WXK_SNAPSHOT WXK_F2 WXK_NUMPAD_TAB WXK_WINDOWS_RIGHT + WXK_RETURN WXK_INSERT WXK_F3 WXK_NUMPAD_ENTER WXK_WINDOWS_MENU + WXK_ESCAPE WXK_HELP WXK_F4 WXK_NUMPAD_F1 WXK_SPECIAL1 + WXK_SPACE WXK_NUMPAD0 WXK_F5 WXK_NUMPAD_F2 WXK_SPECIAL2 + WXK_DELETE WXK_NUMPAD1 WXK_F6 WXK_NUMPAD_F3 WXK_SPECIAL3 + WXK_LBUTTON WXK_NUMPAD2 WXK_F7 WXK_NUMPAD_F4 WXK_SPECIAL4 + WXK_RBUTTON WXK_NUMPAD3 WXK_F8 WXK_NUMPAD_HOME WXK_SPECIAL5 + WXK_CANCEL WXK_NUMPAD4 WXK_F9 WXK_NUMPAD_LEFT WXK_SPECIAL6 + WXK_MBUTTON WXK_NUMPAD5 WXK_F10 WXK_NUMPAD_UP WXK_SPECIAL7 + WXK_CLEAR WXK_NUMPAD6 WXK_F11 WXK_NUMPAD_RIGHT WXK_SPECIAL8 + WXK_SHIFT WXK_NUMPAD7 WXK_F12 WXK_NUMPAD_DOWN WXK_SPECIAL9 + WXK_ALT WXK_NUMPAD8 WXK_F13 WXK_NUMPAD_PRIOR WXK_SPECIAL10 + WXK_CONTROL WXK_NUMPAD9 WXK_F14 WXK_NUMPAD_PAGEUP WXK_SPECIAL11 + WXK_MENU WXK_MULTIPLY WXK_F15 WXK_NUMPAD_NEXT WXK_SPECIAL12 + WXK_PAUSE WXK_ADD WXK_F16 WXK_NUMPAD_PAGEDOWN WXK_SPECIAL13 + WXK_CAPITAL WXK_SEPARATOR WXK_F17 WXK_NUMPAD_END WXK_SPECIAL14 + WXK_PRIOR WXK_SUBTRACT WXK_F18 WXK_NUMPAD_BEGIN WXK_SPECIAL15 + WXK_NEXT WXK_DECIMAL WXK_F19 WXK_NUMPAD_INSERT WXK_SPECIAL16 + WXK_END WXK_DIVIDE WXK_F20 WXK_NUMPAD_DELETE WXK_SPECIAL17 + WXK_HOME WXK_NUMLOCK WXK_F21 WXK_NUMPAD_EQUAL WXK_SPECIAL18 + WXK_LEFT WXK_SCROLL WXK_F22 WXK_NUMPAD_MULTIPLY WXK_SPECIAL19 + WXK_UP WXK_PAGEUP WXK_F23 WXK_NUMPAD_ADD WXK_SPECIAL20 + WXK_RIGHT WXK_PAGEDOWN WXK_F24 WXK_NUMPAD_SEPARATOR + WXK_DOWN WXK_NUMPAD_SUBTRACT + WXK_SELECT WXK_NUMPAD_DECIMAL + WXK_PRINT WXK_NUMPAD_DIVIDE + =========== ============== ======== ==================== ================= +"); + class wxKeyEvent : public wxEvent { public: - wxKeyEvent(wxEventType keyType = wxEVT_NULL); + DocCtorStr( + wxKeyEvent(wxEventType eventType = wxEVT_NULL), + "Construct a new `wx.KeyEvent`. Valid event types are: + * ", ""); + - // Find state of shift/control keys - bool ControlDown() const; - bool MetaDown() const; - bool AltDown() const; - bool ShiftDown() const; + DocDeclStr( + bool , ControlDown() const, + "Returns ``True`` if the Control key was down at the time of the event.", ""); + + DocDeclStr( + bool , MetaDown() const, + "Returns ``True`` if the Meta key was down at the time of the event.", ""); + + DocDeclStr( + bool , AltDown() const, + "Returns ``True`` if the Alt key was down at the time of the event.", ""); + + DocDeclStr( + bool , ShiftDown() const, + "Returns ``True`` if the Shift key was down at the time of the event.", ""); + DocDeclStr( bool , CmdDown() const, "\"Cmd\" is a pseudo key which is the same as Control for PC and Unix platforms but the special \"Apple\" (a.k.a as \"Command\") key on -Macs: it makes often sense to use it instead of, say, `ControlDown` +Macs. It makes often sense to use it instead of, say, `ControlDown` because Cmd key is used for the same thing under Mac as Ctrl elsewhere. The Ctrl still exists, it's just not used for this purpose. So for non-Mac platforms this is the same as `ControlDown` @@ -714,16 +1240,35 @@ and Macs this is the same as `MetaDown`.", ""); - // exclude MetaDown() from HasModifiers() because NumLock under X is often - // configured as mod2 modifier, yet the key events even when it is pressed - // should be processed normally, not like Ctrl- or Alt-key - bool HasModifiers() const; + DocDeclStr( + bool , HasModifiers() const, + "Returns true if either CTRL or ALT keys was down at the time of the +key event. Note that this function does not take into account neither +SHIFT nor META key states (the reason for ignoring the latter is that +it is common for NUMLOCK key to be configured as META under X but the +key presses even while NUMLOCK is on should be still processed +normally).", ""); + - // get the key code: an ASCII7 char or an element of wxKeyCode enum - int GetKeyCode() const; + DocDeclStr( + int , GetKeyCode() const, + "Returns the virtual key code. ASCII events return normal ASCII values, +while non-ASCII events return values such as WXK_LEFT for the left +cursor key. See `wx.KeyEvent` for a full list of the virtual key +codes. + +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`.", ""); %pythoncode { KeyCode = GetKeyCode } + %extend { + DocStr( + GetUnicodeKey, + "Returns the Unicode character corresponding to this key event. This +function is only meaningfule in a Unicode build of wxPython.", ""); int GetUnicodeKey() { %#if wxUSE_UNICODE return self->GetUnicodeKey(); @@ -735,15 +1280,24 @@ and Macs this is the same as `MetaDown`.", ""); %pythoncode { GetUniChar = GetUnicodeKey } - // get the raw key code (platform-dependent) - wxUint32 GetRawKeyCode() const; + DocDeclStr( + wxUint32 , GetRawKeyCode() const, + "Returns the raw key code for this event. This is a platform-dependent +scan code which should only be used in advanced +applications. Currently the raw key codes are not supported by all +ports.", ""); + - // get the raw key flags (platform-dependent) - wxUint32 GetRawKeyFlags() const; + DocDeclStr( + wxUint32 , GetRawKeyFlags() const, + "Returns the low level key flags for this event. The flags are +platform-dependent and should only be used in advanced applications. +Currently the raw key flags are not supported by all ports.", ""); + DocStr(GetPosition, // sets the docstring for both - "Find the position of the event.", ""); + "Find the position of the event, if applicable.", ""); wxPoint GetPosition(); DocDeclAName( @@ -751,11 +1305,18 @@ and Macs this is the same as `MetaDown`.", ""); "GetPositionTuple() -> (x,y)", GetPositionTuple); - // Get X position - wxCoord GetX() const; + + DocDeclStr( + wxCoord , GetX() const, + "Returns the X position (in client coordinates) of the event, if +applicable.", ""); + - // Get Y position - wxCoord GetY() const; + DocDeclStr( + wxCoord , GetY() const, + "Returns the Y position (in client coordinates) of the event, if +applicable.", ""); + public: wxCoord m_x, m_y; @@ -768,8 +1329,6 @@ public: bool m_metaDown; bool m_scanCode; - // these fields contain the platform-specific information about - // key that was pressed wxUint32 m_rawCode; wxUint32 m_rawFlags; }; @@ -778,14 +1337,39 @@ public: %newgroup; // Size event class + +DocStr(wxSizeEvent, +"A size event holds information about size change events. The EVT_SIZE +handler function will be called when the window it is bound to has +been resized. + +Note that the size passed is of the whole window: call +`wx.Window.GetClientSize` for the area which may be used by the +application. + +When a window is resized, usually only a small part of the window is +damaged and and that area is all that is in the update region for the +next paint event. However, if your drawing depends on the size of the +window, you may need to clear the DC explicitly and repaint the whole +window. In which case, you may need to call `wx.Window.Refresh` to +invalidate the entire window. +", ""); + class wxSizeEvent : public wxEvent { public: - wxSizeEvent(const wxSize& sz=wxDefaultSize, int winid = 0); + DocCtorStr( + wxSizeEvent(const wxSize& sz=wxDefaultSize, int winid = 0), + "Construct a new ``wx.SizeEvent``.", ""); - wxSize GetSize() const; + DocDeclStr( + wxSize , GetSize() const, + "Returns the entire size of the window generating the size change +event.", ""); + wxRect GetRect() const; void SetRect(wxRect rect); + %extend { void SetSize(wxSize size) { self->m_size = size; @@ -794,20 +1378,28 @@ public: public: wxSize m_size; - wxRect m_rect; // Used for wxEVT_SIZING + wxRect m_rect; }; //--------------------------------------------------------------------------- %newgroup; -// Move event class +DocStr(wxMoveEvent, +"This event object is sent for EVT_MOVE event bindings when a window is +moved to a new position.", ""); + class wxMoveEvent : public wxEvent { public: - wxMoveEvent(const wxPoint& pos=wxDefaultPosition, int winid = 0); + DocCtorStr( + wxMoveEvent(const wxPoint& pos=wxDefaultPosition, int winid = 0), + "Constructor.", ""); - wxPoint GetPosition() const; + DocDeclStr( + wxPoint , GetPosition() const, + "Returns the position of the window generating the move change event.", ""); + wxRect GetRect() const; void SetRect(const wxRect& rect); void SetPosition(const wxPoint& pos); @@ -821,11 +1413,27 @@ public: //--------------------------------------------------------------------------- %newgroup; -// Paint event class +DocStr(wxPaintEvent, +"A paint event is sent when a window's contents needs to be repainted. +Note that in an EVT_PAINT handler the application must *always* create +a `wx.PaintDC` object, even if you do not use it. Otherwise MS +Windows assumes that the window has not been painted yet and will send +the event again, causing endless refreshes. + +You can optimize painting by retrieving the rectangles that have been +damaged using `wx.Window.GetUpdateRegion` and/or `wx.RegionIterator`, +and only repainting these rectangles. The rectangles are in terms of +the client area, and are unscrolled, so you will need to do some +calculations using the current view position to obtain logical, +scrolled units. +", ""); + class wxPaintEvent : public wxEvent { public: - wxPaintEvent(int Id = 0); + DocCtorStr( + wxPaintEvent(int Id = 0), + "", ""); }; @@ -838,105 +1446,296 @@ public: //--------------------------------------------------------------------------- %newgroup; +DocStr(wxEraseEvent, +"An erase event is sent whenever the background of a window needs to be +repainted. To intercept this event use the EVT_ERASE_BACKGROUND event +binder. On some platforms, such as GTK+, this event is simulated +(simply generated just before the paint event) and may cause flicker. + +To paint a custom background use the `GetDC` method and use the returned +device context if it is not ``None``, otherwise create a temporary +`wx.ClientDC` and draw on that. +", ""); + class wxEraseEvent : public wxEvent { public: - wxEraseEvent(int Id = 0, wxDC *dc = (wxDC *) NULL); + DocCtorStr( + wxEraseEvent(int Id = 0, wxDC *dc = NULL), + "Constructor", ""); - wxDC *GetDC() const; + DocDeclStr( + wxDC *, GetDC() const, + "Returns the device context the event handler should draw upon. If +``None`` is returned then create a temporary `wx.ClientDC` and use +that instead.", ""); }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxFocusEvent, +"A focus event is sent when a window's focus changes. The window losing +focus receives an EVT_KILL_FOCUS event while the window gaining it +gets an EVT_SET_FOCUS event. + +Notice that the set focus event happens both when the user gives focus +to the window (whether using the mouse or keyboard) and when it is +done from the program itself using `wx.Window.SetFocus`. +", ""); + class wxFocusEvent : public wxEvent { public: - wxFocusEvent(wxEventType type = wxEVT_NULL, int winid = 0); + DocCtorStr( + wxFocusEvent(wxEventType type = wxEVT_NULL, int winid = 0), + "Constructor", ""); - // The window associated with this event is the window which had focus - // before for SET event and the window which will have focus for the KILL - // one. NB: it may be NULL in both cases! - wxWindow *GetWindow() const; + DocDeclStr( + wxWindow *, GetWindow() const, + "Returns the other window associated with this event, that is the +window which had the focus before for the EVT_SET_FOCUS event and the +window which is going to receive focus for the wxEVT_KILL_FOCUS event. + +Warning: the window returned may be None!", ""); + void SetWindow(wxWindow *win); }; //--------------------------------------------------------------------------- %newgroup; -// wxChildFocusEvent notifies the parent that a child has got the focus: unlike -// wxFocusEvent it is propagated upwards the window chain +DocStr(wxChildFocusEvent, +"wx.ChildFocusEvent notifies the parent that a child has received the +focus. Unlike `wx.FocusEvent` it is propagated up the window +heirarchy.", ""); + + class wxChildFocusEvent : public wxCommandEvent { public: - wxChildFocusEvent(wxWindow *win = NULL); + DocCtorStr( + wxChildFocusEvent(wxWindow *win = NULL), + "Constructor", ""); - wxWindow *GetWindow() const; + DocDeclStr( + wxWindow *, GetWindow() const, + "The window which has just received the focus.", ""); + }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxActivateEvent, +"An activate event is sent when a top-level window or the entire +application is being activated or deactivated. + +A top-level window (a dialog or frame) receives an activate event when +is being activated or deactivated. This is indicated visually by the +title bar changing colour, and a subwindow gaining the keyboard focus. +An application is activated or deactivated when one of its frames +becomes activated, or a frame becomes inactivate resulting in all +application frames being inactive. + +Please note that usually you should call event.Skip() in your handlers +for these events so the default handlers will still be called, as not +doing so can result in strange effects. +", " + +Events +------- + ======================= ========================================== + wx.EVT_ACTIVATE Sent to a frame when it has been activated + or deactivated. + wx.EVT_ACTIVATE_APP Sent to the app object when its activation + state changes. + ======================= ========================================== +"); + + class wxActivateEvent : public wxEvent { public: - wxActivateEvent(wxEventType type = wxEVT_NULL, bool active = true, int Id = 0); - bool GetActive() const; + DocCtorStr( + wxActivateEvent(wxEventType type = wxEVT_NULL, bool active = true, int Id = 0), + "Constructor", ""); + + DocDeclStr( + bool , GetActive() const, + "Returns true if the application or window is being activated, false +otherwise.", ""); + }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxInitDialogEvent, +"A wx.InitDialogEvent is sent as a dialog is being initialised, or for +any window when `wx.Window.InitDialog` is called. Handlers for this +event can transfer data to the window, or anything else that should be +done before the user begins editing the form. The default handler +calls `wx.Window.TransferDataToWindow`.", " + +Events +------- + ======================= ========================================== + wx.EVT_INIT_DIALOG Binder for init dialog events. + ======================= ========================================== +"); + class wxInitDialogEvent : public wxEvent { public: - wxInitDialogEvent(int Id = 0); + DocCtorStr( + wxInitDialogEvent(int Id = 0), + "Constructor", ""); }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxMenuEvent, +"This class is used for a variety of menu-related events. Note that +these do not include menu command events, which are handled by sending +`wx.CommandEvent` objects. + +The default handler for wx.EVT_MENU_HIGHLIGHT displays menu item help +text in the first field of the status bar.", " + +Events +------- + ========================= ========================================== + wx.EVT_MENU_OPEN A menu is about to be opened. On Windows, + this is only sent once for each navigation + of the menubar (up until all menus have closed). + wx.EVT_MENU_CLOSE A menu has been just closed. + wx.EVT_MENU_HIGHLIGHT Sent when the menu item with the specified id + has been highlighted: used by default to show + help prompts in the `wx.Frame`'s status bar. + wx.EVT_MENU_HIGHLIGHT_ALL Can be used to catch the menu highlight + event for all menu items. + ========================= ========================================== +"); + class wxMenuEvent : public wxEvent { public: - wxMenuEvent(wxEventType type = wxEVT_NULL, int winid = 0, wxMenu* menu = NULL); + DocCtorStr( + wxMenuEvent(wxEventType type = wxEVT_NULL, int winid = 0, wxMenu* menu = NULL), + "Constructor", ""); + + DocDeclStr( + int , GetMenuId() const, + "Returns the menu identifier associated with the event. This method +should be only used with the HIGHLIGHT events.", ""); - // only for wxEVT_MENU_HIGHLIGHT - int GetMenuId() const; - // only for wxEVT_MENU_OPEN/CLOSE - bool IsPopup() const; + DocDeclStr( + bool , IsPopup() const, + "Returns ``True`` if the menu which is being opened or closed is a +popup menu, ``False`` if it is a normal one. This method should only +be used with the OPEN and CLOSE events.", ""); + - // only for wxEVT_MENU_OPEN/CLOSE - wxMenu* GetMenu() const; + DocDeclStr( + wxMenu* , GetMenu() const, + "Returns the menu which is being opened or closed. This method should +only be used with the OPEN and CLOSE events.", ""); + }; //--------------------------------------------------------------------------- %newgroup; -// Window close or session close event class +DocStr(wxCloseEvent, +"This event class contains information about window and session close +events. + +The handler function for EVT_CLOSE is called when the user has tried +to close a a frame or dialog box using the window manager controls or +the system menu. It can also be invoked by the application itself +programmatically, for example by calling the `wx.Window.Close` +function. + +You should check whether the application is forcing the deletion of +the window using `CanVeto`. If it returns ``False``, you must destroy +the window using `wx.Window.Destroy`. If the return value is ``True``, +it is up to you whether you respond by destroying the window or not. +For example you may wish to display a message dialog prompting to save +files or to cancel the close. + +If you don't destroy the window, you should call `Veto` to let the +calling code know that you did not destroy the window. This allows the +`wx.Window.Close` function to return ``True`` or ``False`` depending +on whether the close instruction was honored or not.", " + +Events +------- + ========================= ========================================== + wx.EVT_CLOSE This event is sent to a top-level window + when it has been requested to close either + from the user or programatically. + wx.EVT_QUERY_END_SESSION This event is sent to the `wx.App` when the + system is about to be logged off, giving the + app a chance to veto the shutdown. + wx.EVT_END_SESSION This event is sent to the `wx.App` when the + system is being logged off. + ========================= ========================================== +"); + class wxCloseEvent : public wxEvent { public: - wxCloseEvent(wxEventType type = wxEVT_NULL, int winid = 0); + DocCtorStr( + wxCloseEvent(wxEventType type = wxEVT_NULL, int winid = 0), + "Constructor.", ""); + + DocDeclStr( + void , SetLoggingOff(bool logOff), + "Sets the 'logging off' flag.", ""); - void SetLoggingOff(bool logOff); - bool GetLoggingOff() const; + DocDeclStr( + bool , GetLoggingOff() const, + "Returns ``True`` if the user is logging off or ``False`` if the +system is shutting down. This method can only be called for end +session and query end session events, it doesn't make sense for close +window event.", ""); + + + DocDeclStr( + void , Veto(bool veto = true), + "Call this from your event handler to veto a system shutdown or to +signal to the calling application that a window close did not happen. - void Veto(bool veto = true); - void SetCanVeto(bool canVeto); +You can only veto a shutdown or close if `CanVeto` returns true.", ""); - bool CanVeto() const; bool GetVeto() const; + + DocDeclStr( + void , SetCanVeto(bool canVeto), + "Sets the 'can veto' flag.", ""); + + DocDeclStr( + bool , CanVeto() const, + "Returns true if you can veto a system shutdown or a window close +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.", ""); + }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxShowEvent, +"An EVT_SHOW event is sent when a window is shown or hidden.", ""); + class wxShowEvent : public wxEvent { public: @@ -951,17 +1750,29 @@ public: //--------------------------------------------------------------------------- %newgroup; +DocStr(wxIconizeEvent, +"An EVT_ICONIZE event is sent when a frame is iconized (minimized) or +restored.", ""); + class wxIconizeEvent: public wxEvent { public: wxIconizeEvent(int id = 0, bool iconized = true); - bool Iconized(); + + DocDeclStr( + bool , Iconized(), + "Returns ``True`` if the frame has been iconized, ``False`` if it has +been restored.", ""); + }; //--------------------------------------------------------------------------- %newgroup; +DocStr(wxMaximizeEvent, +"An EVT_MAXIMIZE event is sent when a frame is maximized or restored.", ""); + class wxMaximizeEvent: public wxEvent { public: @@ -971,26 +1782,58 @@ public: //--------------------------------------------------------------------------- %newgroup; +DocStr(wxDropFilesEvent, +"This class is used for drop files events, that is, when files have +been dropped onto the window. This functionality is only available +under Windows. The window must have previously been enabled for +dropping by calling `wx.Window.DragAcceptFiles`. + +Important note: this is a separate implementation to the more general +drag and drop implementation using `wx.FileDropTarget`, and etc. This +implementation uses the older, Windows message-based approach of +dropping files. + +Use wx.EVT_DROP_FILES to bind an event handler to receive file drop +events. +", ""); + class wxDropFilesEvent: public wxEvent { public: - wxPoint GetPosition(); - int GetNumberOfFiles(); + + // TODO: wrap the ctor! + + + DocDeclStr( + wxPoint , GetPosition(), + "Returns the position at which the files were dropped.", ""); + + DocDeclStr( + int , GetNumberOfFiles(), + "Returns the number of files dropped.", ""); + %extend { + DocStr( + GetFiles, + "Returns a list of the filenames that were dropped.", ""); + PyObject* GetFiles() { int count = self->GetNumberOfFiles(); wxString* files = self->GetFiles(); + wxPyBlock_t blocked = wxPyBeginBlockThreads(); PyObject* list = PyList_New(count); if (!list) { PyErr_SetString(PyExc_MemoryError, "Can't allocate list of files!"); + wxPyEndBlockThreads(blocked); return NULL; } for (int i=0; i