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 licence
   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{wxcore}
  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{wxcore}
 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 int GetHeaderButtonMargin(wxWindow *win);
 208
 209     virtual void DrawTreeItemButton(wxWindow *win, wxDC& dc,
 210                                     const wxRect& rect, int flags = 0);
 211
 212     virtual void DrawSplitterBorder(wxWindow *win, wxDC& dc,
 213                                     const wxRect& rect, int flags = 0);
 214
 215     virtual void DrawSplitterSash(wxWindow *win, wxDC& dc,
 216                                   const wxSize& size, wxCoord position,
 217                                   wxOrientation orient, int flags = 0);
 218
 219     virtual void DrawComboBoxDropButton(wxWindow *win, wxDC& dc,
 220                                         const wxRect& rect, int flags = 0);
 221
 222     virtual void DrawDropArrow(wxWindow *win, wxDC& dc,
 223                                const wxRect& rect, int flags = 0);
 224
 225     virtual void DrawCheckBox(wxWindow *win, wxDC& dc,
 226                               const wxRect& rect, int flags = 0 );
 227
 228     virtual wxSize GetCheckBoxSize(wxWindow *win);
 229
 230     virtual void DrawPushButton(wxWindow *win, wxDC& dc,
 231                                 const wxRect& rect, int flags = 0 );
 232
 233     virtual void DrawItemSelectionRect(wxWindow *win, wxDC& dc,
 234                                        const wxRect& rect, int flags = 0 );
 235
 236     virtual void DrawFocusRect(wxWindow* win, wxDC& dc,
 237                                const wxRect& rect, int flags = 0);
 238
 239     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow *win);
 240
 241     virtual wxRendererVersion GetVersion() const;
 242 };
 243
 244
 245
 246 /**
 247     @class wxRendererNative
 248
 249     First, a brief introduction to wxRendererNative and why it is needed.
 250
 251     Usually wxWidgets uses the underlying low level GUI system to draw all the
 252     controls - this is what we mean when we say that it is a "native" framework.
 253     However not all controls exist under all (or even any) platforms and in this
 254     case wxWidgets provides a default, generic, implementation of them written in
 255     wxWidgets itself.
 256
 257     These controls don't have the native appearance if only the standard
 258     line drawing and other graphics primitives are used, because the native
 259     appearance is different under different platforms while the lines are always
 260     drawn in the same way.
 261
 262     This is why we have renderers: wxRendererNative is a class which virtualizes the
 263     drawing, i.e. it abstracts the drawing operations and allows you to draw say, a
 264     button, without caring about exactly how this is done. Of course, as we
 265     can draw the button differently in different renderers, this also allows us to
 266     emulate the native look and feel.
 267
 268     So the renderers work by exposing a large set of high-level drawing functions
 269     which are used by the generic controls. There is always a default global
 270     renderer but it may be changed or extended by the user, see
 271     @ref page_samples_render.
 272
 273     All drawing functions take some standard parameters:
 274
 275     @li @a win - The window being drawn. It is normally not used and when
 276     it is it should only be used as a generic wxWindow
 277     (in order to get its low level handle, for example), but you should
 278     not assume that it is of some given type as the same renderer
 279     function may be reused for drawing different kinds of control.
 280     @li @a dc - The wxDC to draw on. Only this device
 281     context should be used for drawing. It is not necessary to restore
 282     pens and brushes for it on function exit but, on the other hand, you
 283     shouldn't assume that it is in any specific state on function entry:
 284     the rendering functions should always prepare it.
 285     @li @a rect - The bounding rectangle for the element to be drawn.
 286     @li @a flags - The optional flags (none by default) which can be a
 287     combination of the @ref wxCONTROL_FLAGS.
 288
 289     Note that each drawing function restores the wxDC attributes if
 290     it changes them, so it is safe to assume that the same pen, brush and colours
 291     that were active before the call to this function are still in effect after it.
 292
 293     @library{wxcore}
 294     @category{gdi}
 295 */
 296 class wxRendererNative
 297 {
 298 public:
 299     /**
 300         Virtual destructor as for any base class.
 301     */
 302     virtual ~wxRendererNative();
 303
 304     /**
 305         Draw a check box.
 306
 307         @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or
 308         @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS.
 309     */
 310     virtual void DrawCheckBox(wxWindow* win, wxDC& dc, const wxRect& rect,
 311                               int flags = 0) = 0;
 312
 313     /**
 314         Draw a button like the one used by wxComboBox to show a
 315         drop down window. The usual appearance is a downwards pointing arrow.
 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 DrawComboBoxDropButton(wxWindow* win, wxDC& dc,
 321                                         const wxRect& rect, int flags = 0) = 0;
 322
 323     /**
 324         Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
 325         have transparent background.
 326
 327         @a rect is not entirely filled by the arrow. Instead, you should use bounding
 328         rectangle of a drop down button which arrow matches the size you need.
 329
 330         @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set,
 331         see @ref wxCONTROL_FLAGS.
 332     */
 333     virtual void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect,
 334                                int flags = 0) = 0;
 335
 336     /**
 337         Draw a focus rectangle using the specified rectangle.
 338         wxListCtrl.
 339
 340         The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
 341         see @ref wxCONTROL_FLAGS.
 342     */
 343     virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect,
 344                                int flags = 0) = 0;
 345
 346     /**
 347         Draw the header control button (used, for example, by wxListCtrl).
 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 unabbreviated label text or
 354         bitmap, the sort arrow if present, and internal margins.
 355     */
 356     virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 357                                  int flags = 0,
 358                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 359
 360     /**
 361         Draw the contents of a header control button (label, sort arrows,
 362         etc.). This function is normally only called by DrawHeaderButton().
 363
 364         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 365         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 366
 367         @return
 368         The optimal width to contain the unabbreviated label text or
 369         bitmap, the sort arrow if present, and internal margins.
 370     */
 371     virtual int DrawHeaderButtonContents(wxWindow* win, wxDC& dc,
 372                                          const wxRect& rect, int flags = 0,
 373                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 374
 375     /**
 376         Draw a selection rectangle underneath the text as used e.g. in a
 377         wxListCtrl.
 378
 379         The supported @a flags are @c wxCONTROL_SELECTED for items
 380         which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT
 381         for the item that has the focus (often a dotted line around the item's text).
 382         @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus
 383         (otherwise the selection rectangle is e.g. often grey and not blue).
 384         This may be ignored by the renderer or deduced by the code directly from
 385         the @a win.
 386     */
 387     virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc,
 388                                        const wxRect& rect, int flags = 0) = 0;
 389
 390     /**
 391         Draw a blank push button that looks very similar to wxButton.
 392
 393         @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or
 394         @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS.
 395     */
 396     virtual void DrawPushButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 397                                 int flags = 0) = 0;
 398
 399     /**
 400         Draw the border for sash window: this border must be such that the sash
 401         drawn by DrawSplitterSash() blends into it well.
 402     */
 403     virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc, const wxRect& rect,
 404                                     int flags = 0) = 0;
 405
 406     /**
 407         Draw a sash. The @a orient parameter defines whether the sash should be
 408         vertical or horizontal and how the @a position should be interpreted.
 409     */
 410     virtual void DrawSplitterSash(wxWindow* win, wxDC& dc, const wxSize& size,
 411                                   wxCoord position, wxOrientation orient,
 412                                   int flags = 0) = 0;
 413
 414     /**
 415         Draw the expanded/collapsed icon for a tree control item.
 416
 417         To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit,
 418         see @ref wxCONTROL_FLAGS.
 419     */
 420     virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 421                                     int flags = 0) = 0;
 422
 423     /**
 424         Draw a native wxChoice
 425     */
 426     virtual void DrawChoice(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0) = 0;
 427
 428     /**
 429         Draw a native wxComboBox
 430     */
 431     virtual void DrawComboBox(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0) = 0;
 432
 433     /**
 434         Draw a native wxTextCtrl frame
 435     */
 436     virtual void DrawTextCtrl(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0) = 0;
 437
 438     /**
 439         Draw a native wxRadioButton bitmap.
 440     */
 441     virtual void DrawRadioBitmap(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0) = 0;
 442
 443     /**
 444         Draw a title bar button in the given state.
 445
 446         This function is currently only available under MSW and OS X (and only
 447         for wxTITLEBAR_BUTTON_CLOSE under the latter), its best replacement for
 448         the other platforms is to use wxArtProvider to retrieve the bitmaps for
 449         @c wxART_HELP and @c wxART_CLOSE (but not any other title bar buttons
 450         and not for any state but normal, i.e. not pressed and not current one).
 451
 452         The presence of this function is indicated by @c
 453         wxHAS_DRAW_TITLE_BAR_BITMAP symbol being defined.
 454
 455         Also notice that PNG handler must be enabled using wxImage::AddHandler()
 456         to use this function under OS X currently as the bitmaps are embedded
 457         in the library itself in PNG format.
 458
 459         @since 2.9.1
 460      */
 461     virtual void DrawTitleBarBitmap(wxWindow *win,
 462                                     wxDC& dc,
 463                                     const wxRect& rect,
 464                                     wxTitleBarButton button,
 465                                     int flags = 0) = 0;
 466
 467     /**
 468         Return the currently used renderer.
 469     */
 470     static wxRendererNative& Get();
 471
 472     /**
 473         Return the default (native) implementation for this platform -- this is also
 474         the one used by default but this may be changed by calling
 475         Set() in which case the return value of this
 476         method may be different from the return value of Get().
 477     */
 478     static wxRendererNative& GetDefault();
 479
 480     /**
 481         Return the generic implementation of the renderer. Under some platforms, this
 482         is the default renderer implementation, others have platform-specific default
 483         renderer which can be retrieved by calling GetDefault().
 484     */
 485     static wxRendererNative& GetGeneric();
 486
 487     /**
 488         Returns the size of a check box.
 489         The @a win parameter is not used currently and can be @NULL.
 490     */
 491     virtual wxSize GetCheckBoxSize(wxWindow* win) = 0;
 492
 493     /**
 494         Returns the height of a header button, either a fixed platform height if
 495         available, or a generic height based on the @a win window's font.
 496     */
 497     virtual int GetHeaderButtonHeight(wxWindow* win) = 0;
 498
 499     /**
 500         Returns the horizontal margin on the left and right sides of header
 501         button's label.
 502
 503         @since 2.9.2
 504      */
 505     virtual int GetHeaderButtonMargin(wxWindow *win) = 0;
 506
 507     /**
 508         Get the splitter parameters, see wxSplitterRenderParams.
 509         The @a win parameter should be a wxSplitterWindow.
 510     */
 511     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win) = 0;
 512
 513     /**
 514         This function is used for version checking: Load()
 515         refuses to load any shared libraries implementing an older or incompatible
 516         version.
 517
 518         @remarks
 519         The implementation of this method is always the same in all renderers (simply
 520         construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
 521         but it has to be in the derived, not base, class, to detect mismatches between
 522         the renderers versions and so you have to implement it anew in all renderers.
 523     */
 524     virtual wxRendererVersion GetVersion() const = 0;
 525
 526     /**
 527         Load the renderer from the specified DLL, the returned pointer must be
 528         deleted by caller if not @NULL when it is not used any more.
 529
 530         The @a name should be just the base name of the renderer and not the full
 531         name of the DLL file which is constructed differently (using
 532         wxDynamicLibrary::CanonicalizePluginName())
 533         on different systems.
 534     */
 535     static wxRendererNative* Load(const wxString& name);
 536
 537     /**
 538         Set the renderer to use, passing @NULL reverts to using the default
 539         renderer (the global renderer must always exist).
 540
 541         Return the previous renderer used with Set() or @NULL if none.
 542     */
 543     static wxRendererNative* Set(wxRendererNative* renderer);
 544 };
 545
 546
 547
 548 /**
 549     @struct wxRendererVersion
 550
 551     This simple struct represents the wxRendererNative
 552     interface version and is only used as the return value of
 553     wxRendererNative::GetVersion().
 554
 555     The version has two components: the version itself and the age. If the main
 556     program and the renderer have different versions they are never compatible with
 557     each other because the version is only changed when an existing virtual
 558     function is modified or removed. The age, on the other hand, is incremented
 559     each time a new virtual method is added and so, at least for the compilers
 560     using a common C++ object model, the calling program is compatible with any
 561     renderer which has the age greater or equal to its age. This verification is
 562     done by IsCompatible() method.
 563
 564     @library{wxcore}
 565     @category{gdi}
 566 */
 567 struct wxRendererVersion
 568 {
 569     wxRendererVersion(int version_, int age_);
 570
 571     /**
 572         Checks if the main program is compatible with the renderer having the version
 573         @e ver, returns @true if it is and @false otherwise.
 574
 575         This method is used by wxRendererNative::Load() to determine whether a
 576         renderer can be used.
 577     */
 578     static bool IsCompatible(const wxRendererVersion& ver);
 579
 580     /**
 581         The age component.
 582     */
 583     const int age;
 584
 585     /**
 586         The version component.
 587     */
 588     const int version;
 589 };
 590