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