documentation for window ids allocation and wxIdManager (patch 1870570)

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

diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index 2d74c6a41c2ffd5763471cd32cf7b52d7760ad3a..a5e0a0949a9d147d0115aec8d867c377f53be50f 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}


@@ -12,19 +18,23 @@ this class.
 
 <wx/event.h>
 
 
 <wx/event.h>
 

+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{See also}
 
 \overview{Event handling overview}{eventhandlingoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \wxheading{See also}
 
 \overview{Event handling overview}{eventhandlingoverview}
 
 \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,11 +44,9 @@ each other.
 
 \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
 
 
 \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
 

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

 
 

-Adds an event to be processed later. The function will return immediately and the
-event will get processed in idle time using the \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} 
-method.
+This function posts an event to be processed later.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -46,70 +54,90 @@ method.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Note that this requires that the event has a fully implemented Clone()
-method so that the event can be duplicated and stored until it gets processed later.
-Not all events in wxWindows currently have a fully implemented Clone() method,
-so you may have to look at the source to verify this.
+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).

 
 

-This methods automatically wakes up idle handling even if the underlying window 
-system is currently idle anyway and thus would not send any idle events. (Waking
-up the idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
+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. In
-a multi-threaded program, you will often have to inform the main GUI thread
-about the status of other working threads and this has to be done using this
-method - which also means that this method is thread safe by means of using
-crtical sections where needed.
+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.

 
 

-Furthermore, it may be noted that some ports of wxWindows will probably move
-to using this method more and more in preference over calling ProcessEvent()
-directly so as to avoid problems with reentrant code.
+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}
 
 
 \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{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{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
 
 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{wxFooEventHandler} for the handler for any \texttt{wxFooEvent}.}

 
 \docparam{userData}{Data to be associated with the event table entry.}
 
 
 \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,
 \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{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{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
 
 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
+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.
 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.


@@ -126,6 +154,11 @@ to disconnect functions connected using the (static) event tables.
 
 \docparam{userData}{Data associated with the event table entry.}
 
 
 \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}
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 
 \func{void* }{GetClientData}{\void}


@@ -141,11 +174,22 @@ should be made available by deriving a new class with new data members.
 
 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 
 
 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 

+\membersection{wxEvtHandler::GetClientObject}\label{wxevthandlergetclientobject}
+
+\constfunc{wxClientData*}{GetClientObject}{\void}
+
+Get a pointer to the user-supplied client data object.
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject},
+\helpref{wxClientData}{wxclientdata}
+

 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 
 \func{bool}{GetEvtHandlerEnabled}{\void}
 
 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 
 \func{bool}{GetEvtHandlerEnabled}{\void}
 

-Returns TRUE if the event handler is enabled, FALSE otherwise.
+Returns true if the event handler is enabled, false otherwise.

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


@@ -191,19 +235,19 @@ Processes an event, searching event tables and calling zero or more suitable eve
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if a suitable event handler function was found and executed, and the function did not
+true if a suitable event handler function was found and executed, and the function did not

 call \helpref{wxEvent::Skip}{wxeventskip}.
 
 \wxheading{Remarks}
 
 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
 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.


@@ -215,14 +259,14 @@ The normal order of event table searching is as follows:
 \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
 \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.
+\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
 \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.
+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}
 
 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
 \end{enumerate}
 


@@ -230,9 +274,33 @@ recursively applied to the parent window's event handler. If this returns TRUE,
 
 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
 
 
 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
 

+
+\membersection{wxEvtHandler::SafelyProcessEvent}\label{wxevthandlersafelyprocessevent}
+
+\func{bool}{SafelyProcessEvent}{\param{wxEvent\& }{event}}
+
+Processes an event by calling \helpref{ProcessEvent}{wxevthandlerprocessevent}
+and handles any exceptions that occur in the process. If an exception is
+thrown in event handler, \helpref{wxApp::OnExceptionInMainLoop}{wxapponexceptioninmainloop}
+is called.
+
+\wxheading{Parameters}
+
+\docparam{event}{Event to process.}
+
+\wxheading{Return value}
+
+\true if the event was processed, \false if no handler was found or an
+exception was thrown.
+
+\wxheading{See also}
+
+\helpref{wxWindow::HandleWindowEvent}{wxwindowhandlewindowevent}
+
+

 \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.


@@ -245,7 +313,7 @@ is found.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if a suitable event handler function was found and executed, and the function did not
+true if a suitable event handler function was found and executed, and the function did not

 call \helpref{wxEvent::Skip}{wxeventskip}.
 
 \wxheading{Remarks}
 call \helpref{wxEvent::Skip}{wxeventskip}.
 
 \wxheading{Remarks}


@@ -281,12 +349,25 @@ Sets user-supplied client data.
 
 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. You must not call this method and
+\helpref{SetClientObject}{wxevthandlersetclientobject} on the
+same class - only one of them.

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

+\membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject}
+
+\func{void}{SetClientObject}{\param{wxClientData* }{data}}
+
+Set the client data object. Any previous object will be deleted.
+
+\wxheading{See also}
+
+\helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject},
+\helpref{wxClientData}{wxclientdata}
+

 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 
 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 
 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}


@@ -295,7 +376,7 @@ Enables or disables the event handler.
 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}
+\docparam{enabled}{true if the event handler is to be enabled, false if it is to be disabled.}

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}