added null pointer check and assert

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

diff --git a/docs/latex/wx/tevent.tex b/docs/latex/wx/tevent.tex
index e4a42328aebb98b162c2398e35e36ec47c497c2a..7468d45803e380c3dd43826aa1927c1f7a59126d 100644 (file)
--- a/docs/latex/wx/tevent.tex
+++ b/docs/latex/wx/tevent.tex
@@ -211,7 +211,6 @@ here is a list of system events which will NOT get sent to the parent's event ha
 \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
 \twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)}
 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
 \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
 \twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)}
 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}

-\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}

 \end{twocollist}
 
 In some cases, it might be desired by the programmer to get a certain number
 \end{twocollist}
 
 In some cases, it might be desired by the programmer to get a certain number


@@ -220,6 +219,30 @@ used by, the native controls in a dialog. In this case, a special event handler
 will have to be written that will override ProcessEvent() in order to pass
 all events (or any selection of them) to the parent window.
 
 will have to be written that will override ProcessEvent() in order to pass
 all events (or any selection of them) to the parent window.
 

+
+\subsection{Events generated by the user vs programmatically generated events}\label{progevent}
+
+While generically \helpref{wxEvents}{wxevent} can be generated both by user
+actions (e.g. resize of a \helpref{wxWindow}{wxwindow}) and by calls to functions
+(e.g. \helpref{wxWindow::SetSize}{wxwindowsetsize}), wxWidgets controls
+normally send \helpref{wxCommandEvent}{wxcommandevent}-derived events only for
+the user-generated events. The only {\bf exceptions} to this rule are:
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxNotebook::AddPage}{wxnotebookaddpage}}{No event-free alternatives}
+\twocolitem{\helpref{wxNotebook::AdvanceSelection}{wxnotebookadvanceselection}}{No event-free alternatives}
+\twocolitem{\helpref{wxNotebook::DeletePage}{wxnotebookdeletepage}}{No event-free alternatives}
+\twocolitem{\helpref{wxNotebook::SetSelection}{wxnotebooksetselection}}{Use \helpref{wxNotebook::ChangeSelection}{wxnotebookchangeselection} instead, as \helpref{wxNotebook::SetSelection}{wxnotebooksetselection} is deprecated}
+\twocolitem{\helpref{wxTreeCtrl::Delete}{wxtreectrldelete}}{No event-free alternatives}
+\twocolitem{\helpref{wxTreeCtrl::DeleteAllItems}{wxtreectrldeleteallitems}}{No event-free alternatives}
+\twocolitem{\helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}}{No event-free alternatives}
+\twocolitem{All \helpref{wxTextCtrl}{wxtextctrl} methods}{\helpref{wxTextCtrl::ChangeValue}{wxtextctrlchangevalue} can be used instead
+of \helpref{wxTextCtrl::SetValue}{wxtextctrlsetvalue} but the other functions,
+such as \helpref{Replace}{wxtextctrlreplace} or \helpref{WriteText}{wxtextctrlwritetext} 
+don't have event-free equivalents}
+\end{twocollist}
+
+

 % VZ: it doesn't work like this, but just in case we ever reenable this
 %     behaviour, I leave it here
 %
 % VZ: it doesn't work like this, but just in case we ever reenable this
 %     behaviour, I leave it here
 %


@@ -245,8 +268,9 @@ defining the appropriate event table, and then call
 \rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably,
 \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this
 event handler the object that responds to events. This way, you can avoid
 \rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably,
 \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this
 event handler the object that responds to events. This way, you can avoid

-a lot of class derivation, and use the same event handler object to
-handle events from instances of different classes. If you ever have to call a window's event handler
+a lot of class derivation, and use instances of the same event handler class (but different
+objects as the same event handler object shouldn't be used more than once) to
+handle events from instances of different widget classes. If you ever have to call a window's event handler

 manually, use the GetEventHandler function to retrieve the window's event handler and use that
 to call the member function. By default, GetEventHandler returns a pointer to the window itself
 unless an application has redirected event handling using SetEventHandler or PushEventHandler.
 manually, use the GetEventHandler function to retrieve the window's event handler and use that
 to call the member function. By default, GetEventHandler returns a pointer to the window itself
 unless an application has redirected event handling using SetEventHandler or PushEventHandler.


@@ -417,16 +441,21 @@ and this is done using the following macros:
 
 \begin{verbatim}
 // in the header of the source file
 
 \begin{verbatim}
 // in the header of the source file

+BEGIN_DECLARE_EVENT_TYPES()

 DECLARE_EVENT_TYPE(name, value)
 DECLARE_EVENT_TYPE(name, value)

+END_DECLARE_EVENT_TYPES()

 
 // in the implementation
 DEFINE_EVENT_TYPE(name)
 \end{verbatim}
 
 You can ignore the {\it value} parameter of the DECLARE\_EVENT\_TYPE macro
 
 // in the implementation
 DEFINE_EVENT_TYPE(name)
 \end{verbatim}
 
 You can ignore the {\it value} parameter of the DECLARE\_EVENT\_TYPE macro

-since it used only for backwards compatibility with wxWidgets 2.0.x based
+since it is used only for backwards compatibility with wxWidgets 2.0.x based

 applications where you have to give the event type ID an explicit value.
 
 applications where you have to give the event type ID an explicit value.
 

+See also the \helpref{event sample}{sampleevent} for an example of code
+defining and working with the custom event types.
+

 \wxheading{Using existing event classes}
 
 If you just want to use a \helpref{wxCommandEvent}{wxcommandevent} with
 \wxheading{Using existing event classes}
 
 If you just want to use a \helpref{wxCommandEvent}{wxcommandevent} with


@@ -485,9 +514,9 @@ but responds to a range of window identifiers.}
 expects a member function with a wxCommandEvent argument.}
 \twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but
 expects a member function with a wxCommandEvent argument.}
 expects a member function with a wxCommandEvent argument.}
 \twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but
 expects a member function with a wxCommandEvent argument.}

