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