From d6af57d4d2b2336aa0196d5c1b3833ea98b89a78 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 7 Feb 2004 16:39:26 +0000
Subject: [PATCH] documented wxBuffered[Paint]DC

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@25569 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/bufferdc.tex | 134 +++++++++++++++++++++++++++++++++++++
 docs/latex/wx/category.tex |   2 +
 docs/latex/wx/classes.tex  |   1 +
 docs/latex/wx/tdc.tex      |   2 +-
 4 files changed, 138 insertions(+), 1 deletion(-)
 create mode 100644 docs/latex/wx/bufferdc.tex

diff --git a/docs/latex/wx/bufferdc.tex b/docs/latex/wx/bufferdc.tex
new file mode 100644
index 0000000000..8d9e3171b7
--- /dev/null
+++ b/docs/latex/wx/bufferdc.tex
@@ -0,0 +1,134 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        bufferdc.tex
+%% Purpose:     wxBufferedDC documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     07.02.04
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2004 Vadim Zeitlin
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxBufferedDC}}\label{wxbuffereddc}
+
+This simple class provides a simple way to avoid flicker: when drawing on it,
+everything is in fact drawn on an in-memory buffer (a 
+\helpref{wxBitmap}{wxbitmap}) and copied to the screen only once, when this
+object is destroyed.
+
+It can be used in the same way as any other device context. wxBufferedDC itself
+typically replaces \helpref{wxClientDC}{wxclientdc}, if you want to use it in
+your \texttt{OnPaint()} handler, you should look at
+\helpref{wxBufferedPaintDC}{wxbufferedpaintdc}.
+
+\wxheading{Derived from}
+
+\helpref{wxMemoryDC}{wxmemorydc}
+\helpref{wxDC}{wxdc}
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/dcbuffer.h>
+
+\wxheading{See also}
+
+\helpref{wxDC}{wxdc}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxBufferedDC::wxBufferedDC}\label{wxbufferedtdcctor}
+
+\func{}{wxBufferedDC}{\void}
+
+\func{}{wxBufferedDC}{\param{wxDC *}{dc}, \param{const wxSize\& }{area}, \param{int }{flags}}
+
+\func{}{wxBufferedDC}{\param{wxDC *}{dc}, \param{const wxBitmap\& }{buffer}}
+
+If you use the first, default, constructor, you must call one of the 
+\helpref{Init}{wxbufferedtdcinit} methods later in order to use the object.
+
+The other constructors initialize the object immediately and \texttt{Init()} 
+must not be called after using them.
+
+\wxheading{Parameters}
+
+\docparam{dc}{The underlying DC: everything drawn to this object will be
+flushed to this DC when this object is destroyed.}
+
+\docparam{area}{The size of the bitmap to be used for buffering (this bitmap is
+created internally when it is not given explicitely).}
+
+\docparam{flags}{Can currently only include the flag 
+\texttt{wxBUFFER\_DC\_PRESERVE\_BG} which means that the existing background
+of \arg{dc} must be copied to this object before doing anything else, otherwise
+the background is overwritten (which is more efficient).}
+
+\docparam{buffer}{Explicitly provided bitmap to be used for buffering: this is
+the most efficient solution as the bitmap doesn't have to be recreated each
+time but it also requires more memory as the bitmap is never freed. The bitmap
+should have appropriate size, anything drawn outside of its bounds is clipped.}
+
+
+\membersection{wxBufferedDC::Init}\label{wxbufferedtdcinit}
+
+\func{void}{Init}{\param{wxDC *}{dc}, \param{const wxSize\& }{area}, \param{int }{flags}}
+
+\func{void}{Init}{\param{wxDC *}{dc}, \param{const wxBitmap\& }{buffer}}
+
+These functions initialize the object created using the default constructor.
+Please see \helpref{constructors documentation}{wxbufferedtdcctor} for details.
+
+
+% VZ: UnMask() intentionally not documented, we might want to make it private
+
+
+\membersection{wxBufferedDC::\destruct{wxBufferedDC}}\label{wxbuffereddcdtor}
+
+Copies everything drawn on the DC so far to the underlying DC associated with
+this object.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxBufferedPaintDC}}\label{wxbufferedpaintdc}
+
+This is a subclass of \helpref{wxBufferedDC}{wxbuffereddc} which can be used
+inside \texttt{OnPaint()} handler. Just create an object of this class instead
+of \helpref{wxPaintDC}{wxpaintdc} and that's all you have to do to (mostly)
+avoid flicker. The only thing to watch out for is that if you are using this
+class together with \helpref{wxScrolledWindow}{wxscrolledwindow}, you probably
+do \textbf{not} want to call \helpref{PrepareDC}{wxwindowpreparedc} on it as it
+already does this internally for the real underlying wxPaintDC.
+
+\wxheading{Derived from}
+
+\helpref{wxMemoryDC}{wxmemorydc}
+\helpref{wxDC}{wxdc}
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/dcbuffer.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxBufferedPaintDC::wxBufferedPaintDC}\label{wxbufferedpaintdcctor}
+
+\func{}{wxBufferedPaintDC}{\param{wxWindow *}{window}, \param{int }{flags}}
+
+\func{}{wxBufferedPaintDC}{\param{wxWindow *}{window}, \param{const wxBitmap\& }{buffer}}
+
+As with \helpref{wxBufferedDC}{wxbuffereddcctor}, you may either provide the
+bitmap to be used for buffering or let this object create one internally (in
+the latter case, the size of the client part of the window is used).
+
+
+\membersection{wxBufferedPaintDC::\destruct{wxBufferedPaintDC}}\label{wxbufferedpaintdcdtor}
+
+Copies everything drawn on the DC so far to the window associated with this
+object.
+
+
diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index 5cc2615cc3..5f15e9a86b 100644
--- a/docs/latex/wx/category.tex
+++ b/docs/latex/wx/category.tex
@@ -162,6 +162,8 @@ by passing different device contexts.
 
 \twocolwidtha{6cm}
 \begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxBufferedDC}{wxbuffereddc}}{A helper device context for double buffered drawing.}
