Updates to event docs. (removed evthandler::default).

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4644 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/evthand.tex

@@ -32,6 +32,39 @@ 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.
 
+\membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
+
+\func{virtual void}{AddPendingEvent}{\param{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.
+
+\wxheading{Parameters}
+
+\docparam{event}{Event to add to process queue.}
+
+\wxheading{Remarks}
+
+Note that this requires that the event has a fully implemented Clone()
+methods so that the event can be duplicated and stored until later processing.
+Not all events in wxWindows currently have a fully implemented Clone() method,
+you may have to look at the source to verify this.
+
+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}.)
+
+This is also the method to call for inter-thread communication. When using
+a multi-threading 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.
+
+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.
+
 \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
 
 \func{void}{Connect}{\param{int}{ id},
@@ -65,24 +98,33 @@ is an alternative to the use of static event tables. See the 'dynamic' sample fo
     (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
 \end{verbatim}
 
-\membersection{wxEvtHandler::Default}\label{wxevthandlerdefault}
+\membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
 
-\func{virtual long}{Default}{\void}
+\func{bool}{Disconnect}{\param{int}{ id},
+ \param{wxEventType }{eventType = wxEVT_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}}
 
-Invokes default processing if this event handler is a window.
+\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
+ \param{wxEventType }{eventType = wxEVT_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}}
 
-\wxheading{Return value}
+Disconnects the given function dynamically from the event handler, using the specified
+parameters as search criteria and returning TRUE if a matching event handler has been
+found and removed. This method can only disconnect from functions which have been added
+using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
+to disconnect from events used in the (static) event tables.
 
-System dependent.
+\wxheading{Parameters}
 
-\wxheading{Remarks}
+\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
 
-A generic way of delegating processing to the default system behaviour. It calls a platform-dependent
+\docparam{lastId}{The second part of the identifier range associated with the event handler function.}
-default function, with parameters dependent on the event or message parameters
-originally sent from the windowing system.
 
-Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
+\docparam{eventType}{The event type associated with this event handler.}
-may call {\bf Default}.
+
+\docparam{function}{The event handler function.}
+
+\docparam{userData}{Data to be associated with the event table entry.}
 
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 

docs/latex/wx/function.tex

@@ -862,7 +862,9 @@ Sets the translation (from the top left corner) for PostScript output. The defau
 
 \section{Clipboard functions}\label{clipsboard}
 
-These clipboard functions are implemented for Windows only.
+These clipboard functions are implemented for Windows only. The use of these functions
+is drepated and the code no longer maintained. Use the \helpref{wxClipboard}{wxclipboard}
+class instead.
 
 \wxheading{Include files}
 
@@ -1513,7 +1515,12 @@ sometime later - usually during the next even loop iteration.
 
 Note that a copy of the {\it event} is made by the function, so the original
 copy can be deleted as soon as function returns. This function can also be used
-to send events between different threads safely.
+to send events between different threads safely. As this function makes a
+copy of the event, the event needs to have a fully implemented Clone() method,
+which may not be the case for all event in wxWindows.
+
+See also \helpref{AddPendingEvent}{wxevthandleraddpendingevent} (which this function
+uses internally).
 
 \wxheading{Include files}
 
@@ -1711,6 +1718,21 @@ function.
 
 <wx/app.h> or <wx/utils.h>
 
+\membersection{::wxWakeUpIdle}\label{wxwakeupidle}
+
+\func{void}{wxWakeUpIdle}{\void}
+
+This functions wakes up the (internal and platform dependent) idle system, i.e. it
+will force the system to send an idle event even if the system currently {\it is}
+idle and thus would not send any idle event until after some other event would get
+sent. This is also useful for sending events between two threads and is used by
+the corresponding functions \helpref{::wxPostEvent}{wxpostevent} and 
+\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}.
+
+\wxheading{Include files}
+
+<wx/app.h>
+
 \section{Macros}\label{macros}
 
 These macros are defined in wxWindows.

docs/latex/wx/tevent.tex

@@ -173,7 +173,7 @@ events which will NOT get sent to the parent's event handler:
 \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event}
 \twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information}
 \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
