1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxRendererNative
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @anchor wxCONTROL_FLAGS
12 The following rendering flags are defined for wxRendererNative:
16 /** Control is disabled. */
17 wxCONTROL_DISABLED
= 0x00000001,
19 /** Currently has keyboard focus. */
20 wxCONTROL_FOCUSED
= 0x00000002,
22 /** (Button) is pressed. */
23 wxCONTROL_PRESSED
= 0x00000004,
25 /** Control-specific bit. */
26 wxCONTROL_SPECIAL
= 0x00000008,
28 /** Only for the buttons. */
29 wxCONTROL_ISDEFAULT
= wxCONTROL_SPECIAL
,
31 /** Only for the menu items. */
32 wxCONTROL_ISSUBMENU
= wxCONTROL_SPECIAL
,
34 /** Only for the tree items. */
35 wxCONTROL_EXPANDED
= wxCONTROL_SPECIAL
,
37 /** Only for the status bar panes. */
38 wxCONTROL_SIZEGRIP
= wxCONTROL_SPECIAL
,
40 /** Checkboxes only: flat border. */
41 wxCONTROL_FLAT
= wxCONTROL_SPECIAL
,
43 /** Mouse is currently over the control. */
44 wxCONTROL_CURRENT
= 0x00000010,
46 /** Selected item in e.g. listbox. */
47 wxCONTROL_SELECTED
= 0x00000020,
49 /** (Check/radio button) is checked. */
50 wxCONTROL_CHECKED
= 0x00000040,
52 /** (Menu) item can be checked. */
53 wxCONTROL_CHECKABLE
= 0x00000080,
55 /** (Check) undetermined state. */
56 wxCONTROL_UNDETERMINED
= wxCONTROL_CHECKABLE
60 @struct wxSplitterRenderParams
62 This is just a simple @c struct used as a return value of
63 wxRendererNative::GetSplitterParams().
65 It doesn't have any methods and all of its fields are constant, so they can
66 only be examined but not modified.
71 struct wxSplitterRenderParams
74 The only way to initialize this struct is by using this ctor.
76 wxSplitterRenderParams(wxCoord widthSash_
, wxCoord border_
, bool isSens_
);
79 The width of the border drawn by the splitter inside it, may be 0.
84 @true if the sash changes appearance when the mouse passes over it, @false
87 const bool isHotSensitive
;
90 The width of the splitter sash.
92 const wxCoord widthSash
;
96 @struct wxHeaderButtonParams
98 This @c struct can optionally be used with
99 wxRendererNative::DrawHeaderButton() to specify custom values used to draw
100 the text or bitmap label.
105 struct wxHeaderButtonParams
107 wxHeaderButtonParams();
109 wxColour m_arrowColour
;
110 wxColour m_selectionColour
;
111 wxString m_labelText
;
113 wxColour m_labelColour
;
114 wxBitmap m_labelBitmap
;
115 int m_labelAlignment
;
119 Used to specify the type of sort arrow used with
120 wxRendererNative::DrawHeaderButton().
122 enum wxHeaderSortIconType
124 wxHDR_SORT_ICON_NONE
, ///< Don't draw a sort arrow.
125 wxHDR_SORT_ICON_UP
, ///< Draw a sort arrow icon pointing up.
126 wxHDR_SORT_ICON_DOWN
///< Draw a sort arrow icon pointing down.
132 @class wxDelegateRendererNative
134 wxDelegateRendererNative allows reuse of renderers code by forwarding all the
135 wxRendererNative methods to the given object and
136 thus allowing you to only modify some of its methods -- without having to
137 reimplement all of them.
139 Note that the "normal", inheritance-based approach, doesn't work with the
140 renderers as it is impossible to derive from a class unknown at compile-time
141 and the renderer is only chosen at run-time. So suppose that you want to only
142 add something to the drawing of the tree control buttons but leave all the
143 other methods unchanged -- the only way to do it, considering that the renderer
144 class which you want to customize might not even be written yet when you write
145 your code (it could be written later and loaded from a DLL during run-time), is
148 Except for the constructor, it has exactly the same methods as
149 wxRendererNative and their implementation is
150 trivial: they are simply forwarded to the real renderer. Note that the "real"
151 renderer may, in turn, be a wxDelegateRendererNative as well and that there may
152 be arbitrarily many levels like this -- but at the end of the chain there must
153 be a real renderer which does the drawing.
158 @see wxRendererNative
160 class wxDelegateRendererNative
: public wxRendererNative
164 The default constructor does the same thing as the other one except that it
165 uses the @ref wxRendererNative::GetGeneric() "generic renderer" instead of the
166 user-specified @a rendererNative.
168 In any case, this sets up the delegate renderer object to follow all calls to
169 the specified real renderer.
171 wxDelegateRendererNative();
173 This constructor uses the user-specified @a rendererNative to set up the delegate
174 renderer object to follow all calls to the specified real renderer.
177 This object does not take ownership of (i.e. won't delete) @a rendererNative.
179 wxDelegateRendererNative(wxRendererNative
& rendererNative
);
181 // The rest of these functions inherit the documentation from wxRendererNative
183 virtual int DrawHeaderButton(wxWindow
*win
, wxDC
& dc
,
184 const wxRect
& rect
, int flags
= 0,
185 wxHeaderSortIconType sortArrow
= wxHDR_SORT_ICON_NONE
,
186 wxHeaderButtonParams
* params
= NULL
);
188 virtual int DrawHeaderButtonContents(wxWindow
*win
, wxDC
& dc
,
189 const wxRect
& rect
, int flags
= 0,
190 wxHeaderSortIconType sortArrow
= wxHDR_SORT_ICON_NONE
,
191 wxHeaderButtonParams
* params
= NULL
);
193 virtual int GetHeaderButtonHeight(wxWindow
*win
);
195 virtual void DrawTreeItemButton(wxWindow
*win
, wxDC
& dc
,
196 const wxRect
& rect
, int flags
= 0);
198 virtual void DrawSplitterBorder(wxWindow
*win
, wxDC
& dc
,
199 const wxRect
& rect
, int flags
= 0);
201 virtual void DrawSplitterSash(wxWindow
*win
, wxDC
& dc
,
202 const wxSize
& size
, wxCoord position
,
203 wxOrientation orient
, int flags
= 0);
205 virtual void DrawComboBoxDropButton(wxWindow
*win
, wxDC
& dc
,
206 const wxRect
& rect
, int flags
= 0);
208 virtual void DrawDropArrow(wxWindow
*win
, wxDC
& dc
,
209 const wxRect
& rect
, int flags
= 0);
211 virtual void DrawCheckBox(wxWindow
*win
, wxDC
& dc
,
212 const wxRect
& rect
, int flags
= 0 );
214 virtual wxSize
GetCheckBoxSize(wxWindow
*win
);
216 virtual void DrawPushButton(wxWindow
*win
, wxDC
& dc
,
217 const wxRect
& rect
, int flags
= 0 );
219 virtual void DrawItemSelectionRect(wxWindow
*win
, wxDC
& dc
,
220 const wxRect
& rect
, int flags
= 0 );
222 virtual void DrawFocusRect(wxWindow
* win
, wxDC
& dc
,
223 const wxRect
& rect
, int flags
= 0);
225 virtual wxSplitterRenderParams
GetSplitterParams(const wxWindow
*win
);
227 virtual wxRendererVersion
GetVersion() const;
233 @class wxRendererNative
235 First, a brief introduction to wxRendererNative and why it is needed.
237 Usually wxWidgets uses the underlying low level GUI system to draw all the
238 controls - this is what we mean when we say that it is a "native" framework.
239 However not all controls exist under all (or even any) platforms and in this
240 case wxWidgets provides a default, generic, implementation of them written in
243 These controls don't have the native appearance if only the standard
244 line drawing and other graphics primitives are used, because the native
245 appearance is different under different platforms while the lines are always
246 drawn in the same way.
248 This is why we have renderers: wxRendererNative is a class which virtualizes the
249 drawing, i.e. it abstracts the drawing operations and allows you to draw say, a
250 button, without caring about exactly how this is done. Of course, as we
251 can draw the button differently in different renderers, this also allows us to
252 emulate the native look and feel.
254 So the renderers work by exposing a large set of high-level drawing functions
255 which are used by the generic controls. There is always a default global
256 renderer but it may be changed or extended by the user, see
257 @ref page_samples_render.
259 All drawing functions take some standard parameters:
261 @li @a win - The window being drawn. It is normally not used and when
262 it is it should only be used as a generic wxWindow
263 (in order to get its low level handle, for example), but you should
264 not assume that it is of some given type as the same renderer
265 function may be reused for drawing different kinds of control.
266 @li @a dc - The wxDC to draw on. Only this device
267 context should be used for drawing. It is not necessary to restore
268 pens and brushes for it on function exit but, on the other hand, you
269 shouldn't assume that it is in any specific state on function entry:
270 the rendering functions should always prepare it.
271 @li @a rect - The bounding rectangle for the element to be drawn.
272 @li @a flags - The optional flags (none by default) which can be a
273 combination of the @ref wxCONTROL_FLAGS.
275 Note that each drawing function restores the wxDC attributes if
276 it changes them, so it is safe to assume that the same pen, brush and colours
277 that were active before the call to this function are still in effect after it.
282 class wxRendererNative
286 Virtual destructor as for any base class.
288 virtual ~wxRendererNative();
293 @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or
294 @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS.
296 virtual void DrawCheckBox(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
300 Draw a button like the one used by wxComboBox to show a
301 drop down window. The usual appearance is a downwards pointing arrow.
303 @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
304 see @ref wxCONTROL_FLAGS.
306 virtual void DrawComboBoxDropButton(wxWindow
* win
, wxDC
& dc
,
307 const wxRect
& rect
, int flags
= 0) = 0;
310 Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
311 have transparent background.
313 @a rect is not entirely filled by the arrow. Instead, you should use bounding
314 rectangle of a drop down button which arrow matches the size you need.
316 @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
317 see @ref wxCONTROL_FLAGS.
319 virtual void DrawDropArrow(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
323 Draw a focus rectangle using the specified rectangle.
326 The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
327 see @ref wxCONTROL_FLAGS.
329 virtual void DrawFocusRect(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
333 Draw the header control button (used, for example, by wxListCtrl).
335 Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
336 @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
339 The optimal width to contain the the unabreviated label text or
340 bitmap, the sort arrow if present, and internal margins.
342 virtual int DrawHeaderButton(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
344 wxHeaderSortIconType sortArrow
= wxHDR_SORT_ICON_NONE
, wxHeaderButtonParams
* params
= NULL
) = 0;
347 Draw the contents of a header control button (label, sort arrows,
348 etc.). This function is normally only called by DrawHeaderButton().
350 Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
351 @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
354 The optimal width to contain the the unabreviated label text or
355 bitmap, the sort arrow if present, and internal margins.
357 virtual int DrawHeaderButtonContents(wxWindow
* win
, wxDC
& dc
,
358 const wxRect
& rect
, int flags
= 0,
359 wxHeaderSortIconType sortArrow
= wxHDR_SORT_ICON_NONE
, wxHeaderButtonParams
* params
= NULL
) = 0;
362 Draw a selection rectangle underneath the text as used e.g. in a
365 The supported @a flags are @c wxCONTROL_SELECTED for items
366 which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT
367 for the item that has the focus (often a dotted line around the item's text).
368 @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus
369 (othewise the the selection rectangle is e.g. often grey and not blue).
370 This may be ignored by the renderer or deduced by the code directly from
373 virtual void DrawItemSelectionRect(wxWindow
* win
, wxDC
& dc
,
374 const wxRect
& rect
, int flags
= 0) = 0;
377 Draw a blank push button that looks very similar to wxButton.
379 @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or
380 @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS.
382 virtual void DrawPushButton(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
386 Draw the border for sash window: this border must be such that the sash
387 drawn by DrawSplitterSash() blends into it well.
389 virtual void DrawSplitterBorder(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
393 Draw a sash. The @a orient parameter defines whether the sash should be
394 vertical or horizontal and how the @a position should be interpreted.
396 virtual void DrawSplitterSash(wxWindow
* win
, wxDC
& dc
, const wxSize
& size
,
397 wxCoord position
, wxOrientation orient
,
401 Draw the expanded/collapsed icon for a tree control item.
403 To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit,
404 see @ref wxCONTROL_FLAGS.
406 virtual void DrawTreeItemButton(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
,
410 Draw a native wxChoice
412 virtual void DrawChoice(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
, int flags
= 0) = 0;
415 Draw a native wxComboBox
417 virtual void DrawComboBox(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
, int flags
= 0) = 0;
420 Draw a native wxTextCtrl frame
422 virtual void DrawTextCtrl(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
, int flags
= 0) = 0;
425 Draw a native wxRadioButton bitmap.
427 virtual void DrawRadioBitmap(wxWindow
* win
, wxDC
& dc
, const wxRect
& rect
, int flags
= 0) = 0;
430 Return the currently used renderer.
432 static wxRendererNative
& Get();
435 Return the default (native) implementation for this platform -- this is also
436 the one used by default but this may be changed by calling
437 Set() in which case the return value of this
438 method may be different from the return value of Get().
440 static wxRendererNative
& GetDefault();
443 Return the generic implementation of the renderer. Under some platforms, this
444 is the default renderer implementation, others have platform-specific default
445 renderer which can be retrieved by calling GetDefault().
447 static wxRendererNative
& GetGeneric();
450 Returns the size of a check box.
451 The @a win parameter is not used currently and can be @NULL.
453 virtual wxSize
GetCheckBoxSize(wxWindow
* win
) = 0;
456 Returns the height of a header button, either a fixed platform height if
457 available, or a generic height based on the @a win window's font.
459 virtual int GetHeaderButtonHeight(wxWindow
* win
) = 0;
462 Get the splitter parameters, see wxSplitterRenderParams.
463 The @a win parameter should be a wxSplitterWindow.
465 virtual wxSplitterRenderParams
GetSplitterParams(const wxWindow
* win
) = 0;
468 This function is used for version checking: Load()
469 refuses to load any shared libraries implementing an older or incompatible
473 The implementation of this method is always the same in all renderers (simply
474 construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
475 but it has to be in the derived, not base, class, to detect mismatches between
476 the renderers versions and so you have to implement it anew in all renderers.
478 virtual wxRendererVersion
GetVersion() const = 0;
481 Load the renderer from the specified DLL, the returned pointer must be
482 deleted by caller if not @NULL when it is not used any more.
484 The @a name should be just the base name of the renderer and not the full
485 name of the DLL file which is constructed differently (using
486 wxDynamicLibrary::CanonicalizePluginName())
487 on different systems.
489 static wxRendererNative
* Load(const wxString
& name
);
492 Set the renderer to use, passing @NULL reverts to using the default
493 renderer (the global renderer must always exist).
495 Return the previous renderer used with Set() or @NULL if none.
497 static wxRendererNative
* Set(wxRendererNative
* renderer
);
503 @struct wxRendererVersion
505 This simple struct represents the wxRendererNative
506 interface version and is only used as the return value of
507 wxRendererNative::GetVersion().
509 The version has two components: the version itself and the age. If the main
510 program and the renderer have different versions they are never compatible with
511 each other because the version is only changed when an existing virtual
512 function is modified or removed. The age, on the other hand, is incremented
513 each time a new virtual method is added and so, at least for the compilers
514 using a common C++ object model, the calling program is compatible with any
515 renderer which has the age greater or equal to its age. This verification is
516 done by IsCompatible() method.
521 struct wxRendererVersion
524 Checks if the main program is compatible with the renderer having the version
525 @e ver, returns @true if it is and @false otherwise.
527 This method is used by wxRendererNative::Load() to determine whether a
528 renderer can be used.
530 static bool IsCompatible(const wxRendererVersion
& ver
);
538 The version component.