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