1998-05-20 10:25:30 -04:00
|
|
|
\section{Event handling overview}\label{eventhandlingoverview}
|
|
|
|
|
|
|
|
Classes: \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow}, \helpref{wxEvent}{wxevent}
|
|
|
|
|
|
|
|
\subsection{Introduction}
|
|
|
|
|
|
|
|
Before version 2.0 of wxWindows, events were handled by the application
|
|
|
|
either by supplying callback functions, or by overriding virtual member
|
|
|
|
functions such as {\bf OnSize}.
|
|
|
|
|
|
|
|
From wxWindows 2.0, {\it event tables} are used instead, with a few exceptions.
|
|
|
|
|
|
|
|
An event table is placed in an implementation file to tell wxWindows how to map
|
|
|
|
events to member functions. These member functions are not virtual functions, but
|
|
|
|
they all similar in form: they take a single wxEvent-derived argument, and have a void return
|
|
|
|
type.
|
|
|
|
|
|
|
|
Here's an example of an event table.
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
|
|
|
|
EVT_MENU (wxID_EXIT, MyFrame::OnExit)
|
|
|
|
EVT_MENU (DO_TEST, MyFrame::DoTest)
|
|
|
|
EVT_SIZE ( MyFrame::OnSize)
|
|
|
|
EVT_BUTTON (BUTTON1, MyFrame::OnButton1)
|
|
|
|
END_EVENT_TABLE()
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
The first two entries map menu commands to two different member functions. The EVT\_SIZE macro
|
|
|
|
doesn't need a window identifier, since normally you are only interested in the
|
|
|
|
current window's size events. (In fact you could intercept a particular window's size event
|
|
|
|
by using EVT\_CUSTOM(wxEVT\_SIZE, id, func).)
|
|
|
|
|
|
|
|
The EVT\_BUTTON macro demonstrates that the originating event does not have to come from
|
|
|
|
the window class implementing the event table - if the event source is a button within a panel within a frame, this will still
|
|
|
|
work, because event tables are searched up through the hierarchy of windows. In this
|
|
|
|
case, the button's event table will be searched, then the parent panel's, then the frame's.
|
|
|
|
|
|
|
|
As mentioned before, the member functions that handle events do not have to be virtual.
|
1999-01-26 08:10:06 -05:00
|
|
|
Indeed, the member functions should not be virtual as the event handler ignores that
|
|
|
|
the functions are virtual, i.e. overriding a virtual member function in a derived class
|
|
|
|
will not have any effect.
|
1998-05-20 10:25:30 -04:00
|
|
|
These member functions take an event argument, and the class of event differs according
|
|
|
|
to the type of event and the class of the originating window. For size
|
|
|
|
events, \helpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most control
|
|
|
|
commands (such as button presses), \helpref{wxCommandEvent}{wxcommandevent} is used.
|
|
|
|
When controls get more complicated, then specific event classes are used, such
|
|
|
|
as \helpref{wxTreeEvent}{wxtreeevent} for events from \helpref{wxTreeCtrl}{wxtreectrl} windows.
|
|
|
|
|
|
|
|
As well as the event table in the implementation file, there must be a DECLARE\_EVENT\_TABLE
|
|
|
|
macro in the class definition. For example:
|
|
|
|
|
|
|
|
{\small%
|
|
|
|
\begin{verbatim}
|
|
|
|
class MyFrame: public wxFrame {
|
|
|
|
|
|
|
|
DECLARE_DYNAMIC_CLASS(MyFrame)
|
|
|
|
|
|
|
|
public:
|
|
|
|
...
|
|
|
|
void OnExit(wxCommandEvent& event);
|
|
|
|
void OnSize(wxSizeEvent& event);
|
|
|
|
protected:
|
|
|
|
int m_count;
|
|
|
|
...
|
|
|
|
DECLARE_EVENT_TABLE()
|
|
|
|
};
|
|
|
|
\end{verbatim}
|
|
|
|
}%
|
|
|
|
|
|
|
|
\subsection{How events are processed}\label{eventprocessing}
|
|
|
|
|
|
|
|
When an event is received from the windowing system, wxWindows calls \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on
|
|
|
|
the first event handler object belonging to the window generating the event.
|
|
|
|
|
1999-01-26 08:10:06 -05:00
|
|
|
It may be noted that wxWindows' event processing system implements something
|
|
|
|
very close to virtual methods in normal C++, i.e. it is possible to alter
|
|
|
|
the behaviour of a class by overriding its event handling functions. In
|
|
|
|
many cases this works even for changing the behaviour of native controls.
|
1999-02-02 07:37:14 -05:00
|
|
|
For example it is possible to filter out a number of key events sent by the
|
1999-01-26 08:10:06 -05:00
|
|
|
system to a native text control by overriding wxTextCtrl and defining a
|
1999-02-02 07:37:14 -05:00
|
|
|
handler for key events using EVT\_KEY\_DOWN. This would indeed prevent
|
1999-01-26 08:10:06 -05:00
|
|
|
any key events from being sent to the native control - which might not be
|
|
|
|
what is desired. In this case the event handler function has to call Skip()
|
|
|
|
so as to indicate that it did NOT handle the event at all.
|
|
|
|
|
|
|
|
In practice, this would look like this if the derived text control only
|
|
|
|
accepts 'a' to 'z' and 'A' to 'Z':
|
|
|
|
|
|
|
|
{\small%
|
|
|
|
\begin{verbatim}
|
|
|
|
void MyTextCtrl::OnChar(wxKeyEvent& event)
|
|
|
|
{
|
|
|
|
if ( isalpha( event.KeyCode() ) )
|
|
|
|
{
|
|
|
|
// key code is within legal range. we call event.Skip() so the
|
|
|
|
// event can be processed either in the base wxWindows class
|
|
|
|
// or the native control.
|
|
|
|
|
|
|
|
event.Skip();
|
|
|
|
}
|
|
|
|
else
|
|
|
|
{
|
|
|
|
// illegal key hit. we don't call event.Skip() so the
|
|
|
|
// event is not processed anywhere else.
|
|
|
|
|
|
|
|
wxBell();
|
|
|
|
}
|
|
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
}%
|
|
|
|
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
The normal order of event table searching by ProcessEvent is as follows:
|
|
|
|
|
|
|
|
\begin{enumerate}\itemsep=0pt
|
|
|
|
\item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
|
|
|
|
the function skips to step (6).
|
|
|
|
\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
|
|
|
|
\helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
|
|
|
|
\item {\bf SearchEventTable} is called for this event handler. If this fails, the base
|
|
|
|
class table is tried, and so on until no more tables exist or an appropriate function was found,
|
|
|
|
in which case the function exits.
|
|
|
|
\item The search is applied down the entire chain of event handlers (usually the chain has a length
|
|
|
|
of one). If this succeeds, the function exits.
|
|
|
|
\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
|
|
|
|
recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
|
|
|
|
\item Finally, {\bf ProcessEvent} is called on the wxApp object.
|
|
|
|
\end{enumerate}
|
|
|
|
|
|
|
|
Note that your application may wish to override ProcessEvent to redirect processing of
|
|
|
|
events. This is done in the document/view framework, for example, to allow event handlers
|
|
|
|
to be defined in the document or view.
|
|
|
|
|
1999-01-26 08:10:06 -05:00
|
|
|
As mentioned above, only command events are recursively applied to the parents event
|
|
|
|
handler. As this quite often causes confusion for users, here is a list of system
|
|
|
|
events which will NOT get sent to the parent's event handler:
|
|
|
|
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
|
|
\twocolitem{\helpref{wxEvent}{wxevent}}{The event base class}
|
|
|
|
\twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event}
|
|
|
|
\twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event}
|
|
|
|
\twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event}
|
|
|
|
\twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{A window focus event}
|
|
|
|
\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{A keypress event}
|
|
|
|
\twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{An idle event}
|
|
|
|
\twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event}
|
|
|
|
\twocolitem{\helpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event}
|
|
|
|
\twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event}
|
|
|
|
\twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event}
|
|
|
|
\twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event}
|
|
|
|
\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event}
|
|
|
|
\twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information}
|
|
|
|
\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
|
|
|
|
\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
|
|
|
|
\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
|
|
|
|
\end{twocollist}
|
|
|
|
|
|
|
|
In some cases, it might be desired by the programmer to get a certain number
|
1999-02-02 07:37:14 -05:00
|
|
|
of system events in a parent window, for example all key events sent to, but not
|
1999-01-26 08:10:06 -05:00
|
|
|
used by, the native controls in a dialog. In this case, a special event handler
|
|
|
|
will have to be written that will override ProcessEvent() in order to pass
|
|
|
|
all events (or any selection of them) to the parent window. See next section.
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
\subsection{Pluggable event handlers}
|
|
|
|
|
|
|
|
In fact, you don't have to derive a new class from a window class
|
|
|
|
if you don't want to. You can derive a new class from wxEvtHandler instead,
|
|
|
|
defining the appropriate event table, and then call
|
|
|
|
\rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably,
|
|
|
|
\rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this
|
|
|
|
event handler the object that responds to events. This way, you can avoid
|
|
|
|
a lot of class derivation, and use the same event handler object to
|
|
|
|
handle events from instances of different classes. If you ever have to call a window's event handler
|
|
|
|
manually, use the GetEventHandler function to retrieve the window's event handler and use that
|
|
|
|
to call the member function. By default, GetEventHandler returns a pointer to the window itself
|
|
|
|
unless an application has redirected event handling using SetEventHandler or PushEventHandler.
|
|
|
|
|
|
|
|
One use of PushEventHandler is to temporarily or permanently change the
|
|
|
|
behaviour of the GUI. For example, you might want to invoke a dialog editor
|
|
|
|
in your application that changes aspects of dialog boxes. You can
|
|
|
|
grab all the input for an existing dialog box, and edit it `in situ',
|
|
|
|
before restoring its behaviour to normal. So even if the application
|
|
|
|
has derived new classes to customize behaviour, your utility can indulge
|
|
|
|
in a spot of body-snatching. It could be a useful technique for on-line
|
|
|
|
tutorials, too, where you take a user through a serious of steps and
|
|
|
|
don't want them to diverge from the lesson. Here, you can examine the events
|
|
|
|
coming from buttons and windows, and if acceptable, pass them through to
|
|
|
|
the original event handler. Use PushEventHandler/PopEventHandler
|
|
|
|
to form a chain of event handlers, where each handler processes a different
|
|
|
|
range of events independently from the other handlers.
|
|
|
|
|
1999-02-02 07:37:14 -05:00
|
|
|
\subsection{Window identifiers}\label{windowids}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-02-02 07:37:14 -05:00
|
|
|
\index{identifiers}\index{wxID}Window identifiers are integers, and are used to uniquely determine window identity in the
|
|
|
|
event system (though you can use it for other purposes). In fact, identifiers do not need
|
|
|
|
to be unique across your entire application just so long as they are unique within a particular context you're interested
|
|
|
|
in, such as a frame and its children. You may use the wxID\_OK identifier, for example, on
|
|
|
|
any number of dialogs so long as you don't have several within the same dialog.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-02-02 07:37:14 -05:00
|
|
|
If you pass -1 to a window constructor, an identifier will be generated for you, but beware:
|
|
|
|
if things don't respond in the way they should, it could be because of an id conflict. It's safer
|
|
|
|
to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict
|
|
|
|
with your own identifiers.
|
|
|
|
|
|
|
|
The following standard identifiers are supplied. You can use wxID\_HIGHEST to determine the
|
|
|
|
number above which it is safe to define your own identifiers. Or, you can use identifiers below
|
|
|
|
wxID\_LOWEST.
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
#define wxID_LOWEST 4999
|
|
|
|
|
|
|
|
#define wxID_OPEN 5000
|
|
|
|
#define wxID_CLOSE 5001
|
|
|
|
#define wxID_NEW 5002
|
|
|
|
#define wxID_SAVE 5003
|
|
|
|
#define wxID_SAVEAS 5004
|
|
|
|
#define wxID_REVERT 5005
|
|
|
|
#define wxID_EXIT 5006
|
|
|
|
#define wxID_UNDO 5007
|
|
|
|
#define wxID_REDO 5008
|
|
|
|
#define wxID_HELP 5009
|
|
|
|
#define wxID_PRINT 5010
|
|
|
|
#define wxID_PRINT_SETUP 5011
|
|
|
|
#define wxID_PREVIEW 5012
|
|
|
|
#define wxID_ABOUT 5013
|
|
|
|
#define wxID_HELP_CONTENTS 5014
|
|
|
|
#define wxID_HELP_COMMANDS 5015
|
|
|
|
#define wxID_HELP_PROCEDURES 5016
|
|
|
|
#define wxID_HELP_CONTEXT 5017
|
|
|
|
|
|
|
|
#define wxID_CUT 5030
|
|
|
|
#define wxID_COPY 5031
|
|
|
|
#define wxID_PASTE 5032
|
|
|
|
#define wxID_CLEAR 5033
|
|
|
|
#define wxID_FIND 5034
|
|
|
|
#define wxID_DUPLICATE 5035
|
|
|
|
#define wxID_SELECTALL 5036
|
|
|
|
|
|
|
|
#define wxID_FILE1 5050
|
|
|
|
#define wxID_FILE2 5051
|
|
|
|
#define wxID_FILE3 5052
|
|
|
|
#define wxID_FILE4 5053
|
|
|
|
#define wxID_FILE5 5054
|
|
|
|
#define wxID_FILE6 5055
|
|
|
|
#define wxID_FILE7 5056
|
|
|
|
#define wxID_FILE8 5057
|
|
|
|
#define wxID_FILE9 5058
|
|
|
|
|
|
|
|
#define wxID_OK 5100
|
|
|
|
#define wxID_CANCEL 5101
|
|
|
|
#define wxID_APPLY 5102
|
|
|
|
#define wxID_YES 5103
|
|
|
|
#define wxID_NO 5104
|
|
|
|
#define wxID_STATIC 5105
|
|
|
|
|
|
|
|
#define wxID_HIGHEST 5999
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\subsection{Event macros summary}\label{eventmacros}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\wxheading{Generic event table macros}
|
|
|
|
|
|
|
|
\twocolwidtha{8cm}%
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
1999-02-02 07:37:14 -05:00
|
|
|
\twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table
|
1998-05-20 10:25:30 -04:00
|
|
|
entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier,
|
|
|
|
and a member function to call.}
|
1999-02-02 07:37:14 -05:00
|
|
|
\twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM,
|
1998-05-20 10:25:30 -04:00
|
|
|
but responds to a range of window identifiers.}
|
1999-02-02 07:37:14 -05:00
|
|
|
\twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but
|
1998-05-20 10:25:30 -04:00
|
|
|
expects a member function with a wxCommandEvent argument.}
|
1999-02-02 07:37:14 -05:00
|
|
|
\twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but
|
1998-05-20 10:25:30 -04:00
|
|
|
expects a member function with a wxCommandEvent argument.}
|
|
|
|
\end{twocollist}
|
|
|
|
|
|
|
|
\wxheading{Macros listed by event class}
|
|
|
|
|
|
|
|
The documentation for specific event macros is organised by event class. Please refer
|
|
|
|
to these sections for details.
|
|
|
|
|
|
|
|
\twocolwidtha{8cm}%
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
|
|
\twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept
|
|
|
|
activation and deactivation events.}
|
|
|
|
\twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.}
|
|
|
|
\twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure
|
|
|
|
called via \helpref{wxWindow::Close}{wxwindowclose}.}
|
|
|
|
\twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles
|
|
|
|
file drop events.}
|
|
|
|
\twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.}
|
|
|
|
\twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keybaord focus events.}
|
|
|
|
\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard
|
|
|
|
input for any window.}
|
|
|
|
\twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events
|
|
|
|
(to process background tasks, for example).}
|
|
|
|
\twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used
|
|
|
|
to handle dialog initialisation.}
|
|
|
|
\twocolitem{\helpref{wxListEvent}{wxlistevent}}{These macros handle \helpref{wxListCtrl}{wxlistctrl} events.}
|
|
|
|
\twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).}
|
|
|
|
\twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual
|
|
|
|
mouse events or all mouse events.}
|
|
|
|
\twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
|
|
|
|
\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface
|
|
|
|
update pseudo-events, which are generated to give the application the chance to update the visual state of menus,
|
|
|
|
toolbars and controls.}
|
|
|
|
\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.}
|
|
|
|
\twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from
|
|
|
|
windows, \helpref{wxScrollBar}{wxscrollbar}, and \helpref{wxSpinButton}{wxspinbutton}.}
|
|
|
|
\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.}
|
|
|
|
\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle
|
|
|
|
events informing the application that the user has changed the system colours (Windows only).}
|
|
|
|
\twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.}
|
|
|
|
\end{twocollist}
|
|
|
|
|