compilation fix after TRUE/FALSE change

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

diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index 16e10a1bcbb37420b1f2b45550d85df8fe3bfb06..3b543f1a72bf6a49027685e03137a752dda5bc24 100644 (file)
--- a/docs/latex/wx/evthand.tex
+++ b/docs/latex/wx/evthand.tex
@@ -8,6 +8,10 @@ this class.
 
 \helpref{wxObject}{wxobject}
 
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/event.h>
+

 \wxheading{See also}
 
 \overview{Event handling overview}{eventhandlingoverview}
 \wxheading{See also}
 
 \overview{Event handling overview}{eventhandlingoverview}


@@ -28,36 +32,111 @@ Destructor. If the handler is part of a chain, the destructor will
 unlink itself and restore the previous and next handlers so that they point to
 each other.
 
 unlink itself and restore the previous and next handlers so that they point to
 each other.
 

-\membersection{wxEvtHandler::Default}\label{wxevthandlerdefault}
+\membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}

 
 

-\func{virtual long}{Default}{\void}
+\func{virtual void}{AddPendingEvent}{\param{wxEvent\& }{event}}

 
 

-Invokes default processing if this event handler is a window.
+This function posts an event to be processed later.

 
 

-\wxheading{Return value}
+\wxheading{Parameters}

 
 

-System dependent.
+\docparam{event}{Event to add to process queue.}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-A generic way of delegating processing to the default system behaviour. It calls a platform-dependent
-default function, with parameters dependent on the event or message parameters
-originally sent from the windowing system.
+The difference between sending an event (using the
+\helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is
+that in the first case the event is processed before the function returns,
+while in the second case, the function returns immediately and the event will
+be processed sometime later (usually during the next event loop iteration).
+
+A copy of {\it event} is made by the function, so the original can be deleted
+as soon as function returns (it is common that the original is created on the
+stack).  This requires that the \helpref{wxEvent::Clone}{wxeventclone} method
+be implemented by {\it event} so that it can be duplicated and stored until
+it gets processed.
+
+This is also the method to call for inter-thread communication---it will
+post events safely between different threads which means that this method is
+thread-safe by using critical sections where needed.  In a multi-threaded
+program, you often need to inform the main GUI thread about the status of
+other working threads and such notification should be done using this method.
+
+This method automatically wakes up idle handling if the underlying window 
+system is currently idle and thus would not send any idle events. (Waking
+up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
+
+\membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
+
+\func{void}{Connect}{\param{int}{ id},
+ \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
+ \param{wxObject*}{ userData = NULL}}
+
+\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
+ \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
+ \param{wxObject*}{ userData = 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.
+
+\wxheading{Parameters}
+
+\docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
+
+\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{userData}{Data to be associated with the event table entry.}
+
+\wxheading{Example}

 
 

-Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
-may call {\bf Default}.
+\begin{verbatim}
+  frame->Connect( wxID_EXIT,
+    wxEVT_COMMAND_MENU_SELECTED,
+    (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
+\end{verbatim}
+
+\membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
+
+\func{bool}{Disconnect}{\param{int}{ id},
+ \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}}
+
+\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
+ \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = 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
+found and removed. This method can only disconnect functions which have been added
+using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
+to disconnect functions connected using the (static) event tables.
+
+\wxheading{Parameters}
+
+\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
+
+\docparam{lastId}{The second part of the identifier range associated with the event handler function.}
+
+\docparam{eventType}{The event type associated with this event handler.}
+
+\docparam{function}{The event handler function.}
+
+\docparam{userData}{Data associated with the event table entry.}

 
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 
 
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 

-\func{char* }{GetClientData}{\void}
+\func{void* }{GetClientData}{\void}

 
 Gets user-supplied client data.
 
 \wxheading{Remarks}
 
 Normally, any extra data the programmer wishes to associate with the object
 
 Gets user-supplied client data.
 
 \wxheading{Remarks}
 
 Normally, any extra data the programmer wishes to associate with the object

-should be made available by deriving a new class
-with new data members.
+should be made available by deriving a new class with new data members.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 


@@ -81,9 +160,9 @@ Gets the pointer to the next handler in the chain.
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

+\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp

 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp

-\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp

 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 
 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 


@@ -95,9 +174,9 @@ Gets the pointer to the previous handler in the chain.
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
-\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp

 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp

+\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
+\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp

 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 
 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 


@@ -191,7 +270,7 @@ fail, and searching will continue.
 
 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
 
 
 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
 

-\func{void}{SetClientData}{\param{char* }{data}}
+\func{void}{SetClientData}{\param{void* }{data}}

 
 Sets user-supplied client data.
 
 
 Sets user-supplied client data.
 


@@ -201,12 +280,10 @@ Sets user-supplied client data.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Normally, any extra data the programmer wishes
-to associate with the object should be made available by deriving a new class
+Normally, any extra data the programmer wishes to associate with 
+the object should be made available by deriving a new class

 with new data members.
 
 with new data members.
 

-TODO: make this void*, char* only in compatibility mode.
-

 \wxheading{See also}
 
 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
 \wxheading{See also}
 
 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}