1 \section{\class{wxEvtHandler
}}\label{wxevthandler
}
3 A class that can handle events from the windowing system.
4 wxWindow (and therefore all window classes) are derived from
7 \wxheading{Derived from
}
9 \helpref{wxObject
}{wxobject
}
11 \wxheading{Include files
}
17 \overview{Event handling overview
}{eventhandlingoverview
}
19 \latexignore{\rtfignore{\wxheading{Members
}}}
21 \membersection{wxEvtHandler::wxEvtHandler
}
23 \func{}{wxEvtHandler
}{\void}
27 \membersection{wxEvtHandler::
\destruct{wxEvtHandler
}}
29 \func{}{\destruct{wxEvtHandler
}}{\void}
31 Destructor. If the handler is part of a chain, the destructor will
32 unlink itself and restore the previous and next handlers so that they point to
35 \membersection{wxEvtHandler::AddPendingEvent
}\label{wxevthandleraddpendingevent
}
37 \func{virtual void
}{AddPendingEvent
}{\param{wxEvent\&
}{event
}}
39 Adds an event to be processed later. The function will return immediately and the
40 event will get processed in idle time using the
\helpref{wxEvtHandler::ProcessEvent
}{wxevthandlerprocessevent
}
43 \wxheading{Parameters
}
45 \docparam{event
}{Event to add to process queue.
}
49 Note that this requires that the event has a fully implemented Clone()
50 methods so that the event can be duplicated and stored until later processing.
51 Not all events in wxWindows currently have a fully implemented Clone() method,
52 you may have to look at the source to verify this.
54 This methods automatically wakes up idle handling even if the underlying window
55 system is currently idle anyway and thus would not send any idle events. (Waking
56 up the idle handling is done calling
\helpref{::wxWakeUpIdle
}{wxwakeupidle
}.)
58 This is also the method to call for inter-thread communication. When using
59 a multi-threading program, you will often have to inform the main GUI thread
60 about the status of other working threads and this has to be done using this
61 method - which also means that this method is thread safe by means of using
62 crtical sections where needed.
64 Furthermore, it may be noted that some ports of wxWindows will probably move
65 to using this method more and more in preference over calling ProcessEvent()
66 directly so as to avoid problems with reentrant code.
68 \membersection{wxEvtHandler::Connect
}\label{wxevthandlerconnect
}
70 \func{void
}{Connect
}{\param{int
}{ id
},
71 \param{wxEventType
}{eventType
},
\param{wxObjectEventFunction
}{ function
},
72 \param{wxObject*
}{ userData = NULL
}}
74 \func{void
}{Connect
}{\param{int
}{ id
},
\param{int
}{ lastId
},
75 \param{wxEventType
}{eventType
},
\param{wxObjectEventFunction
}{ function
},
76 \param{wxObject*
}{ userData = NULL
}}
78 Connects the given function dynamically with the event handler, id and event type. This
79 is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
81 \wxheading{Parameters
}
83 \docparam{id
}{The identifier (or first of the identifier range) to be associated with the event handler function.
}
85 \docparam{lastId
}{The second part of the identifier range to be associated with the event handler function.
}
87 \docparam{eventType
}{The event type to be associated with this event handler.
}
89 \docparam{function
}{The event handler function.
}
91 \docparam{userData
}{Data to be associated with the event table entry.
}
96 frame->Connect( wxID_EXIT,
97 wxEVT_COMMAND_MENU_SELECTED,
98 (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
101 \membersection{wxEvtHandler::Disconnect
}\label{wxevthandlerdisconnect
}
103 \func{bool
}{Disconnect
}{\param{int
}{ id
},
104 \param{wxEventType
}{eventType = wxEVT_NULL
},
\param{wxObjectEventFunction
}{ function = NULL
},
105 \param{wxObject*
}{ userData = NULL
}}
107 \func{bool
}{Disconnect
}{\param{int
}{ id
},
\param{int
}{ lastId = -
1},
108 \param{wxEventType
}{eventType = wxEVT_NULL
},
\param{wxObjectEventFunction
}{ function = NULL
},
109 \param{wxObject*
}{ userData = NULL
}}
111 Disconnects the given function dynamically from the event handler, using the specified
112 parameters as search criteria and returning TRUE if a matching event handler has been
113 found and removed. This method can only disconnect from functions which have been added
114 using the
\helpref{wxEvtHandler::Connect
}{wxevthandlerconnect
} method. There is no way
115 to disconnect from events used in the (static) event tables.
117 \wxheading{Parameters
}
119 \docparam{id
}{The identifier (or first of the identifier range) associated with the event handler function.
}
121 \docparam{lastId
}{The second part of the identifier range associated with the event handler function.
}
123 \docparam{eventType
}{The event type associated with this event handler.
}
125 \docparam{function
}{The event handler function.
}
127 \docparam{userData
}{Data to be associated with the event table entry.
}
129 \membersection{wxEvtHandler::GetClientData
}\label{wxevthandlergetclientdata
}
131 \func{char*
}{GetClientData
}{\void}
133 Gets user-supplied client data.
137 Normally, any extra data the programmer wishes to associate with the object
138 should be made available by deriving a new class
139 with new data members.
143 \helpref{wxEvtHandler::SetClientData
}{wxevthandlersetclientdata
}
145 \membersection{wxEvtHandler::GetEvtHandlerEnabled
}\label{wxevthandlergetevthandlerenabled
}
147 \func{bool
}{GetEvtHandlerEnabled
}{\void}
149 Returns TRUE if the event handler is enabled, FALSE otherwise.
153 \helpref{wxEvtHandler::SetEvtHandlerEnabled
}{wxevthandlersetevthandlerenabled
}
155 \membersection{wxEvtHandler::GetNextHandler
}\label{wxevthandlergetnexthandler
}
157 \func{wxEvtHandler*
}{GetNextHandler
}{\void}
159 Gets the pointer to the next handler in the chain.
163 \helpref{wxEvtHandler::SetNextHandler
}{wxevthandlersetnexthandler
},
\rtfsp
164 \helpref{wxEvtHandler::GetPreviousHandler
}{wxevthandlergetprevioushandler
},
\rtfsp
165 \helpref{wxEvtHandler::SetPreviousHandler
}{wxevthandlersetprevioushandler
},
\rtfsp
166 \helpref{wxWindow::PushEventHandler
}{wxwindowpusheventhandler
},
\rtfsp
167 \helpref{wxWindow::PopEventHandler
}{wxwindowpopeventhandler
}
169 \membersection{wxEvtHandler::GetPreviousHandler
}\label{wxevthandlergetprevioushandler
}
171 \func{wxEvtHandler*
}{GetPreviousHandler
}{\void}
173 Gets the pointer to the previous handler in the chain.
177 \helpref{wxEvtHandler::SetPreviousHandler
}{wxevthandlersetprevioushandler
},
\rtfsp
178 \helpref{wxEvtHandler::GetNextHandler
}{wxevthandlergetnexthandler
},
\rtfsp
179 \helpref{wxEvtHandler::SetNextHandler
}{wxevthandlersetnexthandler
},
\rtfsp
180 \helpref{wxWindow::PushEventHandler
}{wxwindowpusheventhandler
},
\rtfsp
181 \helpref{wxWindow::PopEventHandler
}{wxwindowpopeventhandler
}
183 \membersection{wxEvtHandler::ProcessEvent
}\label{wxevthandlerprocessevent
}
185 \func{virtual bool
}{ProcessEvent
}{\param{wxEvent\&
}{event
}}
187 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
189 \wxheading{Parameters
}
191 \docparam{event
}{Event to process.
}
193 \wxheading{Return value
}
195 TRUE if a suitable event handler function was found and executed, and the function did not
196 call
\helpref{wxEvent::Skip
}{wxeventskip
}.
200 Normally, your application would not call this function: it is called in the wxWindows
201 implementation to dispatch incoming user interface events to the framework (and application).
203 However, you might need to call it if implementing new functionality (such as a new control) where
204 you define new event types, as opposed to allowing the user to override virtual functions.
206 An instance where you might actually override the
{\bf ProcessEvent
} function is where you want
207 to direct event processing to event handlers not normally noticed by wxWindows. For example,
208 in the
document/view architecture, documents and views are potential event handlers.
209 When an event reaches a frame,
{\bf ProcessEvent
} will need to be called on the associated
210 document and view in case event handler functions are associated with these objects.
211 The property classes library (wxProperty) also overrides
{\bf ProcessEvent
} for similar reasons.
213 The normal order of event table searching is as follows:
215 \begin{enumerate
}\itemsep=
0pt
216 \item If the object is disabled (via a call to
\helpref{wxEvtHandler::SetEvtHandlerEnabled
}{wxevthandlersetevthandlerenabled
})
217 the function skips to step (
6).
218 \item If the object is a wxWindow,
{\bf ProcessEvent
} is recursively called on the window's
\rtfsp
219 \helpref{wxValidator
}{wxvalidator
}. If this returns TRUE, the function exits.
220 \item {\bf SearchEventTable
} is called for this event handler. If this fails, the base
221 class table is tried, and so on until no more tables exist or an appropriate function was found,
222 in which case the function exits.
223 \item The search is applied down the entire chain of event handlers (usually the chain has a length
224 of one). If this succeeds, the function exits.
225 \item If the object is a wxWindow and the event is a wxCommandEvent,
{\bf ProcessEvent
} is
226 recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
227 \item Finally,
{\bf ProcessEvent
} is called on the wxApp object.
232 \helpref{wxEvtHandler::SearchEventTable
}{wxevthandlersearcheventtable
}
234 \membersection{wxEvtHandler::SearchEventTable
}\label{wxevthandlersearcheventtable
}
236 \func{bool
}{SearchEventTable
}{\param{wxEventTable\&
}{table
},
\param{wxEvent\&
}{event
}}
238 Searches the event table, executing an event handler function if an appropriate one
241 \wxheading{Parameters
}
243 \docparam{table
}{Event table to be searched.
}
245 \docparam{event
}{Event to be matched against an event table entry.
}
247 \wxheading{Return value
}
249 TRUE if a suitable event handler function was found and executed, and the function did not
250 call
\helpref{wxEvent::Skip
}{wxeventskip
}.
254 This function looks through the object's event table and tries to find an entry
255 that will match the event.
257 An entry will match if:
259 \begin{enumerate
}\itemsep=
0pt
260 \item The event type matches, and
261 \item the identifier or identifier range matches, or the event table entry's identifier is zero.
264 If a suitable function is called but calls
\helpref{wxEvent::Skip
}{wxeventskip
}, this function will
265 fail, and searching will continue.
269 \helpref{wxEvtHandler::ProcessEvent
}{wxevthandlerprocessevent
}
271 \membersection{wxEvtHandler::SetClientData
}\label{wxevthandlersetclientdata
}
273 \func{void
}{SetClientData
}{\param{char*
}{data
}}
275 Sets user-supplied client data.
277 \wxheading{Parameters
}
279 \docparam{data
}{Data to be associated with the event handler.
}
283 Normally, any extra data the programmer wishes
284 to associate with the object should be made available by deriving a new class
285 with new data members.
286 %TODO: make this void*, char* only in compatibility mode.
290 \helpref{wxEvtHandler::GetClientData
}{wxevthandlergetclientdata
}
292 \membersection{wxEvtHandler::SetEvtHandlerEnabled
}\label{wxevthandlersetevthandlerenabled
}
294 \func{void
}{SetEvtHandlerEnabled
}{\param{bool
}{enabled
}}
296 Enables or disables the event handler.
298 \wxheading{Parameters
}
300 \docparam{enabled
}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.
}
304 You can use this function to avoid having to remove the event handler from the chain, for example
305 when implementing a dialog editor and changing from edit to test mode.
309 \helpref{wxEvtHandler::GetEvtHandlerEnabled
}{wxevthandlergetevthandlerenabled
}
311 \membersection{wxEvtHandler::SetNextHandler
}\label{wxevthandlersetnexthandler
}
313 \func{void
}{SetNextHandler
}{\param{wxEvtHandler*
}{handler
}}
315 Sets the pointer to the next handler.
317 \wxheading{Parameters
}
319 \docparam{handler
}{Event handler to be set as the next handler.
}
323 \helpref{wxEvtHandler::GetNextHandler
}{wxevthandlergetnexthandler
},
\rtfsp
324 \helpref{wxEvtHandler::SetPreviousHandler
}{wxevthandlersetprevioushandler
},
\rtfsp
325 \helpref{wxEvtHandler::GetPreviousHandler
}{wxevthandlergetprevioushandler
},
\rtfsp
326 \helpref{wxWindow::PushEventHandler
}{wxwindowpusheventhandler
},
\rtfsp
327 \helpref{wxWindow::PopEventHandler
}{wxwindowpopeventhandler
}
329 \membersection{wxEvtHandler::SetPreviousHandler
}\label{wxevthandlersetprevioushandler
}
331 \func{void
}{SetPreviousHandler
}{\param{wxEvtHandler*
}{handler
}}
333 Sets the pointer to the previous handler.
335 \wxheading{Parameters
}
337 \docparam{handler
}{Event handler to be set as the previous handler.
}
341 \helpref{wxEvtHandler::GetPreviousHandler
}{wxevthandlergetprevioushandler
},
\rtfsp
342 \helpref{wxEvtHandler::SetNextHandler
}{wxevthandlersetnexthandler
},
\rtfsp
343 \helpref{wxEvtHandler::GetNextHandler
}{wxevthandlergetnexthandler
},
\rtfsp
344 \helpref{wxWindow::PushEventHandler
}{wxwindowpusheventhandler
},
\rtfsp
345 \helpref{wxWindow::PopEventHandler
}{wxwindowpopeventhandler
}