+\twocolitem{\helpref{wxBufferedPaintDC}{wxbufferedpaintdc}}{A helper device context for double buffered drawing inside \textbf{OnPaint}.}
 \twocolitem{\helpref{wxClientDC}{wxclientdc}}{A device context to access the client area outside {\bf OnPaint} events}
 \twocolitem{\helpref{wxPaintDC}{wxpaintdc}}{A device context to access the client area inside {\bf OnPaint} events}
 \twocolitem{\helpref{wxWindowDC}{wxwindowdc}}{A device context to access the non-client area}
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index fdaf96afe9..c573dc5280 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -19,6 +19,7 @@
 \input bmphand.tex
 \input boxsizer.tex
 \input brush.tex
+\input bufferdc.tex
 \input strmbfrd.tex
 \input busycurs.tex
 \input busyinfo.tex
diff --git a/docs/latex/wx/tdc.tex b/docs/latex/wx/tdc.tex
index 58db517ae4..70500d92ec 100644
--- a/docs/latex/wx/tdc.tex
+++ b/docs/latex/wx/tdc.tex
@@ -1,6 +1,6 @@
 \section{Device context overview}\label{dcoverview}
 
-Classes: \helpref{wxDC}{wxdc}, \helpref{wxPostScriptDC}{wxpostscriptdc},\rtfsp
+Classes: \helpref{wxBufferedDC}{wxbuffereddc}, \helpref{wxBufferedPaintDC}{wxbufferedpaintdc}, \helpref{wxDC}{wxdc}, \helpref{wxPostScriptDC}{wxpostscriptdc},\rtfsp
 \rtfsp\helpref{wxMetafileDC}{wxmetafiledc}, \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxPrinterDC}{wxprinterdc},\rtfsp
 \helpref{wxScreenDC}{wxscreendc}, \helpref{wxClientDC}{wxclientdc}, \helpref{wxPaintDC}{wxpaintdc},\rtfsp
 \helpref{wxWindowDC}{wxwindowdc}.
-- 
2.50.0

