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
 136     thus allowing you to only modify some of its methods -- without having to
 137     reimplement all of them.
 138
 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
 146     by using this class.
 147
 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.
 154
 155     @library{wxcore}
 156     @category{gdi}
 157
 158     @see wxRendererNative
 159 */
 160 class wxDelegateRendererNative : public wxRendererNative
 161 {
 162 public:
 163     /**
 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.
 167
 168         In any case, this sets up the delegate renderer object to follow all calls to
 169         the specified real renderer.
 170     */
 171     wxDelegateRendererNative();
 172     /**
 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.
 175
 176         @note
 177         This object does not take ownership of (i.e. won't delete) @a rendererNative.
 178     */
 179     wxDelegateRendererNative(wxRendererNative& rendererNative);
 180
 181     // The rest of these functions inherit the documentation from wxRendererNative
 182
 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);
 187
 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);
 192
 193     virtual int GetHeaderButtonHeight(wxWindow *win);
 194
 195     virtual void DrawTreeItemButton(wxWindow *win, wxDC& dc,
 196                                     const wxRect& rect, int flags = 0);
 197
 198     virtual void DrawSplitterBorder(wxWindow *win, wxDC& dc,
 199                                     const wxRect& rect, int flags = 0);
 200
 201     virtual void DrawSplitterSash(wxWindow *win, wxDC& dc,
 202                                   const wxSize& size, wxCoord position,
 203                                   wxOrientation orient, int flags = 0);
 204
 205     virtual void DrawComboBoxDropButton(wxWindow *win, wxDC& dc,
 206                                         const wxRect& rect, int flags = 0);
 207
 208     virtual void DrawDropArrow(wxWindow *win, wxDC& dc,
 209                                const wxRect& rect, int flags = 0);
 210
 211     virtual void DrawCheckBox(wxWindow *win, wxDC& dc,
 212                               const wxRect& rect, int flags = 0 );
 213
 214     virtual wxSize GetCheckBoxSize(wxWindow *win);
 215
 216     virtual void DrawPushButton(wxWindow *win, wxDC& dc,
 217                                 const wxRect& rect, int flags = 0 );
 218
 219     virtual void DrawItemSelectionRect(wxWindow *win, wxDC& dc,
 220                                        const wxRect& rect, int flags = 0 );
 221
 222     virtual void DrawFocusRect(wxWindow* win, wxDC& dc,
 223                                const wxRect& rect, int flags = 0);
 224
 225     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow *win);
 226
 227     virtual wxRendererVersion GetVersion() const;
 228 };
 229
 230
 231
 232 /**
 233     @class wxRendererNative
 234
 235     First, a brief introduction to wxRendererNative and why it is needed.
 236
 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
 241     wxWidgets itself.
 242
 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.
 247
 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.
 253
 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.
 258
 259     All drawing functions take some standard parameters:
 260
 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.
 274
 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.
 278
 279     @library{wxcore}
 280     @category{gdi}
 281 */
 282 class wxRendererNative
 283 {
 284 public:
 285     /**
 286         Virtual destructor as for any base class.
 287     */
 288     virtual ~wxRendererNative();
 289
 290     /**
 291         Draw a check box.
 292
 293         @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or
 294         @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS.
 295     */
 296     virtual void DrawCheckBox(wxWindow* win, wxDC& dc,
 297                               const wxRect& rect, int flags);
 298
 299     /**
 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.
 302
 303         @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
 304         see @ref wxCONTROL_FLAGS.
 305     */
 306     virtual void DrawComboBoxDropButton(wxWindow* win, wxDC& dc,
 307                                 const wxRect& rect,
 308                                 int flags);
 309
 310     /**
 311         Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
 312         have transparent background.
 313
 314         @a rect is not entirely filled by the arrow. Instead, you should use bounding
 315         rectangle of a drop down button which arrow matches the size you need.
 316
 317         @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
 318         see @ref wxCONTROL_FLAGS.
 319     */
 320     virtual void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect,
 321                        int flags);
 322
 323     /**
 324         Draw a focus rectangle using the specified rectangle.
 325         wxListCtrl.
 326
 327         The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
 328         see @ref wxCONTROL_FLAGS.
 329     */
 330     virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect,
 331                        int flags = 0);
 332
 333     /**
 334         Draw the header control button (used, for example, by wxListCtrl).
 335
 336         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 337         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 338
 339         @return
 340         The optimal width to contain the the unabreviated label text or
 341         bitmap, the sort arrow if present, and internal margins.
 342     */
 343     virtual int DrawHeaderButton(wxWindow* win, wxDC& dc,
 344                                  const wxRect& rect, int flags = 0,
 345                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE,
 346                                  wxHeaderButtonParams* params = NULL);
 347
 348     /**
 349         Draw the contents of a header control button (label, sort arrows,
 350         etc.). This function is normally only called by DrawHeaderButton().
 351
 352         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 353         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 354
 355         @return
 356         The optimal width to contain the the unabreviated label text or
 357         bitmap, the sort arrow if present, and internal margins.
 358     */
 359     virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc,
 360                                          const wxRect& rect, int flags = 0,
 361                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE,
 362                                          wxHeaderButtonParams* params = NULL);
 363
 364     /**
 365         Draw a selection rectangle underneath the text as used e.g. in a
 366         wxListCtrl.
 367
 368         The supported @a flags are @c wxCONTROL_SELECTED for items
 369         which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT
 370         for the item that has the focus (often a dotted line around the item's text).
 371         @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus
 372         (othewise the the selection rectangle is e.g. often grey and not blue).
 373         This may be ignored by the renderer or deduced by the code directly from
 374         the @a win.
 375     */
 376     virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc,
 377                                        const wxRect& rect, int flags = 0);
 378
 379     /**
 380         Draw a blank push button that looks very similar to wxButton.
 381
 382         @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or
 383         @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS.
 384     */
 385     virtual void DrawPushButton(wxWindow* win, wxDC& dc,
 386                                 const wxRect& rect, int flags);
 387
 388     /**
 389         Draw the border for sash window: this border must be such that the sash
 390         drawn by DrawSplitterSash() blends into it well.
 391     */
 392     virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc,
 393                                     const wxRect& rect, int flags = 0);
 394
 395     /**
 396         Draw a sash. The @a orient parameter defines whether the sash should be
 397         vertical or horizontal and how the @a position should be interpreted.
 398     */
 399     virtual void DrawSplitterSash(wxWindow* win, wxDC& dc,
 400                                   const wxSize& size, wxCoord position,
 401                                   wxOrientation orient, int flags = 0);
 402
 403     /**
 404         Draw the expanded/collapsed icon for a tree control item.
 405
 406         To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit,
 407         see @ref wxCONTROL_FLAGS.
 408     */
 409     virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc,
 410                                     const wxRect& rect, int flags = 0);
 411
 412     /**
 413         Return the currently used renderer.
 414     */
 415     static wxRendererNative Get();
 416
 417     /**
 418         Return the default (native) implementation for this platform -- this is also
 419         the one used by default but this may be changed by calling
 420         Set() in which case the return value of this
 421         method may be different from the return value of Get().
 422     */
 423     static wxRendererNative GetDefault();
 424
 425     /**
 426         Return the generic implementation of the renderer. Under some platforms, this
 427         is the default renderer implementation, others have platform-specific default
 428         renderer which can be retrieved by calling GetDefault().
 429     */
 430     static wxRendererNative GetGeneric();
 431
 432     /**
 433         Returns the size of a check box.
 434     */
 435     virtual wxSize GetCheckBoxSize(wxWindow *win);
 436
 437     /**
 438         Returns the height of a header button, either a fixed platform height if
 439         available, or a
 440         generic height based on the window's font.
 441     */
 442     virtual int GetHeaderButtonHeight(wxWindow* win);
 443
 444     /**
 445         Get the splitter parameters, see
 446         wxSplitterRenderParams.
 447     */
 448     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win);
 449
 450     /**
 451         This function is used for version checking: Load()
 452         refuses to load any shared libraries implementing an older or incompatible
 453         version.
 454
 455         @remarks
 456         The implementation of this method is always the same in all renderers (simply
 457         construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
 458         but it has to be in the derived, not base, class, to detect mismatches between
 459         the renderers versions and so you have to implement it anew in all renderers.
 460     */
 461     virtual wxRendererVersion GetVersion() const;
 462
 463     /**
 464         Load the renderer from the specified DLL, the returned pointer must be
 465         deleted by caller if not @NULL when it is not used any more.
 466
 467         The @a name should be just the base name of the renderer and not the full
 468         name of the DLL file which is constructed differently (using
 469         wxDynamicLibrary::CanonicalizePluginName())
 470         on different systems.
 471     */
 472     static wxRendererNative* Load(const wxString& name);
 473
 474     /**
 475         Set the renderer to use, passing @NULL reverts to using the default
 476         renderer (the global renderer must always exist).
 477
 478         Return the previous renderer used with Set() or @NULL if none.
 479     */
 480     static wxRendererNative* Set(wxRendererNative* renderer);
 481 };
 482
 483
 484
 485 /**
 486     @struct wxRendererVersion
 487
 488     This simple struct represents the wxRendererNative
 489     interface version and is only used as the return value of
 490     wxRendererNative::GetVersion().
 491
 492     The version has two components: the version itself and the age. If the main
 493     program and the renderer have different versions they are never compatible with
 494     each other because the version is only changed when an existing virtual
 495     function is modified or removed. The age, on the other hand, is incremented
 496     each time a new virtual method is added and so, at least for the compilers
 497     using a common C++ object model, the calling program is compatible with any
 498     renderer which has the age greater or equal to its age. This verification is
 499     done by IsCompatible() method.
 500
 501     @library{wxbase}
 502     @category{gdi}
 503 */
 504 struct wxRendererVersion
 505 {
 506     /**
 507         Checks if the main program is compatible with the renderer having the version
 508         @e ver, returns @true if it is and @false otherwise.
 509
 510         This method is used by wxRendererNative::Load() to determine whether a
 511         renderer can be used.
 512     */
 513     static bool IsCompatible(const wxRendererVersion& ver);
 514
 515     /**
 516         The age component.
 517     */
 518     const int age;
 519
 520     /**
 521         The version component.
 522     */
 523     const int version;
 524 };
 525