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, const wxRect& rect,
 297                               int flags = 0) = 0;
 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, int flags = 0) = 0;
 308
 309     /**
 310         Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
 311         have transparent background.
 312
 313         @a rect is not entirely filled by the arrow. Instead, you should use bounding
 314         rectangle of a drop down button which arrow matches the size you need.
 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 DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect,
 320                                int flags = 0) = 0;
 321
 322     /**
 323         Draw a focus rectangle using the specified rectangle.
 324         wxListCtrl.
 325
 326         The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
 327         see @ref wxCONTROL_FLAGS.
 328     */
 329     virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect,
 330                                int flags = 0) = 0;
 331
 332     /**
 333         Draw the header control button (used, for example, by wxListCtrl).
 334
 335         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 336         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 337
 338         @return
 339         The optimal width to contain the the unabreviated label text or
 340         bitmap, the sort arrow if present, and internal margins.
 341     */
 342     virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 343                                  int flags = 0,
 344                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 345
 346     /**
 347         Draw the contents of a header control button (label, sort arrows,
 348         etc.). This function is normally only called by DrawHeaderButton().
 349
 350         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 351         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 352
 353         @return
 354         The optimal width to contain the the unabreviated label text or
 355         bitmap, the sort arrow if present, and internal margins.
 356     */
 357     virtual int DrawHeaderButtonContents(wxWindow* win, wxDC& dc,
 358                                          const wxRect& rect, int flags = 0,
 359                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 360
 361     /**
 362         Draw a selection rectangle underneath the text as used e.g. in a
 363         wxListCtrl.
 364
 365         The supported @a flags are @c wxCONTROL_SELECTED for items
 366         which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT
 367         for the item that has the focus (often a dotted line around the item's text).
 368         @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus
 369         (othewise the the selection rectangle is e.g. often grey and not blue).
 370         This may be ignored by the renderer or deduced by the code directly from
 371         the @a win.
 372     */
 373     virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc,
 374                                        const wxRect& rect, int flags = 0) = 0;
 375
 376     /**
 377         Draw a blank push button that looks very similar to wxButton.
 378
 379         @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or
 380         @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS.
 381     */
 382     virtual void DrawPushButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 383                                 int flags = 0) = 0;
 384
 385     /**
 386         Draw the border for sash window: this border must be such that the sash
 387         drawn by DrawSplitterSash() blends into it well.
 388     */
 389     virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc, const wxRect& rect,
 390                                     int flags = 0) = 0;
 391
 392     /**
 393         Draw a sash. The @a orient parameter defines whether the sash should be
 394         vertical or horizontal and how the @a position should be interpreted.
 395     */
 396     virtual void DrawSplitterSash(wxWindow* win, wxDC& dc, const wxSize& size,
 397                                   wxCoord position, wxOrientation orient,
 398                                   int flags = 0) = 0;
 399
 400     /**
 401         Draw the expanded/collapsed icon for a tree control item.
 402
 403         To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit,
 404         see @ref wxCONTROL_FLAGS.
 405     */
 406     virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 407                                     int flags = 0) = 0;
 408
 409     /**
 410         Return the currently used renderer.
 411     */
 412     static wxRendererNative Get();
 413
 414     /**
 415         Return the default (native) implementation for this platform -- this is also
 416         the one used by default but this may be changed by calling
 417         Set() in which case the return value of this
 418         method may be different from the return value of Get().
 419     */
 420     static wxRendererNative GetDefault();
 421
 422     /**
 423         Return the generic implementation of the renderer. Under some platforms, this
 424         is the default renderer implementation, others have platform-specific default
 425         renderer which can be retrieved by calling GetDefault().
 426     */
 427     static wxRendererNative GetGeneric();
 428
 429     /**
 430         Returns the size of a check box.
 431     */
 432     virtual wxSize GetCheckBoxSize(wxWindow* win) = 0;
 433
 434     /**
 435         Returns the height of a header button, either a fixed platform height if
 436         available, or a
 437         generic height based on the window's font.
 438     */
 439     virtual int GetHeaderButtonHeight(wxWindow* win) = 0;
 440
 441     /**
 442         Get the splitter parameters, see
 443         wxSplitterRenderParams.
 444     */
 445     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win) = 0;
 446
 447     /**
 448         This function is used for version checking: Load()
 449         refuses to load any shared libraries implementing an older or incompatible
 450         version.
 451
 452         @remarks
 453         The implementation of this method is always the same in all renderers (simply
 454         construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
 455         but it has to be in the derived, not base, class, to detect mismatches between
 456         the renderers versions and so you have to implement it anew in all renderers.
 457     */
 458     virtual wxRendererVersion GetVersion() const = 0;
 459
 460     /**
 461         Load the renderer from the specified DLL, the returned pointer must be
 462         deleted by caller if not @NULL when it is not used any more.
 463
 464         The @a name should be just the base name of the renderer and not the full
 465         name of the DLL file which is constructed differently (using
 466         wxDynamicLibrary::CanonicalizePluginName())
 467         on different systems.
 468     */
 469     static wxRendererNative* Load(const wxString& name);
 470
 471     /**
 472         Set the renderer to use, passing @NULL reverts to using the default
 473         renderer (the global renderer must always exist).
 474
 475         Return the previous renderer used with Set() or @NULL if none.
 476     */
 477     static wxRendererNative* Set(wxRendererNative* renderer);
 478 };
 479
 480
 481
 482 /**
 483     @struct wxRendererVersion
 484
 485     This simple struct represents the wxRendererNative
 486     interface version and is only used as the return value of
 487     wxRendererNative::GetVersion().
 488
 489     The version has two components: the version itself and the age. If the main
 490     program and the renderer have different versions they are never compatible with
 491     each other because the version is only changed when an existing virtual
 492     function is modified or removed. The age, on the other hand, is incremented
 493     each time a new virtual method is added and so, at least for the compilers
 494     using a common C++ object model, the calling program is compatible with any
 495     renderer which has the age greater or equal to its age. This verification is
 496     done by IsCompatible() method.
 497
 498     @library{wxbase}
 499     @category{gdi}
 500 */
 501 struct wxRendererVersion
 502 {
 503     /**
 504         Checks if the main program is compatible with the renderer having the version
 505         @e ver, returns @true if it is and @false otherwise.
 506
 507         This method is used by wxRendererNative::Load() to determine whether a
 508         renderer can be used.
 509     */
 510     static bool IsCompatible(const wxRendererVersion& ver);
 511
 512     /**
 513         The age component.
 514     */
 515     const int age;
 516
 517     /**
 518         The version component.
 519     */
 520     const int version;
 521 };
 522