-\twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{An event, sent by a scrolled window, not a scroll bar.}
+\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}

docs/latex/wx/window.tex

@@ -223,7 +223,7 @@ implements the following methods:\par
 
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
-\func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}
+\func{virtual bool}{Close}{\param{bool}{ force = FALSE}}
 
 The purpose of this call is to provide a safer way of destroying a window than using
 the {\it delete} operator.
@@ -363,7 +363,7 @@ Destroys all children of a window.  Called automatically by the destructor.
 
 \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles}
 
-\func{virtual void}{DragAcceptFiles}{\param{const bool}{ accept}}
+\func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}}
 
 Enables or disables elibility for drop file events (OnDropFiles).
 
@@ -382,7 +382,7 @@ Windows only.
 
 \membersection{wxWindow::Enable}\label{wxwindowenable}
 
-\func{virtual void}{Enable}{\param{const bool}{ enable}}
+\func{virtual void}{Enable}{\param{bool}{ enable}}
 
 Enable or disable the window for user input.
 
@@ -714,7 +714,7 @@ implements the following methods:\par
 
 \constfunc{virtual void}{GetTextExtent}{\param{const wxString\& }{string}, \param{int* }{x}, \param{int* }{y},
  \param{int* }{descent = NULL}, \param{int* }{externalLeading = NULL},
- \param{const wxFont* }{font = NULL}, \param{const bool}{ use16 = FALSE}}
+ \param{const wxFont* }{font = NULL}, \param{bool}{ use16 = FALSE}}
 
 Gets the dimensions of the string as it would be drawn on the
 window with the currently selected font.
@@ -878,7 +878,7 @@ or frame).
 
 \membersection{wxWindow::MakeModal}\label{wxwindowmakemodal}
 
-\func{virtual void}{MakeModal}{\param{const bool }{flag}}
+\func{virtual void}{MakeModal}{\param{bool }{flag}}
 
 Disables all other windows in the application so that
 the user can only interact with this window. (This function
@@ -1616,7 +1616,7 @@ or frame).
 
 \membersection{wxWindow::Refresh}\label{wxwindowrefresh}
 
-\func{virtual void}{Refresh}{\param{const bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect
+\func{virtual void}{Refresh}{\param{bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect
 = NULL}}
 
 Causes a message or event to be generated to repaint the
@@ -1719,7 +1719,7 @@ Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxa
 
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
-\func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
+\func{void}{SetAutoLayout}{\param{bool}{ autoLayout}}
 
 Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will
 be called automatically when the window is resized. Use in connection with
@@ -1970,7 +1970,7 @@ Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead.
 
 \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp
 \param{int }{thumbSize}, \param{int }{range},\rtfsp
-\param{const bool }{refresh = TRUE}}
+\param{bool }{refresh = TRUE}}
 
 Sets the scrollbar properties of a built-in scrollbar.
 
@@ -2019,7 +2019,7 @@ from your \helpref{wxWindow::OnSize}{wxwindowonsize} event handler function.
 \begin{comment}
 \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage}
 
-\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{bool }{refresh = TRUE}}
 
 Sets the page size of one of the built-in scrollbars.
 
@@ -2057,7 +2057,7 @@ handling of pages and ranges.
 
 \membersection{wxWindow::SetScrollPos}\label{wxwindowsetscrollpos}
 
-\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{bool }{refresh = TRUE}}
 
 Sets the position of one of the built-in scrollbars.
 
@@ -2084,7 +2084,7 @@ application to take note of scrollbar attributes and redraw contents accordingly
 \begin{comment}
 \membersection{wxWindow::SetScrollRange}\label{wxwindowsetscrollrange}
 
-\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{bool }{refresh = TRUE}}
 
 Sets the range of one of the built-in scrollbars.
 
@@ -2255,7 +2255,7 @@ create a new validator of this type.
 
 \membersection{wxWindow::Show}\label{wxwindowshow}
 
-\func{virtual bool}{Show}{\param{const bool}{ show}}
+\func{virtual bool}{Show}{\param{bool}{ show}}
 
 Shows or hides the window.