wxNB_HITTEST_* flags renamed to wxBK_HITTEST_* to serve all book controls.

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

diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index e891d4f826337a79b19a0eafe79bae3ea5d5e71e..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.
 
 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}
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}


@@ -18,13 +24,13 @@ this class.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxEvtHandler::wxEvtHandler}
+\membersection{wxEvtHandler::wxEvtHandler}\label{wxevthandlerctor}

 
 \func{}{wxEvtHandler}{\void}
 
 Constructor.
 
 
 \func{}{wxEvtHandler}{\void}
 
 Constructor.
 

-\membersection{wxEvtHandler::\destruct{wxEvtHandler}}
+\membersection{wxEvtHandler::\destruct{wxEvtHandler}}\label{wxevthandlerdtor}

 
 \func{}{\destruct{wxEvtHandler}}{\void}
 
 
 \func{}{\destruct{wxEvtHandler}}{\void}
 


@@ -34,7 +40,7 @@ each other.
 
 \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
 
 
 \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.
 
 
 This function posts an event to be processed later.
 


@@ -68,47 +74,61 @@ up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
 
 \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
 
 
 \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{wxEvtHandler*}{ eventSink = NULL}}
 
  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  \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{wxEvtHandler*}{ eventSink = NULL}}
 
  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  \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
 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}
 
 
 \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{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,
 
 \docparam{userData}{Data to be associated with the event table entry.}
 
 \docparam{eventSink}{Object whose member function should be called. If this is NULL,

-'this' will be used.}
+\textit{this} will be used.}

 
 \wxheading{Example}
 
 \begin{verbatim}
   frame->Connect( wxID_EXIT,
     wxEVT_COMMAND_MENU_SELECTED,
 
 \wxheading{Example}
 
 \begin{verbatim}
   frame->Connect( wxID_EXIT,
     wxEVT_COMMAND_MENU_SELECTED,

-    (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
+    wxCommandEventHandler(MyFrame::OnQuit) );

 \end{verbatim}
 
 \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}
 
 \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{wxEvtHandler*}{ eventSink = NULL}}
 
  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = 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{wxEvtHandler*}{ eventSink = NULL}}
 
  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
  \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 


@@ -132,6 +152,9 @@ to disconnect functions connected using the (static) event tables.
 
 \docparam{eventSink}{Object whose member function should be called.}
 
 
 \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}
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 
 \func{void* }{GetClientData}{\void}


@@ -213,14 +236,14 @@ call \helpref{wxEvent::Skip}{wxeventskip}.
 
 \wxheading{Remarks}
 
 
 \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
 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.
 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.


@@ -249,7 +272,7 @@ recursively applied to the parent window's event handler. If this returns true,
 
 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
 
 
 \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.
 
 Searches the event table, executing an event handler function if an appropriate one
 is found.