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,
 297                               const wxRect& rect, int flags);
 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,
 308                                 int flags);
 309
 310     /**
 311         Draw a drop down arrow that is suitable for use outside a combo box. Arrow will
 312         have transparent background.
 313
 314         @a rect is not entirely filled by the arrow. Instead, you should use bounding
 315         rectangle of a drop down button which arrow matches the size you need.
 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 DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect,
 321                        int flags);
 322
 323     /**
 324         Draw a focus rectangle using the specified rectangle.
 325         wxListCtrl.
 326
 327         The only supported flags is @c wxCONTROL_SELECTED for items which are selected.
 328         see @ref wxCONTROL_FLAGS.
 329     */
 330     virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect,
 331                        int flags = 0);
 332
 333     /**
 334         Draw the header control button (used, for example, by wxListCtrl).
 335
 336         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 337         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 338
 339         @return
 340         The optimal width to contain the the unabreviated label text or
 341         bitmap, the sort arrow if present, and internal margins.
 342     */
 343     virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, const wxRect& rect,
 344                                  int flags = 0,
 345                                  wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 346
 347     /**
 348         Draw the contents of a header control button (label, sort arrows,
 349         etc.). This function is normally only called by DrawHeaderButton().
 350
 351         Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED
 352         @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS.
 353
 354         @return
 355         The optimal width to contain the the unabreviated label text or
 356         bitmap, the sort arrow if present, and internal margins.
 357     */
 358     virtual int DrawHeaderButtonContents(wxWindow* win, wxDC& dc,
 359                                          const wxRect& rect, int flags = 0,
 360                                          wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, wxHeaderButtonParams* params = NULL) = 0;
 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, const wxSize& size,
 398                                   wxCoord position, wxOrientation orient,
 399                                   int flags = 0) = 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 size of a check box.
 432     */
 433     virtual wxSize GetCheckBoxSize(wxWindow* win) = 0;
 434
 435     /**
 436         Returns the height of a header button, either a fixed platform height if
 437         available, or a
 438         generic height based on the window's font.
 439     */
 440     virtual int GetHeaderButtonHeight(wxWindow* win) = 0;
 441
 442     /**
 443         Get the splitter parameters, see
 444         wxSplitterRenderParams.
 445     */
 446     virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win) = 0;
 447
 448     /**
 449         This function is used for version checking: Load()
 450         refuses to load any shared libraries implementing an older or incompatible
 451         version.
 452
 453         @remarks
 454         The implementation of this method is always the same in all renderers (simply
 455         construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values),
 456         but it has to be in the derived, not base, class, to detect mismatches between
 457         the renderers versions and so you have to implement it anew in all renderers.
 458     */
 459     virtual wxRendererVersion GetVersion() const = 0;
 460
 461     /**
 462         Load the renderer from the specified DLL, the returned pointer must be
 463         deleted by caller if not @NULL when it is not used any more.
 464
 465         The @a name should be just the base name of the renderer and not the full
 466         name of the DLL file which is constructed differently (using
 467         wxDynamicLibrary::CanonicalizePluginName())
 468         on different systems.
 469     */
 470     static wxRendererNative* Load(const wxString& name);
 471
 472     /**
 473         Set the renderer to use, passing @NULL reverts to using the default
 474         renderer (the global renderer must always exist).
 475
 476         Return the previous renderer used with Set() or @NULL if none.
 477     */
 478     static wxRendererNative* Set(wxRendererNative* renderer);
 479 };
 480
 481
 482
 483 /**
 484     @struct wxRendererVersion
 485
 486     This simple struct represents the wxRendererNative
 487     interface version and is only used as the return value of
 488     wxRendererNative::GetVersion().
 489
 490     The version has two components: the version itself and the age. If the main
 491     program and the renderer have different versions they are never compatible with
 492     each other because the version is only changed when an existing virtual
 493     function is modified or removed. The age, on the other hand, is incremented
 494     each time a new virtual method is added and so, at least for the compilers
 495     using a common C++ object model, the calling program is compatible with any
 496     renderer which has the age greater or equal to its age. This verification is
 497     done by IsCompatible() method.
 498
 499     @library{wxbase}
 500     @category{gdi}
 501 */
 502 struct wxRendererVersion
 503 {
 504     /**
 505         Checks if the main program is compatible with the renderer having the version
 506         @e ver, returns @true if it is and @false otherwise.
 507
 508         This method is used by wxRendererNative::Load() to determine whether a
 509         renderer can be used.
 510     */
 511     static bool IsCompatible(const wxRendererVersion& ver);
 512
 513     /**
 514         The age component.
 515     */
 516     const int age;
 517
 518     /**
 519         The version component.
 520     */
 521     const int version;
 522 };
 523