From bc51e42e8b8cdf53ef8e24ab9568236329420778 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Mon, 11 Aug 2003 00:33:11 +0000
Subject: [PATCH] more wxRendererNative docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@22759 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/classes.tex  |   5 +-
 docs/latex/wx/delgrend.tex |  70 ++++++++++++++++
 docs/latex/wx/renderer.tex | 160 ++++++++++++++++++++++++++++++++++++-
 docs/latex/wx/rendver.tex  |  63 +++++++++++++++
 docs/latex/wx/splitpar.tex |  48 +++++++++++
 5 files changed, 344 insertions(+), 2 deletions(-)
 create mode 100644 docs/latex/wx/delgrend.tex
 create mode 100644 docs/latex/wx/rendver.tex
 create mode 100644 docs/latex/wx/splitpar.tex

diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index 7d90341fe7..1b48ad7659 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -63,8 +63,9 @@
 \input datespan.tex
 \input datetime.tex
 \input db.tex
-\input dc.tex
 \input debugcxt.tex
+\input delgrend.tex
+\input dc.tex
 \input dialog.tex
 \input dialevt.tex
 \input dialup.tex
@@ -239,6 +240,7 @@
 \input regex.tex
 \input region.tex
 \input renderer.tex
+\input rendver.tex
 \input sashevt.tex
 \input sashlayw.tex
 \input sashwin.tex
@@ -268,6 +270,7 @@
 \input splash.tex
 \input splitevt.tex
 \input splitter.tex
+\input splitpar.tex
 \input statbmp.tex
 \input statbox.tex
 \input sbsizer.tex
