Applied ref-couting patch.

[wxWidgets.git] / docs / latex / wx / evthand.tex

diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index ad4daf7f71673be7944bfc6abe404245ce357f81..98fed356957a0a225c4c69b9fe8bbec988f0bb73 100644 (file)
--- a/docs/latex/wx/evthand.tex
+++ b/docs/latex/wx/evthand.tex
@@ -4,6 +4,12 @@ A class that can handle events from the windowing system.
 wxWindow (and therefore all window classes) are derived from
 this class.
 
+When events are received, wxEvtHandler invokes the method listed in the
+event table using itself as the object.  When using multiple inheritance
+it is imperative that the wxEvtHandler(-derived) class be the first
+class inherited such that the "this" pointer for the overall object
+will be identical to the "this" pointer for the wxEvtHandler portion.
+
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
@@ -18,13 +24,13 @@ this class.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxEvtHandler::wxEvtHandler}
+\membersection{wxEvtHandler::wxEvtHandler}\label{wxevthandlerctor}
 
 \func{}{wxEvtHandler}{\void}
 
 Constructor.
 
-\membersection{wxEvtHandler::\destruct{wxEvtHandler}}
+\membersection{wxEvtHandler::\destruct{wxEvtHandler}}\label{wxevthandlerdtor}
 
 \func{}{\destruct{wxEvtHandler}}{\void}
 
@@ -34,7 +40,7 @@ each other.
 
 \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
 
-\func{virtual void}{AddPendingEvent}{\param{wxEvent\& }{event}}
+\func{void}{AddPendingEvent}{\param{wxEvent\& }{event}}
 
 This function posts an event to be processed later.
 
@@ -68,46 +74,63 @@ up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
 
 \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
 
-\func{void}{Connect}{\param{int}{ id},
+\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
- \param{wxObject*}{ userData = NULL}}
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 
-\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
+\func{void}{Connect}{\param{int}{ id},
  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
- \param{wxObject*}{ userData = NULL}}
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
+
+\func{void}{Connect}{\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 
 Connects the given function dynamically with the event handler, id and event type. This
-is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
+is an alternative to the use of static event tables. See the 'event' or the old 'dynamic' sample for usage.
 
 \wxheading{Parameters}
 
-\docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
+\docparam{id}{The identifier (or first of the identifier range) to be
+associated with the event handler function. For the version not taking this
+argument, it defaults to \texttt{wxID\_ANY}.}
 
 \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}
 
 \docparam{eventType}{The event type to be associated with this event handler.}
 
-\docparam{function}{The event handler function.}
+\docparam{function}{The event handler function. Note that this function should
+be explicitly converted to the correct type which can be done using a macro
+called \texttt{wxFooHandler} for the handler for any \texttt{wxFooEvent}.}
 
 \docparam{userData}{Data to be associated with the event table entry.}
 
+\docparam{eventSink}{Object whose member function should be called. If this is NULL,
+\textit{this} will be used.}
+
 \wxheading{Example}
 
 \begin{verbatim}
   frame->Connect( wxID_EXIT,
     wxEVT_COMMAND_MENU_SELECTED,
-    (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
+    wxCommandEventHandler(MyFrame::OnQuit) );
 \end{verbatim}
 
+\perlnote{In wxPerl this function takes 4 arguments: \texttt{id,
+lastid, type, method}; if \texttt{method} is \texttt{undef}, the
+handler is disconnected.}
+
 \membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
 
-\func{bool}{Disconnect}{\param{int}{ id},
+\func{bool}{Disconnect}{\param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
+
+\func{bool}{Disconnect}{\param{int}{ id = \texttt{wxID\_ANY}},
  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
- \param{wxObject*}{ userData = NULL}}
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 
-\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
+\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = \texttt{wxID\_ANY}},
  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
- \param{wxObject*}{ userData = NULL}}
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 
 Disconnects the given function dynamically from the event handler, using the specified
 parameters as search criteria and returning true if a matching function has been
@@ -127,6 +150,11 @@ to disconnect functions connected using the (static) event tables.
 
 \docparam{userData}{Data associated with the event table entry.}
 
+\docparam{eventSink}{Object whose member function should be called.}
+
+\perlnote{In wxPerl this function takes 3 arguments: \texttt{id,
+lastid, type}.}
+
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 
 \func{void* }{GetClientData}{\void}
@@ -208,14 +236,14 @@ call \helpref{wxEvent::Skip}{wxeventskip}.
 
 \wxheading{Remarks}
 
-Normally, your application would not call this function: it is called in the wxWindows
+Normally, your application would not call this function: it is called in the wxWidgets
 implementation to dispatch incoming user interface events to the framework (and application).
 
 However, you might need to call it if implementing new functionality (such as a new control) where
 you define new event types, as opposed to allowing the user to override virtual functions.
 
 An instance where you might actually override the {\bf ProcessEvent} function is where you want
-to direct event processing to event handlers not normally noticed by wxWindows. For example,
+to direct event processing to event handlers not normally noticed by wxWidgets. For example,
 in the document/view architecture, documents and views are potential event handlers.
 When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
 document and view in case event handler functions are associated with these objects.
@@ -244,7 +272,7 @@ recursively applied to the parent window's event handler. If this returns true,
 
 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
 
-\func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
+\func{virtual bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
 
 Searches the event table, executing an event handler function if an appropriate one
 is found.