-\twocolitem{\windowstyle{EVT\_NOTIFY(id, event, func)}}{The same as EVT\_CUSTOM, but
+\twocolitem{\windowstyle{EVT\_NOTIFY(event, id, func)}}{The same as EVT\_CUSTOM, but

 expects a member function with a wxNotifyEvent argument.}
 expects a member function with a wxNotifyEvent argument.}

-\twocolitem{\windowstyle{EVT\_NOTIFY\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but
+\twocolitem{\windowstyle{EVT\_NOTIFY\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM\_RANGE, but

 expects a member function with a wxNotifyEvent argument.}
 \end{twocollist}
 
 expects a member function with a wxNotifyEvent argument.}
 \end{twocollist}
 


@@ -498,9 +527,7 @@ Under certain circumstances, it will be required to define your own event
 class e.g. for sending more complex data from one place to another. Apart
 from defining your event class, you will also need to define your own
 event table macro (which is quite long). Watch out to put in enough
 class e.g. for sending more complex data from one place to another. Apart
 from defining your event class, you will also need to define your own
 event table macro (which is quite long). Watch out to put in enough

-casts to the inherited event function. Here is an example, taken mostly
-from the {\it wxPlot} library, which is in the {\it contrib} section of
-the wxWidgets sources.
+casts to the inherited event function. Here is an example:

 
 {\small%
 \begin{verbatim}
 
 {\small%
 \begin{verbatim}


@@ -523,7 +550,7 @@ private:
     wxPlotCurve   *m_curve;
 };
 
     wxPlotCurve   *m_curve;
 };
 

-DECLARE_EVENT_MACRO( wxEVT_PLOT_ACTION, -1 )
+DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )

 
 typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);
 
 
 typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);