diff --git a/docs/latex/wx/delgrend.tex b/docs/latex/wx/delgrend.tex
new file mode 100644
index 0000000000..e1099b7eb2
--- /dev/null
+++ b/docs/latex/wx/delgrend.tex
@@ -0,0 +1,70 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        delgrend.tex
+%% Purpose:     wxDelegateRendererNative documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     11.08.03
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDelegateRendererNative}}\label{wxdelegaterenderernative}
+
+wxDelegateRendererNative allows reuse of renderers code by forwarding all the 
+\helpref{wxRendererNative}{wxrenderernative} methods to the given object and
+thus allowing you to only modify some of its methods -- without having to
+reimplement all of them.
+
+Note that the ``normal'', inheritance-based approach, doesn't work with the
+renderers as it is impossible to derive from a class unknown at compile-time
+and the renderer is only chosen at run-time. So suppose that you want to only
+add something to the drawing of the tree control buttons but leave all the
+other methods unchanged -- the only way to do it, considering that the renderer
+class which you want to customize might not even be written yet when you write
+your code (it could be written later and loaded from a DLL during run-time), is
+by using this class.
+
+Except for the constructor, it has exactly the same methods as 
+\helpref{wxRendererNative}{wxrenderernative} and their implementation is
+trivial: they are simply forwarded to the real renderer. Note that the ``real''
+renderer may, in turn, be a wxDelegateRendererNative as well and that there may
+be arbitrarily many levels like this -- but at the end of the chain there must
+be a real renderer which does the drawing.
+
+\wxheading{Derived from}
+
+\helpref{wxRendererNative}{wxrenderernative}
+
+\wxheading{Include files}
+
+<wx/renderer.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDelegateRendererNative::wxDelegateRendererNative}\label{wxdelegaterenderernativewxdelegaterenderernative}
+
+\func{}{wxDelegateRendererNative}{\void}
+
+\func{}{wxDelegateRendererNative}{\param{wxRendererNative\& }{rendererNative}}
+
+The default constructor does the same thing as the other one except that it
+uses the \helpref{generic renderer}{wxrenderernativegetgeneric} instead of the
+user-specified \arg{rendererNative}.
+
+In any case, this sets up the delegate renderer object to follow all calls to
+the specified real renderer.
+
+Note that this object does \emph{not} take ownership of (i.e. won't delete)
+\arg{rendererNative}.
+
+
+\membersection{wxDelegateRendererNative::DrawXXX}
+
+\func{}{DrawXXX}{\param{}{$\ldots$}}
+
+This class also provides all the virtual methods of 
+\helpref{wxRendererNative}{wxrenderernative}, please refer to that class
+documentation for the details.
+
diff --git a/docs/latex/wx/renderer.tex b/docs/latex/wx/renderer.tex
index 3e6d8fb5ac..9c668b4848 100644
--- a/docs/latex/wx/renderer.tex
+++ b/docs/latex/wx/renderer.tex
@@ -9,7 +9,7 @@
 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{\class{wxRenderer}}\label{wxrenderer}
+\section{\class{wxRendererNative}}\label{wxrenderernative}
 
 First, a brief introduction into what is wxRenderer and why is it needed.
 
@@ -36,4 +36,162 @@ which are used by the generic controls. There is always a default global
 renderer but it may be changed or extended by the user, see 
 \helpref{Render sample}{samplerender}.
 
+All drawing functions take some standard parameters:
+\begin{itemize}
+    \item \arg{win} is the window being drawn. it is normally not used and when
+          it is it should only be used as a generic \helpref{wxWindow}{wxwindow} 
+          (in order to get its low level handle, for example), but you should
+          \emph{not} assume that it is of some given type as the same renderer
+          function may be reused for drawing different kinds of control.
+    \item \arg{dc} is the \helpref{wxDC}{wxdc} to draw on, only this device
+          context should be used for drawing. It is not necessary to restore
+          pens and brushes for it on function exit but, on the other hand, you
+          shouldn't assume that it is in any specific state on function entry
+          neither: the rendering functions should always prepare it.
+    \item \arg{rect} the bounding rectangle for the element to be drawn
+    \item \arg{flags} the optional flags (none by default) which can be a
+          combination of the \texttt{wxCONTROL\_XXX} constants below
+\end{itemize}
+
+\wxheading{Constants}
+
+The following rendering flags are defined:
+\begin{verbatim}
+enum
+{
+    wxCONTROL_DISABLED   = 0x00000001,  // control is disabled
+    wxCONTROL_FOCUSED    = 0x00000002,  // currently has keyboard focus
+    wxCONTROL_PRESSED    = 0x00000004,  // (button) is pressed
+    wxCONTROL_ISDEFAULT  = 0x00000008,  // only applies to the buttons
+    wxCONTROL_ISSUBMENU  = wxCONTROL_ISDEFAULT, // only for menu items
+    wxCONTROL_EXPANDED   = wxCONTROL_ISDEFAULT, // only for the tree items
+    wxCONTROL_CURRENT    = 0x00000010,  // mouse is currently over the control
+    wxCONTROL_SELECTED   = 0x00000020,  // selected item in e.g. listbox
+    wxCONTROL_CHECKED    = 0x00000040,  // (check/radio button) is checked
+    wxCONTROL_CHECKABLE  = 0x00000080   // (menu) item can be checked
+};
+\end{verbatim}
+
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/renderer.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxRendererNative::\destruct{wxRendererNative}}\label{wxrenderernativedtor}
+
+\func{}{\destruct{wxRendererNative}}{\void}
+
+Virtual destructor as for any base class.
+
+
+\membersection{wxRendererNative::DrawHeaderButton}\label{wxrenderernativedrawheaderbutton}
+
+\func{void}{DrawHeaderButton}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}}
+
+Draw the header control button (used by \helpref{wxListCtrl}{wxlistctrl}).
+
+
+\membersection{wxRendererNative::DrawSplitterBorder}\label{wxrenderernativedrawsplitterborder}
+
+\func{void}{DrawSplitterBorder}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}}
+
+Draw the border for sash window: this border must be such that the sash
+drawn by \helpref{DrawSash}{wxrenderernativedrawsplittersash} blends into it
+well.
+
+
+\membersection{wxRendererNative::DrawSplitterSash}\label{wxrenderernativedrawsplittersash}
+
+\func{void}{DrawSplitterSash}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxSize\& }{size}, \param{wxCoord }{position}, \param{wxOrientation }{orient}, \param{int }{flags = 0}}
+
+Draw a sash. The \arg{orient} parameter defines whether the sash should be
+vertical or horizontal and how should the \arg{position} be interpreted.
+
+
+\membersection{wxRendererNative::DrawTreeItemButton}\label{wxrenderernativedrawtreeitembutton}
+
+\func{void}{DrawTreeItemButton}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}}
+
+Draw the expanded/collapsed icon for a tree control item. To draw an expanded
+button the \arg{flags} parameter must contain {\tt wxCONTROL\_EXPANDED} bit.
+
+
+\membersection{wxRendererNative::Get}\label{wxrenderernativeget}
+
+\func{wxRendererNative\&}{Get}{\void}
+
+Return the currently used renderer.
+
+
+\membersection{wxRendererNative::GetDefault}\label{wxrenderernativegetdefault}
+
+\func{wxRendererNative\&}{GetDefault}{\void}
+
+Return the default (native) implementation for this platform -- this is also
+the one used by default but this may be changed by calling 
+\helpref{Set}{wxrenderernativeset} in which case the return value of this
+method may be different from the return value of \helpref{Get}{wxrenderernativeget}.
+
+
+\membersection{wxRendererNative::GetGeneric}\label{wxrenderernativegetgeneric}
+
+\func{wxRendererNative\&}{GetGeneric}{\void}
+
+Return the generic implementation of the renderer. Under some platforms, this
+is the default renderer implementation, others have platform-specific default
+renderer which can be retrieved by calling \helpref{GetDefault}{wxrenderernativegetdefault}.
+
+
+\membersection{wxRendererNative::GetSplitterParams}\label{wxrenderernativegetsplitterparams}
+
+\func{wxSplitterRenderParams}{GetSplitterParams}{\param{const wxWindow* }{win}}
+
+Get the splitter parameters, see 
+\helpref{wxSplitterRenderParams}{wxsplitterrenderparams}.
+
+
+\membersection{wxRendererNative::GetVersion}\label{wxrenderernativegetversion}
+
+\constfunc{wxRendererVersion}{GetVersion}{\void}
+
+This function is used for version checking: \helpref{Load}{wxrenderernativeload} 
+refuses to load any shared libraries implementing an older or incompatible
+version.
+
+The implementation of this method is always the same in all renderers (simply
+construct \helpref{wxRendererVersion}{wxrendererversion} using the 
+{\tt wxRendererVersion::Current\_XXX} values), but it has to be in the derived,
+not base, class, to detect mismatches between the renderers versions and so you
+have to implement it anew in all renderers.
+
+
+\membersection{wxRendererNative::Load}\label{wxrenderernativeload}
+
+\func{wxRendererNative*}{Load}{\param{const wxString\& }{name}}
+
+Load the renderer from the specified DLL, the returned pointer must be
+deleted by caller if not {\tt NULL} when it is not used any more.
+
+The \arg{name} should be just the base name of the renderer and not the full
+name of the DLL file which is constructed differently (using 
+\helpref{wxDynamicLibrary::CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}) 
+on different systems.
+
+
+\membersection{wxRendererNative::Set}\label{wxrenderernativeset}
+
+\func{wxRendererNative*}{Set}{\param{wxRendererNative* }{renderer}}
+
+Set the renderer to use, passing {\tt NULL} reverts to using the default
+renderer (the global renderer must always exist).
+
+Return the previous renderer used with Set() or {\tt NULL} if none.
 
