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