| 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 2 | %% Name: renderer.tex |
| 3 | %% Purpose: wxRenderer and wxRendererNative documentation |
| 4 | %% Author: Vadim Zeitlin |
| 5 | %% Modified by: |
| 6 | %% Created: 06.08.03 |
| 7 | %% RCS-ID: $Id$ |
| 8 | %% Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org> |
| 9 | %% License: wxWindows license |
| 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 11 | |
| 12 | \section{\class{wxRendererNative}}\label{wxrenderernative} |
| 13 | |
| 14 | First, a brief introduction to wxRenderer and why it is needed. |
| 15 | |
| 16 | Usually wxWidgets uses the underlying low level GUI system to draw all the |
| 17 | controls - this is what we mean when we say that it is a ``native'' framework. |
| 18 | However not all controls exist under all (or even any) platforms and in this |
| 19 | case wxWidgets provides a default, generic, implementation of them written in |
| 20 | wxWidgets itself. |
| 21 | |
| 22 | These controls don't have the native appearance if only the tandard |
| 23 | line drawing and other graphics primitives are used, because the native |
| 24 | appearance is different under different platforms while the lines are always |
| 25 | drawn in the same way. |
| 26 | |
| 27 | This is why we have renderers: wxRenderer is a class which virtualizes the |
| 28 | drawing, i.e. it abstracts the drawing operations and allows you to draw say, a |
| 29 | button, without caring about exactly how this is done. Of course, as we |
| 30 | can draw the button differently in different renderers, this also allows us to |
| 31 | emulate the native look and feel. |
| 32 | |
| 33 | So the renderers work by exposing a large set of high-level drawing functions |
| 34 | which are used by the generic controls. There is always a default global |
| 35 | renderer but it may be changed or extended by the user, see |
| 36 | \helpref{Render sample}{samplerender}. |
| 37 | |
| 38 | All drawing functions take some standard parameters: |
| 39 | \begin{itemize} |
| 40 | \item \arg{win} is the window being drawn. It is normally not used and when |
| 41 | it is it should only be used as a generic \helpref{wxWindow}{wxwindow} |
| 42 | (in order to get its low level handle, for example), but you should |
| 43 | \emph{not} assume that it is of some given type as the same renderer |
| 44 | function may be reused for drawing different kinds of control. |
| 45 | \item \arg{dc} is the \helpref{wxDC}{wxdc} to draw on. Only this device |
| 46 | context should be used for drawing. It is not necessary to restore |
| 47 | pens and brushes for it on function exit but, on the other hand, you |
| 48 | shouldn't assume that it is in any specific state on function entry: |
| 49 | the rendering functions should always prepare it. |
| 50 | \item \arg{rect} the bounding rectangle for the element to be drawn. |
| 51 | \item \arg{flags} the optional flags (none by default) which can be a |
| 52 | combination of the \texttt{wxCONTROL\_XXX} constants below. |
| 53 | \end{itemize} |
| 54 | |
| 55 | Note that each drawing function restores the \helpref{wxDC}{wxdc} attributes if |
| 56 | it changes them, so it is safe to assume that the same pen, brush and colours |
| 57 | that were active before the call to this function are still in effect after it. |
| 58 | |
| 59 | |
| 60 | \wxheading{Constants} |
| 61 | |
| 62 | The following rendering flags are defined: |
| 63 | |
| 64 | \begin{verbatim} |
| 65 | enum |
| 66 | { |
| 67 | wxCONTROL_DISABLED = 0x00000001, // control is disabled |
| 68 | wxCONTROL_FOCUSED = 0x00000002, // currently has keyboard focus |
| 69 | wxCONTROL_PRESSED = 0x00000004, // (button) is pressed |
| 70 | wxCONTROL_ISDEFAULT = 0x00000008, // only applies to the buttons |
| 71 | wxCONTROL_ISSUBMENU = wxCONTROL_ISDEFAULT, // only for menu items |
| 72 | wxCONTROL_EXPANDED = wxCONTROL_ISDEFAULT, // only for the tree items |
| 73 | wxCONTROL_CURRENT = 0x00000010, // mouse is currently over the control |
| 74 | wxCONTROL_SELECTED = 0x00000020, // selected item in e.g. listbox |
| 75 | wxCONTROL_CHECKED = 0x00000040, // (check/radio button) is checked |
| 76 | wxCONTROL_CHECKABLE = 0x00000080, // (menu) item can be checked |
| 77 | wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE // (check) undetermined state |
| 78 | }; |
| 79 | \end{verbatim} |
| 80 | |
| 81 | \wxheading{Derived from} |
| 82 | |
| 83 | No base class |
| 84 | |
| 85 | \wxheading{Include files} |
| 86 | |
| 87 | <wx/renderer.h> |
| 88 | |
| 89 | |
| 90 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 91 | |
| 92 | |
| 93 | \membersection{wxRendererNative::\destruct{wxRendererNative}}\label{wxrenderernativedtor} |
| 94 | |
| 95 | \func{}{\destruct{wxRendererNative}}{\void} |
| 96 | |
| 97 | Virtual destructor as for any base class. |
| 98 | |
| 99 | |
| 100 | \membersection{wxRendererNative::DrawCheckBox}\label{wxrenderernativedrawcheckbox} |
| 101 | |
| 102 | \func{void}{DrawCheckBox}{\param{wxWindow *}{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags}} |
| 103 | |
| 104 | Draw a check box (used by wxDataViewCtrl). |
| 105 | |
| 106 | \arg{flags} may have the \texttt{wxCONTROL\_CHECKED}, \texttt{wxCONTROL\_CURRENT} or |
| 107 | \texttt{wxCONTROL\_UNDETERMINED} bit set. |
| 108 | |
| 109 | |
| 110 | \membersection{wxRendererNative::DrawComboBoxDropButton}\label{wxrenderernativedrawcomboboxdropbutton} |
| 111 | |
| 112 | \func{void}{DrawComboBoxDropButton}{\param{wxWindow *}{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags}} |
| 113 | |
| 114 | Draw a button like the one used by \helpref{wxComboBox}{wxcombobox} to show a |
| 115 | drop down window. The usual appearance is a downwards pointing arrow. |
| 116 | |
| 117 | \arg{flags} may have the \texttt{wxCONTROL\_PRESSED} or \texttt{wxCONTROL\_CURRENT} bit set. |
| 118 | |
| 119 | |
| 120 | \membersection{wxRendererNative::DrawDropArrow}\label{wxrenderernativedrawdroparrow} |
| 121 | |
| 122 | \func{void}{DrawDropArrow}{\param{wxWindow *}{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags}} |
| 123 | |
| 124 | Draw a drop down arrow that is suitable for use outside a combo box. Arrow will have |
| 125 | transparent background. |
| 126 | |
| 127 | \arg{rect} is not entirely filled by the arrow. Instead, you should use bounding |
| 128 | rectangle of a drop down button which arrow matches the size you need. |
| 129 | \arg{flags} may have the \texttt{wxCONTROL\_PRESSED} or \texttt{wxCONTROL\_CURRENT} bit set. |
| 130 | |
| 131 | |
| 132 | \membersection{wxRendererNative::DrawHeaderButton}\label{wxrenderernativedrawheaderbutton} |
| 133 | |
| 134 | \func{void}{DrawHeaderButton}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}, \param{wxHeaderSortIconType }{sortArrow = wxHDR\_SORT\_ICON\_NONE}, \param{wxHeaderButtonParams* }{params = NULL}} |
| 135 | |
| 136 | Draw the header control button (used, for example, by |
| 137 | \helpref{wxListCtrl}{wxlistctrl}). Depending on platforms the |
| 138 | \arg{flags} parameter may support the \texttt{wxCONTROL\_SELECTED} |
| 139 | \texttt{wxCONTROL\_DISABLED} and \texttt{wxCONTROL\_CURRENT} bits. |
| 140 | The \arg{sortArrow} parameter can be one of |
| 141 | \texttt{wxHDR\_SORT\_ICON\_NONE}, \texttt{wxHDR\_SORT\_ICON\_UP}, or |
| 142 | \texttt{wxHDR\_SORT\_ICON\_DOWN}. Additional values controlling the |
| 143 | drawing of a text or bitmap label can be passed in \arg{params}. |
| 144 | |
| 145 | |
| 146 | \membersection{wxRendererNative::DrawPushButton}\label{wxrenderernativedrawpushbutton} |
| 147 | |
| 148 | \func{void}{DrawPushButton}{\param{wxWindow *}{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags}} |
| 149 | |
| 150 | Draw a blank push button that looks very similar to \helpref{wxButton}{wxbutton}. |
| 151 | |
| 152 | \arg{flags} may have the \texttt{wxCONTROL\_PRESSED}, \texttt{wxCONTROL\_CURRENT} or |
| 153 | \texttt{wxCONTROL\_ISDEFAULT} bit set. |
| 154 | |
| 155 | |
| 156 | \membersection{wxRendererNative::DrawSplitterBorder}\label{wxrenderernativedrawsplitterborder} |
| 157 | |
| 158 | \func{void}{DrawSplitterBorder}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}} |
| 159 | |
| 160 | Draw the border for sash window: this border must be such that the sash |
| 161 | drawn by \helpref{DrawSash}{wxrenderernativedrawsplittersash} blends into it |
| 162 | well. |
| 163 | |
| 164 | |
| 165 | \membersection{wxRendererNative::DrawSplitterSash}\label{wxrenderernativedrawsplittersash} |
| 166 | |
| 167 | \func{void}{DrawSplitterSash}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxSize\& }{size}, \param{wxCoord }{position}, \param{wxOrientation }{orient}, \param{int }{flags = 0}} |
| 168 | |
| 169 | Draw a sash. The \arg{orient} parameter defines whether the sash should be |
| 170 | vertical or horizontal and how the \arg{position} should be interpreted. |
| 171 | |
| 172 | |
| 173 | \membersection{wxRendererNative::DrawTreeItemButton}\label{wxrenderernativedrawtreeitembutton} |
| 174 | |
| 175 | \func{void}{DrawTreeItemButton}{\param{wxWindow* }{win}, \param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{flags = 0}} |
| 176 | |
| 177 | Draw the expanded/collapsed icon for a tree control item. To draw an expanded |
| 178 | button the \arg{flags} parameter must contain {\tt wxCONTROL\_EXPANDED} bit. |
| 179 | |
| 180 | |
| 181 | \membersection{wxRendererNative::Get}\label{wxrenderernativeget} |
| 182 | |
| 183 | \func{wxRendererNative\&}{Get}{\void} |
| 184 | |
| 185 | Return the currently used renderer. |
| 186 | |
| 187 | |
| 188 | \membersection{wxRendererNative::GetDefault}\label{wxrenderernativegetdefault} |
| 189 | |
| 190 | \func{wxRendererNative\&}{GetDefault}{\void} |
| 191 | |
| 192 | Return the default (native) implementation for this platform -- this is also |
| 193 | the one used by default but this may be changed by calling |
| 194 | \helpref{Set}{wxrenderernativeset} in which case the return value of this |
| 195 | method may be different from the return value of \helpref{Get}{wxrenderernativeget}. |
| 196 | |
| 197 | |
| 198 | \membersection{wxRendererNative::GetGeneric}\label{wxrenderernativegetgeneric} |
| 199 | |
| 200 | \func{wxRendererNative\&}{GetGeneric}{\void} |
| 201 | |
| 202 | Return the generic implementation of the renderer. Under some platforms, this |
| 203 | is the default renderer implementation, others have platform-specific default |
| 204 | renderer which can be retrieved by calling \helpref{GetDefault}{wxrenderernativegetdefault}. |
| 205 | |
| 206 | |
| 207 | \membersection{wxRendererNative::GetHeaderButtonHeight}\label{wxrenderernativegetheaderbuttonheight} |
| 208 | |
| 209 | \func{int}{GetHeaderButtonHeight}{\param{const wxWindow* }{win}} |
| 210 | |
| 211 | Returns the height of a header button, either a fixed platform height if available, or a |
| 212 | generic height based on the window's font. |
| 213 | |
| 214 | |
| 215 | \membersection{wxRendererNative::GetSplitterParams}\label{wxrenderernativegetsplitterparams} |
| 216 | |
| 217 | \func{wxSplitterRenderParams}{GetSplitterParams}{\param{const wxWindow* }{win}} |
| 218 | |
| 219 | Get the splitter parameters, see |
| 220 | \helpref{wxSplitterRenderParams}{wxsplitterrenderparams}. |
| 221 | |
| 222 | |
| 223 | \membersection{wxRendererNative::GetVersion}\label{wxrenderernativegetversion} |
| 224 | |
| 225 | \constfunc{wxRendererVersion}{GetVersion}{\void} |
| 226 | |
| 227 | This function is used for version checking: \helpref{Load}{wxrenderernativeload} |
| 228 | refuses to load any shared libraries implementing an older or incompatible |
| 229 | version. |
| 230 | |
| 231 | The implementation of this method is always the same in all renderers (simply |
| 232 | construct \helpref{wxRendererVersion}{wxrendererversion} using the |
| 233 | {\tt wxRendererVersion::Current\_XXX} values), but it has to be in the derived, |
| 234 | not base, class, to detect mismatches between the renderers versions and so you |
| 235 | have to implement it anew in all renderers. |
| 236 | |
| 237 | |
| 238 | \membersection{wxRendererNative::Load}\label{wxrenderernativeload} |
| 239 | |
| 240 | \func{wxRendererNative*}{Load}{\param{const wxString\& }{name}} |
| 241 | |
| 242 | Load the renderer from the specified DLL, the returned pointer must be |
| 243 | deleted by caller if not {\tt NULL} when it is not used any more. |
| 244 | |
| 245 | The \arg{name} should be just the base name of the renderer and not the full |
| 246 | name of the DLL file which is constructed differently (using |
| 247 | \helpref{wxDynamicLibrary::CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname}) |
| 248 | on different systems. |
| 249 | |
| 250 | |
| 251 | \membersection{wxRendererNative::Set}\label{wxrenderernativeset} |
| 252 | |
| 253 | \func{wxRendererNative*}{Set}{\param{wxRendererNative* }{renderer}} |
| 254 | |
| 255 | Set the renderer to use, passing {\tt NULL} reverts to using the default |
| 256 | renderer (the global renderer must always exist). |
| 257 | |
| 258 | Return the previous renderer used with Set() or {\tt NULL} if none. |
| 259 | |