diff --git a/docs/latex/wx/rendver.tex b/docs/latex/wx/rendver.tex
new file mode 100644
index 0000000000..e7975c522f
--- /dev/null
+++ b/docs/latex/wx/rendver.tex
@@ -0,0 +1,63 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        rendver.tex
+%% Purpose:     wxRendererVersion documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     11.08.03
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxRendererVersion}}\label{wxrendererversion}
+
+This simple struct represents the \helpref{wxRendererNative}{wxrenderernative} 
+interface version and is only used as the return value of 
+\helpref{wxRendererNative::GetVersion}{wxrenderernativegetversion}.
+
+The version has two components: the version itself and the age. If the main
+program and the renderer have different versions they are never compatible with
+each other because the version is only changed when an existing virtual
+function is modified or removed. The age, on the other hand, is incremented
+each time a new virtual method is added and so, at least for the compilers
+using a common C++ object model, the calling program is compatible with any
+renderer which has the age greater or equal to its age. This verification is
+done by \helpref{IsCompatible}{wxrenderernativeiscompatible} method.
+
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/renderer.h>
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxRendererVersion::IsCompatible}\label{wxrenderernativeiscompatible}
+
+\func{static bool}{IsCompatible}{\param{const wxRendererVersion\& }{ver}}
+
+Checks if the main program is compatible with the renderer having the version 
+\arg{ver}, returns \true if it is and \false otherwise.
+
+This method is used by 
+\helpref{wxRendererNative::Load}{wxrenderernativeload} to determine whether a
+renderer can be used.
+
+
+\membersection{wxRendererVersion::version}
+
+\member{const int}{version}
+
+The version component.
+
+
+\membersection{wxRendererVersion::age}
+
+\member{const int}{age}
+
+The age component.
+
diff --git a/docs/latex/wx/splitpar.tex b/docs/latex/wx/splitpar.tex
new file mode 100644
index 0000000000..f82a9f0a27
--- /dev/null
+++ b/docs/latex/wx/splitpar.tex
@@ -0,0 +1,48 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        splitpar.tex
+%% Purpose:     wxSplitterRenderParams documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     11.08.03
+%% RCS-ID:      $Id$
+%% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\section{\class{wxSplitterRenderParams}}\label{wxsplitterrenderparams}
+
+This is just a simple {\tt struct} used as a return value of 
+\helpref{wxRendererNative::GetSplitterParams}{wxrenderernativegetsplitterparams}.
+
+It doesn't have any methods and all of its fields are constant and so can be
+only examined but not modified.
+
+\wxheading{Include files}
+
+<wx/renderer.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxEvent::widthSash}
+
+\member{const wxCoord}{widthSash}
+
+The width of the splitter sash.
+
+
+\membersection{wxSplitterRenderParams::border}
+
+\member{const wxCoord}{border}
+
+The width of the border drawn by the splitter inside it, may be $0$.
+
+
+\membersection{wxSplitterRenderParams::isHotSensitive}
+
+\member{const bool}{isHotSensitive}
+
+\true if the sash changes appearance when the mouse passes over it, \false
+otherwise.
+
+
-- 
2.50.0

