From bc51e42e8b8cdf53ef8e24ab9568236329420778 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin 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 +%% 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} + + + + +\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} + + + + +\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 +%% 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} + + + + +\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 +%% 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} + + + +\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.45.2