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

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

diff --git a/docs/latex/wx/evthand.tex b/docs/latex/wx/evthand.tex
index 73322665b8fd1649d3dc45f50eb6492332fd8b52..a922333c501b000a2b4d99a86a1a105e9d57833c 100644 (file)
--- a/docs/latex/wx/evthand.tex
+++ b/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.
 
 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},
 \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}
 
     (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.
+
+\wxheading{Parameters}

 
 

-System dependent.
+\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}

 
 

-\wxheading{Remarks}
+\docparam{lastId}{The second part 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
-default function, with parameters dependent on the event or message parameters
-originally sent from the windowing system.
+\docparam{eventType}{The event type associated with this event handler.}

 
 

-Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
-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}
 
 
 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index d2bcd33f54ea131bd4d3be62dbc38e61083526eb..e3deb8d61a15a22821669f615f57173e2bb6b46c 100644 (file)
--- a/docs/latex/wx/function.tex
+++ b/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}
 
 
 \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}
 
 
 \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
 
 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}
 
 
 \wxheading{Include files}
 


@@ -1711,6 +1718,21 @@ function.
 
 <wx/app.h> or <wx/utils.h>
 
 
 <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.
 \section{Macros}\label{macros}
 
 These macros are defined in wxWindows.

diff --git a/docs/latex/wx/tevent.tex b/docs/latex/wx/tevent.tex
index 84e7e58ec0f4f4ce48499b9f1ae1b868cbdd5c6e..718f2eaae18d92ca97261fe82dbd1e06f9c38a56 100644 (file)
--- a/docs/latex/wx/tevent.tex
+++ b/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{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}
 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
 \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
 \end{twocollist}

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 9a24dac8ab2ffc6a6e9d2f984e96e210d5bf86f4..2cfb54137d3fed2744cf7ab8c7a3c0340515756f 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -223,7 +223,7 @@ implements the following methods:\par
 
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
 
 \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.
 
 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}
 
 
 \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).
 
 
 Enables or disables elibility for drop file events (OnDropFiles).
 


@@ -382,7 +382,7 @@ Windows only.
 
 \membersection{wxWindow::Enable}\label{wxwindowenable}
 
 
 \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.
 
 
 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},
 
 \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.
 
 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}
 
 
 \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
 
 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}
 
 
 \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
 = 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}
 
 
 \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
 
 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
 
 \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.
 
 
 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}
 
 \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.
 
 
 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}
 
 
 \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.
 
 
 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}
 
 \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.
 
 
 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}
 
 
 \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.
 
 
 Shows or hides the window.