interface/wx/renderer.h

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