The normal order of event table searching is as follows:
-# wxApp::FilterEvent() is called. If it returns anything but @c -1
(default) the processing stops here.
- -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
- the function skips to step (7).
-# TryBefore() is called (this is where wxValidator are taken into
account for wxWindow objects). If this returns @true, the function exits.
- -# Dynamic event table of the handlers binded using Bind<>() is
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (7).
+ -# Dynamic event table of the handlers bound using Bind<>() is
searched. If a handler is found, it is executed and the function
returns @true unless the handler used wxEvent::Skip() to indicate
that it didn't handle the event in which case the search continues.
- -# Static events table of the handlers binded using event table
+ -# Static events table of the handlers bound using event table
macros is searched for this event handler. If this fails, the base
class event table table is tried, and so on until no more tables
exist or an appropriate function was found. If a handler is found,
processed, ProcessEvent() on wxTheApp object is called as the last
step.
- Notice that steps (2)-(6) are performed in ProcessEventHere() which is
- called by this function.
+ Notice that steps (2)-(6) are performed in ProcessEventLocally()
+ which is called by this function.
@param event
Event to process.
virtual bool ProcessEvent(wxEvent& event);
/**
- Try to process the event in this event handler.
+ Try to process the event in this handler and all those chained to it.
+
+ As explained in ProcessEvent() documentation, the event handlers may be
+ chained in a doubly-linked list. This function tries to process the
+ event in this handler (including performing any pre-processing done in
+ TryBefore(), e.g. applying validators) and all those following it in
+ the chain until the event is processed or the chain is exhausted.
- This method is called from ProcessEvent(), please see the detailed
- description of the event processing logic there.
+ This function is called from ProcessEvent() and, in turn, calls
+ TryThis() for each handler in turn. It is not virtual and so cannot be
+ overridden but can, and should, be called to forward an event to
+ another handler instead of ProcessEvent() which would result in a
+ duplicate call to TryAfter(), e.g. resulting in all unprocessed events
+ being sent to the application object multiple times.
- It is @em not virtual and so may not be overridden but it does call
- virtual TryBefore() which may be overridden.
+ @since 2.9.1
@param event
Event to process.
@return
- @true if this object itself defines a handler for this event and
- the handler didn't skip the event.
+ @true if this handler of one of those chained to it processed the
+ event.
*/
- bool ProcessEventHere(wxEvent& event);
+ bool ProcessEventLocally(wxEvent& event);
/**
Processes an event by calling ProcessEvent() and handles any exceptions
when connecting an event generated by one object to a member
function of a different object. If it is omitted, @c this is used.
+ @beginWxPerlOnly
+ In wxPerl this function takes 4 arguments: @a id, @a lastid,
+ @a type, @a method; if @a method is undef, the handler is
+ disconnected.}
+ @endWxPerlOnly
+
@see Bind<>()
*/
void Connect(int id, int lastId, wxEventType eventType,
wxEVT_COMMAND_MENU_SELECTED,
wxCommandEventHandler(MyFrame::OnQuit) );
@endcode
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
void Connect(int id, wxEventType eventType,
wxObjectEventFunction function,
This overload will connect the given event handler so that regardless of the
ID of the event source, the handler will be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
void Connect(wxEventType eventType,
wxObjectEventFunction function,
Data associated with the event table entry.
@param eventSink
Object whose member function should be called.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Disconnect(wxEventType eventType,
wxObjectEventFunction function,
overload for more info.
This overload takes the additional @a id parameter.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
bool Disconnect(int id = wxID_ANY,
wxEventType eventType = wxEVT_NULL,
overload for more info.
This overload takes an additional range of source IDs.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 3 arguments: @a id,
+ @a lastid, @a type.
+ @endWxPerlOnly
*/
bool Disconnect(int id, int lastId,
wxEventType eventType,
@param userData
Data to be associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Functor>
@param userData
Data to be associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
This method can only unbind functions, functors or methods which have
been added using the Bind<>() method. There is no way to unbind
- functions binded using the (static) event tables.
+ functions bound using the (static) event tables.
@param eventType
The event type associated with this event handler.
@param userData
Data associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Functor>
@param userData
Data associated with the event table entry.
+ @see @ref overview_cpp_rtti_disabled
+
@since 2.9.0
*/
template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
};
@endcode
- @see ProcessEvent(), ProcessEventHere()
+ @see ProcessEvent()
*/
virtual bool TryBefore(wxEvent& event);
+ /**
+ Try to process the event in this event handler.
+
+ This method is called from ProcessEventLocally() and thus, indirectly,
+ from ProcessEvent(), please see the detailed description of the event
+ processing logic there.
+
+ It is currently @em not virtual and so may not be overridden.
+
+ @since 2.9.1
+
+ @param event
+ Event to process.
+ @return
+ @true if this object itself defines a handler for this event and
+ the handler didn't skip the event.
+ */
+ bool TryThis(wxEvent& event);
+
/**
Method called by ProcessEvent() as last resort.
};
@endcode
- @see ProcessEvent(), ProcessEventHere()
+ @see ProcessEvent()
*/
virtual bool TryAfter(wxEvent& event);
};
+/**
+ Flags for categories of keys.
+
+ These values are used by wxKeyEvent::IsKeyInCategory(). They may be
+ combined via the bitwise operators |, &, and ~.
+
+ @since 2.9.1
+*/
+enum wxKeyCategoryFlags
+{
+ /// arrow keys, on and off numeric keypads
+ WXK_CATEGORY_ARROW,
+
+ /// page up and page down keys, on and off numeric keypads
+ WXK_CATEGORY_PAGING,
+
+ /// home and end keys, on and off numeric keypads
+ WXK_CATEGORY_JUMP,
+
+ /// tab key, on and off numeric keypads
+ WXK_CATEGORY_TAB,
+
+ /// backspace and delete keys, on and off numeric keypads
+ WXK_CATEGORY_CUT,
+
+ /// union of WXK_CATEGORY_ARROW, WXK_CATEGORY_PAGING, and WXK_CATEGORY_JUMP categories
+ WXK_CATEGORY_NAVIGATION
+};
+
+
/**
@class wxKeyEvent
*/
int GetKeyCode() const;
+ /**
+ Returns true if the key is in the given key category.
+
+ @param category
+ A bitwise combination of named ::wxKeyCategoryFlags constants.
+
+ @since 2.9.1
+ */
+ bool IsKeyInCategory(int category) const;
+
//@{
/**
Obtains the position (in client coordinates) at which the key was pressed.
A paint event is sent when a window's contents needs to be repainted.
- Please notice that in general it is impossible to change the drawing of a
- standard control (such as wxButton) and so you shouldn't attempt to handle
- paint events for them as even if it might work on some platforms, this is
- inherently not portable and won't work everywhere.
-
- @remarks
- Note that in a paint event handler, the application must always create a
- wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
- refreshing for this and other windows will go wrong.
- For example:
+ The handler of this event must create a wxPaintDC object and use it for
+ painting the window contents. For example:
@code
void MyWindow::OnPaint(wxPaintEvent& event)
{
DrawMyDocument(dc);
}
@endcode
+
+ Notice that you must @e not create other kinds of wxDC (e.g. wxClientDC or
+ wxWindowDC) in EVT_PAINT handlers and also don't create wxPaintDC outside
+ of this event handlers.
+
+
You can optimize painting by retrieving the rectangles that have been damaged
and only repainting these. The rectangles are in terms of the client area,
and are unscrolled, so you will need to do some calculations using the current
}
@endcode
+ @remarks
+ Please notice that in general it is impossible to change the drawing of a
+ standard control (such as wxButton) and so you shouldn't attempt to handle
+ paint events for them as even if it might work on some platforms, this is
+ inherently not portable and won't work everywhere.
+
@beginEventTable{wxPaintEvent}
@event{EVT_PAINT(func)}
left the window and the state variables for it may have changed during this time.
@note Note the difference between methods like wxMouseEvent::LeftDown and
- wxMouseEvent::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 wxMouseEvent::LeftIsDown to test whether the left mouse
- button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
- returns @true, wxMouseEvent::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.
+ the inherited wxMouseState::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
+ wxMouseEvent::LeftIsDown to test whether the left mouse button is
+ (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
+ returns @true, wxMouseEvent::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.
@beginEventTable{wxMouseEvent}
*/
bool Aux1Down() const;
- /**
- Returns @true if the first extra button mouse button is currently down,
- independent of the current event type.
- */
- bool Aux1IsDown() const;
-
/**
Returns @true if the first extra button mouse button changed to up.
*/
*/
bool Aux2Down() const;
- /**
- Returns @true if the second extra button mouse button is currently down,
- independent of the current event type.
- */
- bool Aux2IsDown() const;
-
/**
Returns @true if the second extra button mouse button changed to up.
*/
bool Aux2Up() const;
/**
- Returns @true if the identified mouse button is changing state.
- Valid values of @a button are:
+ Returns @true if the event was generated by the specified button.
- @li @c wxMOUSE_BTN_LEFT: check if left button was pressed
- @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed
- @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed
- @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed
- @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed
- @li @c wxMOUSE_BTN_ANY: check if any button was pressed
-
- @todo introduce wxMouseButton enum
+ @see wxMouseState::ButtoinIsDown()
*/
- bool Button(int button) const;
+ bool Button(wxMouseButton but) const;
/**
If the argument is omitted, this returns @true if the event was a mouse
double click event. Otherwise the argument specifies which double click event
was generated (see Button() for the possible values).
*/
- bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const;
+ bool ButtonDClick(wxMouseButton but = wxMOUSE_BTN_ANY) const;
/**
If the argument is omitted, this returns @true if the event was a mouse
button down event. Otherwise the argument specifies which button-down event
was generated (see Button() for the possible values).
*/
- bool ButtonDown(int = wxMOUSE_BTN_ANY) const;
+ bool ButtonDown(wxMouseButton but = wxMOUSE_BTN_ANY) const;
/**
If the argument is omitted, this returns @true if the event was a mouse
button up event. Otherwise the argument specifies which button-up event
was generated (see Button() for the possible values).
*/
- bool ButtonUp(int = wxMOUSE_BTN_ANY) const;
+ bool ButtonUp(wxMouseButton but = wxMOUSE_BTN_ANY) const;
/**
Returns @true if this was a dragging event (motion while a button is depressed).
*/
wxPoint GetLogicalPosition(const wxDC& dc) const;
- //@{
- /**
- Sets *x and *y to the position at which the event occurred.
- Returns the physical mouse position in pixels.
-
- Note that if the mouse event has been artificially generated from a special
- keyboard combination (e.g. under Windows when the "menu" key is pressed), the
- returned position is ::wxDefaultPosition.
- */
- wxPoint GetPosition() const;
- void GetPosition(wxCoord* x, wxCoord* y) const;
- void GetPosition(long* x, long* y) const;
- //@}
-
/**
Get wheel delta, normally 120.
*/
int GetWheelAxis() const;
- /**
- Returns X coordinate of the physical mouse event position.
- */
- wxCoord GetX() const;
-
- /**
- Returns Y coordinate of the physical mouse event position.
- */
- wxCoord GetY() const;
-
/**
Returns @true if the event was a mouse button event (not necessarily a button
down event - that may be tested using ButtonDown()).
*/
bool LeftDown() const;
- /**
- Returns @true if the left mouse button is currently down, independent
- of the current event type.
-
- Please notice that it is not the same as LeftDown() which returns @true if the
- event was generated by the left mouse button being pressed. Rather, it simply
- describes the state of the left mouse button at the time when the event was
- generated (so while it will be @true for a left click event, it can also be @true
- for a right click if it happened while the left mouse button was pressed).
-
- 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.
- */
- bool LeftIsDown() const;
-
/**
Returns @true if the left mouse button changed to up.
*/
*/
bool MiddleDown() const;
- /**
- Returns @true if the middle mouse button is currently down, independent
- of the current event type.
- */
- bool MiddleIsDown() const;
-
/**
Returns @true if the middle mouse button changed to up.
*/
*/
bool RightDown() const;
- /**
- Returns @true if the right mouse button is currently down, independent
- of the current event type.
- */
- bool RightIsDown() const;
-
/**
Returns @true if the right mouse button changed to up.
*/
@event{EVT_TOOL_RANGE(id1, id2, func)}
Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
@event{EVT_TOOL_RCLICKED(id, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.)
@event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
+ Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.)
@event{EVT_TOOL_ENTER(id, func)}
Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
- has moved off a tool.
+ has moved off a tool. (Not available on wxOSX.)
@event{EVT_COMMAND_LEFT_CLICK(id, func)}
Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
@event{EVT_COMMAND_LEFT_DCLICK(id, func)}
when calling wxEventLoopBase::YieldFor().
*/
virtual wxEventCategory GetEventCategory() const;
+
+ /**
+ Sets custom data payload.
+
+ The @a payload argument may be of any type that wxAny can handle
+ (i.e. pretty much anything). Note that T's copy constructor must be
+ thread-safe, i.e. create a copy that doesn't share anything with
+ the original (see Clone()).
+
+ @note This method is not available with Visual C++ 6.
+
+ @since 2.9.1
+
+ @see GetPayload(), wxAny
+ */
+ template<typename T>
+ void SetPayload(const T& payload);
+
+ /**
+ Get custom data payload.
+
+ Correct type is checked in debug builds.
+
+ @note This method is not available with Visual C++ 6.
+
+ @since 2.9.1
+
+ @see SetPayload(), wxAny
+ */
+ template<typename T>
+ T GetPayload() const;
};
@beginEventTable{wxCloseEvent}
@event{EVT_CLOSE(func)}
- Process a close event, supplying the member function.
+ Process a @c wxEVT_CLOSE_WINDOW command event, supplying the member function.
This event applies to wxFrame and wxDialog classes.
@event{EVT_QUERY_END_SESSION(func)}
- Process a query end session event, supplying the member function.
+ Process a @c wxEVT_QUERY_END_SESSION session event, supplying the member function.
This event can be handled in wxApp-derived class only.
@event{EVT_END_SESSION(func)}
- Process an end session event, supplying the member function.
+ Process a @c wxEVT_END_SESSION session event, supplying the member function.
This event can be handled in wxApp-derived class only.
@endEventTable
You may wish to use this for frames to resize their child windows as appropriate.
- Note that the size passed is of the whole window: call wxWindow::GetClientSize
+ Note that the size passed is of the whole window: call wxWindow::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
/**
Returns the entire size of the window generating the size change event.
+
+ This is the new total size of the window, i.e. the same size as would
+ be returned by wxWindow::GetSize() if it were called now. Use
+ wxWindow::GetClientSize() if you catch this event in a top level window
+ such as wxFrame to find the size available for the window contents.
*/
wxSize GetSize() const;
};
projects / wxWidgets.git / blobdiff