interface/wx/renderer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        renderer.h
   3 // Purpose:     interface of wxRendererNative
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @anchor wxCONTROL_FLAGS
  11
  12     The following rendering flags are defined for wxRendererNative:
  13 */
  14 enum
  15 {
  16     /** Control is disabled. */
  17     wxCONTROL_DISABLED   = 0x00000001,
  18
  19     /** Currently has keyboard focus. */
  20     wxCONTROL_FOCUSED    = 0x00000002,
  21
  22     /** (Button) is pressed. */
  23     wxCONTROL_PRESSED    = 0x00000004,
  24
  25     /** Control-specific bit. */
  26     wxCONTROL_SPECIAL    = 0x00000008,
  27
  28     /** Only for the buttons. */
  29     wxCONTROL_ISDEFAULT  = wxCONTROL_SPECIAL,
  30
  31     /** Only for the menu items. */
  32     wxCONTROL_ISSUBMENU  = wxCONTROL_SPECIAL,
  33
  34     /** Only for the tree items. */
  35     wxCONTROL_EXPANDED   = wxCONTROL_SPECIAL,
  36
  37     /** Only for the status bar panes. */
  38     wxCONTROL_SIZEGRIP   = wxCONTROL_SPECIAL,
  39
  40     /** Checkboxes only: flat border. */
  41     wxCONTROL_FLAT       = wxCONTROL_SPECIAL,
  42
  43     /** Mouse is currently over the control. */
  44     wxCONTROL_CURRENT    = 0x00000010,
  45
  46     /** Selected item in e.g. listbox. */
  47     wxCONTROL_SELECTED   = 0x00000020,
  48
  49     /** (Check/radio button) is checked. */
  50     wxCONTROL_CHECKED    = 0x00000040,
  51
  52     /** (Menu) item can be checked. */
  53     wxCONTROL_CHECKABLE  = 0x00000080,
  54
  55     /** (Check) undetermined state. */
  56     wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE
  57 };
  58
  59 /**
  60     @struct wxSplitterRenderParams
  61
  62     This is just a simple @c struct used as a return value of
  63     wxRendererNative::GetSplitterParams().
  64
  65     It doesn't have any methods and all of its fields are constant, so they can
  66     only be examined but not modified.
  67
  68     @library{wxbase}
  69     @category{gdi}
  70 */
  71 struct wxSplitterRenderParams
  72 {
  73     /**
  74         The only way to initialize this struct is by using this ctor.
  75     */
  76     wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_);
  77
  78     /**
  79         The width of the border drawn by the splitter inside it, may be 0.
  80     */
  81     const wxCoord border;
  82
  83     /**
  84         @true if the sash changes appearance when the mouse passes over it, @false
  85         otherwise.
  86     */
  87     const bool isHotSensitive;
  88
  89     /**
  90         The width of the splitter sash.
  91     */
  92     const wxCoord widthSash;
  93 };
  94
  95 /**
  96     @struct wxHeaderButtonParams
  97
  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.
 101
 102     @library{wxbase}
 103     @category{gdi}
 104 */
 105 struct wxHeaderButtonParams
 106 {
 107     wxHeaderButtonParams();
 108
 109     wxColour    m_arrowColour;
 110     wxColour    m_selectionColour;
 111     wxString    m_labelText;
 112     wxFont      m_labelFont;
 113     wxColour    m_labelColour;
 114     wxBitmap    m_labelBitmap;
 115     int         m_labelAlignment;
 116 };
 117
 118 /**
 119     Used to specify the type of sort arrow used with
 120     wxRendererNative::DrawHeaderButton().
 121 */
 122 enum wxHeaderSortIconType
 123 {
 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.
 127 };
 128
 129
 130
 131 /**
 132     @class wxDelegateRendererNative
 133
 134     wxDelegateRendererNative allows reuse of renderers code by forwarding all the
 135     wxRendererNative methods to the given object and thus allowing you to only
 136     modify some of its methods -- without having to reimplement all of them.
 137
 138     Note that the "normal", inheritance-based approach, doesn't work with the
 139     renderers as it is impossible to derive from a class unknown at compile-time
 140     and the renderer is only chosen at run-time. So suppose that you want to only
 141     add something to the drawing of the tree control buttons but leave all the
 142     other methods unchanged -- the only way to do it, considering that the renderer
 143     class which you want to customize might not even be written yet when you write
 144     your code (it could be written later and loaded from a DLL during run-time), is
 145     by using this class.
 146
 147     Except for the constructor, it has exactly the same methods as
 148     wxRendererNative and their implementation is trivial: they are simply forwarded
 149     to the real renderer. Note that the "real" renderer may, in turn, be a
 150     wxDelegateRendererNative as well and that there may be arbitrarily many levels
 151     like this -- but at the end of the chain there must be a real renderer which
 152     does the drawing.
 153
 154     @library{wxcore}
 155     @category{gdi}
 156
 157     @see wxRendererNative
 158 */
 159 class wxDelegateRendererNative : public wxRendererNative
 160 {
 161 public:
 162     /**
 163         The default constructor does the same thing as the other one except that it
 164         uses the @ref wxRendererNative::GetGeneric() "generic renderer" instead of the
 165         user-specified @a rendererNative.
 166
 167         In any case, this sets up the delegate renderer object to follow all calls to
 168         the specified real renderer.
 169     */
 170     wxDelegateRendererNative();
 171     /**
 172         This constructor uses the user-specified @a rendererNative to set up the delegate
 173         renderer object to follow all calls to the specified real renderer.
 174
 175         @note
 176         This object does not take ownership of (i.e. won't delete) @a rendererNative.
 177     */
 178     wxDelegateRendererNative(wxRendererNative& rendererNative);
 179
 180     // The rest of these functions inherit the documentation from wxRendererNative
 181
 182     virtual int DrawHeaderButton(wxWindow *win, wxDC& dc,
 183                                  const wxRect& rect, int flags = 0,
 184                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE,
 185                                  wxHeaderButtonParams* params = NULL);
 186
 187     virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc,
 188                                          const wxRect& rect, int flags = 0,
 189                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE,
 190                                          wxHeaderButtonParams* params = NULL);
 191
 192     virtual int GetHeaderButtonHeight(wxWindow *win);
 193
 194     virtual void DrawTreeItemButton(wxWindow *win, wxDC& dc,
 195                                     const wxRect& rect, int flags = 0);
 196
 197     virtual void DrawSplitterBorder(wxWindow *win, wxDC& dc,
 198                                     const wxRect& rect, int flags = 0);
 199
 200     virtual void DrawSplitterSash(wxWindow *win, wxDC& dc,
 201                                   const wxSize& size, wxCoord position,
 202                                   wxOrientation orient, int flags = 0);
 203
 204     virtual void DrawComboBoxDropButton(wxWindow *win, wxDC& dc,
 205                                         const wxRect& rect, int flags = 0);
 206
 207     virtual void DrawDropArrow(wxWindow *win, wxDC& dc,
 208                                const wxRect& rect, int flags = 0);
 209
 210     virtual void DrawCheckBox(wxWindow *win, wxDC& dc,
 211                               const wxRect& rect, int flags = 0 );
 212
 213     virtual wxSize GetCheckBoxSize() const;
 214
 215     virtual void DrawPushButton(wxWindow *win, wxDC& dc,
 216                                 const wxRect& rect, int flags = 0 );
 217
 218     virtual void DrawItemSelectionRect(wxWindow *win, wxDC& dc,
 219                                        const wxRect& rect, int flags = 0 );
 220
 221     virtual void DrawFocusRect(wxWindow* win, wxDC& dc,
 222                                const wxRect& rect, int flags = 0);
 223
 224     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow *win);
 225
 226     virtual wxRendererVersion GetVersion() const;
 227 };
 228
 229
 230
 231 /**
 232     @class wxRendererNative
 233
 234     First, a brief introduction to wxRendererNative and why it is needed.
 235
 236     Usually wxWidgets uses the underlying low level GUI system to draw all the
 237     controls - this is what we mean when we say that it is a "native" framework.
 238     However not all controls exist under all (or even any) platforms and in this
 239     case wxWidgets provides a default, generic, implementation of them written in
 240     wxWidgets itself.
 241
 242     These controls don't have the native appearance if only the standard
 243     line drawing and other graphics primitives are used, because the native
 244     appearance is different under different platforms while the lines are always
 245     drawn in the same way.
 246
 247     This is why we have renderers: wxRendererNative is a class which virtualizes the
 248     drawing, i.e. it abstracts the drawing operations and allows you to draw say, a
 249     button, without caring about exactly how this is done. Of course, as we
 250     can draw the button differently in different renderers, this also allows us to
 251     emulate the native look and feel.
 252
 253     So the renderers work by exposing a large set of high-level drawing functions
 254     which are used by the generic controls. There is always a default global
 255     renderer but it may be changed or extended by the user, see
 256     @ref page_samples_render.
 257
 258     All drawing functions take some standard parameters:
 259
 260     @li @a win - The window being drawn. It is normally not used and when
 261     it is it should only be used as a generic wxWindow
 262     (in order to get its low level handle, for example), but you should
 263     not assume that it is of some given type as the same renderer
 264     function may be reused for drawing different kinds of control.
 265     @li @a dc - The wxDC to draw on. Only this device
 266     context should be used for drawing. It is not necessary to restore
 267     pens and brushes for it on function exit but, on the other hand, you
 268     shouldn't assume that it is in any specific state on function entry:
 269     the rendering functions should always prepare it.
 270     @li @a rect - The bounding rectangle for the element to be drawn.
 271     @li @a flags - The optional flags (none by default) which can be a
 272     combination of the @ref wxCONTROL_FLAGS.
 273
 274     Note that each drawing function restores the wxDC attributes if
 275     it changes them, so it is safe to assume that the same pen, brush and colours
 276     that were active before the call to this function are still in effect after it.
 277
 278     @library{wxcore}
 279     @category{gdi}
 280 */
 281 class wxRendererNative
 282 {
 283 public:
 284     /**
 285         Virtual destructor as for any base class.
 286     */
 287     virtual ~wxRendererNative();
 288
 289     /**
 290         Draw a check box.
 291
 292         @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or
 293         @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS.
 294     */
 295     virtual void DrawCheckBox(wxWindow* win, wxDC& dc, const wxRect& rect,
 296                               int flags = 0) = 0;
 297
 298     /**
 299         Draw a button like the one used by wxComboBox to show a
 300         drop down window. The usual appearance is a downwards pointing arrow.
 301
 302         @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
 303         see @ref wxCONTROL_FLAGS.
 304     */
 305     virtual void DrawComboBoxDropButton(wxWindow* win, wxDC& dc,
 306                                         const wxRect& rect, int flags = 0) = 0;
 307
 308     /**
 309         Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
 310         have transparent background.
 311
 312         @a rect is not entirely filled by the arrow. Instead, you should use bounding
 313         rectangle of a drop down button which arrow matches the size you need.
 314
 315         @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
 316         see @ref wxCONTROL_FLAGS.
 317     */
 318     virtual void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect,
 319                                int flags = 0) = 0;
 320
 321     /**
 322         Draw a focus rectangle using the specified rectangle.
 323         wxListCtrl.
 324
 325         The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
 326         see @ref wxCONTROL_FLAGS.
 327     */
 328     virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect,
 329                                int flags = 0) = 0;
 330
 331     /**
 332         Draw the header control button (used, for example, by wxListCtrl).
 333
 334         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 335         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 336
 337         @return
 338         The optimal width to contain the the unabreviated label text or
 339         bitmap, the sort arrow if present, and internal margins.
 340     */
 341     virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 342                                  int flags = 0,
 343                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 344
 345     /**
 346         Draw the contents of a header control button (label, sort arrows,
 347         etc.). This function is normally only called by DrawHeaderButton().
 348
 349         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 350         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 351
 352         @return
 353         The optimal width to contain the the unabreviated label text or
 354         bitmap, the sort arrow if present, and internal margins.
 355     */
 356     virtual int DrawHeaderButtonContents(wxWindow* win, wxDC& dc,
 357                                          const wxRect& rect, int flags = 0,
 358                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 359
 360     /**
 361         Draw a selection rectangle underneath the text as used e.g. in a
 362         wxListCtrl.
 363
 364         The supported @a flags are @c wxCONTROL_SELECTED for items
 365         which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT
 366         for the item that has the focus (often a dotted line around the item's text).
 367         @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus
 368         (othewise the the selection rectangle is e.g. often grey and not blue).
 369         This may be ignored by the renderer or deduced by the code directly from
 370         the @a win.
 371     */
 372     virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc,
 373                                        const wxRect& rect, int flags = 0) = 0;
 374
 375     /**
 376         Draw a blank push button that looks very similar to wxButton.
 377
 378         @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or
 379         @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS.
 380     */
 381     virtual void DrawPushButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 382                                 int flags = 0) = 0;
 383
 384     /**
 385         Draw the border for sash window: this border must be such that the sash
 386         drawn by DrawSplitterSash() blends into it well.
 387     */
 388     virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc, const wxRect& rect,
 389                                     int flags = 0) = 0;
 390
 391     /**
 392         Draw a sash. The @a orient parameter defines whether the sash should be
 393         vertical or horizontal and how the @a position should be interpreted.
 394     */
 395     virtual void DrawSplitterSash(wxWindow* win, wxDC& dc, const wxSize& size,
 396                                   wxCoord position, wxOrientation orient,
 397                                   int flags = 0) = 0;
 398
 399     /**
 400         Draw the expanded/collapsed icon for a tree control item.
 401
 402         To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit,
 403         see @ref wxCONTROL_FLAGS.
 404     */
 405     virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 406                                     int flags = 0) = 0;
 407
 408     /**
 409         Draw a native wxChoice
 410     */
 411     virtual void DrawChoice(wxWindow* win, wxDC& dc, const wxRect& rect, int flags=0) = 0;
 412
 413     /**
 414         Draw a native wxComboBox
 415     */
 416     virtual void DrawComboBox(wxWindow* win, wxDC& dc, const wxRect& rect, int flags=0) = 0;
 417
 418     /**
 419         Draw a native wxTextCtrl frame
 420     */
 421     virtual void DrawTextCtrl(wxWindow* win, wxDC& dc, const wxRect& rect, int flags=0) = 0;
 422
 423     /**
 424         Draw a native wxRadioButton (just the button image, not the text)
 425     */
 426     virtual void DrawRadioButton(wxWindow* win, wxDC& dc, const wxRect& rect, int flags=0) = 0;
 427
 428     /**
 429         Return the currently used renderer.
 430     */
 431     static wxRendererNative& Get();
 432
 433     /**
 434         Return the default (native) implementation for this platform -- this is also
 435         the one used by default but this may be changed by calling
 436         Set() in which case the return value of this
 437         method may be different from the return value of Get().
 438     */
 439     static wxRendererNative& GetDefault();
 440
 441     /**
 442         Return the generic implementation of the renderer. Under some platforms, this
 443         is the default renderer implementation, others have platform-specific default
 444         renderer which can be retrieved by calling GetDefault().
 445     */
 446     static wxRendererNative& GetGeneric();
 447
 448     /**
 449         Returns the size of a check box.
 450     */
 451     virtual wxSize GetCheckBoxSize() const = 0;
 452
 453     /**
 454         Returns the height of a header button, either a fixed platform height if
 455         available, or a
 456         generic height based on the window's font.
 457     */
 458     virtual int GetHeaderButtonHeight(wxWindow* win) = 0;
 459
 460     /**
 461         Get the splitter parameters, see
 462         wxSplitterRenderParams.
 463     */
 464     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win) = 0;
 465
 466     /**
 467         This function is used for version checking: Load()
 468         refuses to load any shared libraries implementing an older or incompatible
 469         version.
 470
 471         @remarks
 472         The implementation of this method is always the same in all renderers (simply
 473         construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
 474         but it has to be in the derived, not base, class, to detect mismatches between
 475         the renderers versions and so you have to implement it anew in all renderers.
 476     */
 477     virtual wxRendererVersion GetVersion() const = 0;
 478
 479     /**
 480         Load the renderer from the specified DLL, the returned pointer must be
 481         deleted by caller if not @NULL when it is not used any more.
 482
 483         The @a name should be just the base name of the renderer and not the full
 484         name of the DLL file which is constructed differently (using
 485         wxDynamicLibrary::CanonicalizePluginName())
 486         on different systems.
 487     */
 488     static wxRendererNative* Load(const wxString& name);
 489
 490     /**
 491         Set the renderer to use, passing @NULL reverts to using the default
 492         renderer (the global renderer must always exist).
 493
 494         Return the previous renderer used with Set() or @NULL if none.
 495     */
 496     static wxRendererNative* Set(wxRendererNative* renderer);
 497 };
 498
 499
 500
 501 /**
 502     @struct wxRendererVersion
 503
 504     This simple struct represents the wxRendererNative
 505     interface version and is only used as the return value of
 506     wxRendererNative::GetVersion().
 507
 508     The version has two components: the version itself and the age. If the main
 509     program and the renderer have different versions they are never compatible with
 510     each other because the version is only changed when an existing virtual
 511     function is modified or removed. The age, on the other hand, is incremented
 512     each time a new virtual method is added and so, at least for the compilers
 513     using a common C++ object model, the calling program is compatible with any
 514     renderer which has the age greater or equal to its age. This verification is
 515     done by IsCompatible() method.
 516
 517     @library{wxbase}
 518     @category{gdi}
 519 */
 520 struct wxRendererVersion
 521 {
 522     /**
 523         Checks if the main program is compatible with the renderer having the version
 524         @e ver, returns @true if it is and @false otherwise.
 525
 526         This method is used by wxRendererNative::Load() to determine whether a
 527         renderer can be used.
 528     */
 529     static bool IsCompatible(const wxRendererVersion& ver);
 530
 531     /**
 532         The age component.
 533     */
 534     const int age;
 535
 536     /**
 537         The version component.
 538     */
 539     const int version;
 540 };
 541