interface/wx/ribbon/art.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/art.h
   3 // Purpose:     interface of wxRibbonArtProvider
   4 // Author:      Peter Cawley
   5 // Licence:     wxWindows licence
   6 ///////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Identifiers for common settings on ribbon art providers which can be used
  10     to tweak the appearance of the art provider.
  11
  12     @see wxRibbonArtProvider::GetColour()
  13     @see wxRibbonArtProvider::GetFont()
  14     @see wxRibbonArtProvider::GetMetric()
  15     @see wxRibbonArtProvider::SetColour()
  16     @see wxRibbonArtProvider::SetFont()
  17     @see wxRibbonArtProvider::SetMetric()
  18 */
  19 enum wxRibbonArtSetting
  20 {
  21     wxRIBBON_ART_TAB_SEPARATION_SIZE,
  22     wxRIBBON_ART_PAGE_BORDER_LEFT_SIZE,
  23     wxRIBBON_ART_PAGE_BORDER_TOP_SIZE,
  24     wxRIBBON_ART_PAGE_BORDER_RIGHT_SIZE,
  25     wxRIBBON_ART_PAGE_BORDER_BOTTOM_SIZE,
  26     wxRIBBON_ART_PANEL_X_SEPARATION_SIZE,
  27     wxRIBBON_ART_PANEL_Y_SEPARATION_SIZE,
  28     wxRIBBON_ART_TOOL_GROUP_SEPARATION_SIZE,
  29     wxRIBBON_ART_GALLERY_BITMAP_PADDING_LEFT_SIZE,
  30     wxRIBBON_ART_GALLERY_BITMAP_PADDING_RIGHT_SIZE,
  31     wxRIBBON_ART_GALLERY_BITMAP_PADDING_TOP_SIZE,
  32     wxRIBBON_ART_GALLERY_BITMAP_PADDING_BOTTOM_SIZE,
  33     wxRIBBON_ART_PANEL_LABEL_FONT,
  34     wxRIBBON_ART_BUTTON_BAR_LABEL_FONT,
  35     wxRIBBON_ART_TAB_LABEL_FONT,
  36     wxRIBBON_ART_BUTTON_BAR_LABEL_COLOUR,
  37     /// @since 2.9.5
  38     wxRIBBON_ART_BUTTON_BAR_LABEL_DISABLED_COLOUR,
  39     wxRIBBON_ART_BUTTON_BAR_HOVER_BORDER_COLOUR,
  40     wxRIBBON_ART_BUTTON_BAR_HOVER_BACKGROUND_TOP_COLOUR,
  41     wxRIBBON_ART_BUTTON_BAR_HOVER_BACKGROUND_TOP_GRADIENT_COLOUR,
  42     wxRIBBON_ART_BUTTON_BAR_HOVER_BACKGROUND_COLOUR,
  43     wxRIBBON_ART_BUTTON_BAR_HOVER_BACKGROUND_GRADIENT_COLOUR,
  44     wxRIBBON_ART_BUTTON_BAR_ACTIVE_BORDER_COLOUR,
  45     wxRIBBON_ART_BUTTON_BAR_ACTIVE_BACKGROUND_TOP_COLOUR,
  46     wxRIBBON_ART_BUTTON_BAR_ACTIVE_BACKGROUND_TOP_GRADIENT_COLOUR,
  47     wxRIBBON_ART_BUTTON_BAR_ACTIVE_BACKGROUND_COLOUR,
  48     wxRIBBON_ART_BUTTON_BAR_ACTIVE_BACKGROUND_GRADIENT_COLOUR,
  49     wxRIBBON_ART_GALLERY_BORDER_COLOUR,
  50     wxRIBBON_ART_GALLERY_HOVER_BACKGROUND_COLOUR,
  51     wxRIBBON_ART_GALLERY_BUTTON_BACKGROUND_COLOUR,
  52     wxRIBBON_ART_GALLERY_BUTTON_BACKGROUND_GRADIENT_COLOUR,
  53     wxRIBBON_ART_GALLERY_BUTTON_BACKGROUND_TOP_COLOUR,
  54     wxRIBBON_ART_GALLERY_BUTTON_FACE_COLOUR,
  55     wxRIBBON_ART_GALLERY_BUTTON_HOVER_BACKGROUND_COLOUR,
  56     wxRIBBON_ART_GALLERY_BUTTON_HOVER_BACKGROUND_GRADIENT_COLOUR,
  57     wxRIBBON_ART_GALLERY_BUTTON_HOVER_BACKGROUND_TOP_COLOUR,
  58     wxRIBBON_ART_GALLERY_BUTTON_HOVER_FACE_COLOUR,
  59     wxRIBBON_ART_GALLERY_BUTTON_ACTIVE_BACKGROUND_COLOUR,
  60     wxRIBBON_ART_GALLERY_BUTTON_ACTIVE_BACKGROUND_GRADIENT_COLOUR,
  61     wxRIBBON_ART_GALLERY_BUTTON_ACTIVE_BACKGROUND_TOP_COLOUR,
  62     wxRIBBON_ART_GALLERY_BUTTON_ACTIVE_FACE_COLOUR,
  63     wxRIBBON_ART_GALLERY_BUTTON_DISABLED_BACKGROUND_COLOUR,
  64     wxRIBBON_ART_GALLERY_BUTTON_DISABLED_BACKGROUND_GRADIENT_COLOUR,
  65     wxRIBBON_ART_GALLERY_BUTTON_DISABLED_BACKGROUND_TOP_COLOUR,
  66     wxRIBBON_ART_GALLERY_BUTTON_DISABLED_FACE_COLOUR,
  67     wxRIBBON_ART_GALLERY_ITEM_BORDER_COLOUR,
  68     wxRIBBON_ART_TAB_LABEL_COLOUR,
  69     wxRIBBON_ART_TAB_SEPARATOR_COLOUR,
  70     wxRIBBON_ART_TAB_SEPARATOR_GRADIENT_COLOUR,
  71     wxRIBBON_ART_TAB_CTRL_BACKGROUND_COLOUR,
  72     wxRIBBON_ART_TAB_CTRL_BACKGROUND_GRADIENT_COLOUR,
  73     wxRIBBON_ART_TAB_HOVER_BACKGROUND_TOP_COLOUR,
  74     wxRIBBON_ART_TAB_HOVER_BACKGROUND_TOP_GRADIENT_COLOUR,
  75     wxRIBBON_ART_TAB_HOVER_BACKGROUND_COLOUR,
  76     wxRIBBON_ART_TAB_HOVER_BACKGROUND_GRADIENT_COLOUR,
  77     wxRIBBON_ART_TAB_ACTIVE_BACKGROUND_TOP_COLOUR,
  78     wxRIBBON_ART_TAB_ACTIVE_BACKGROUND_TOP_GRADIENT_COLOUR,
  79     wxRIBBON_ART_TAB_ACTIVE_BACKGROUND_COLOUR,
  80     wxRIBBON_ART_TAB_ACTIVE_BACKGROUND_GRADIENT_COLOUR,
  81     wxRIBBON_ART_TAB_BORDER_COLOUR,
  82     wxRIBBON_ART_PANEL_BORDER_COLOUR,
  83     wxRIBBON_ART_PANEL_BORDER_GRADIENT_COLOUR,
  84     wxRIBBON_ART_PANEL_MINIMISED_BORDER_COLOUR,
  85     wxRIBBON_ART_PANEL_MINIMISED_BORDER_GRADIENT_COLOUR,
  86     wxRIBBON_ART_PANEL_LABEL_BACKGROUND_COLOUR,
  87     wxRIBBON_ART_PANEL_LABEL_BACKGROUND_GRADIENT_COLOUR,
  88     wxRIBBON_ART_PANEL_LABEL_COLOUR,
  89     wxRIBBON_ART_PANEL_HOVER_LABEL_BACKGROUND_COLOUR,
  90     wxRIBBON_ART_PANEL_HOVER_LABEL_BACKGROUND_GRADIENT_COLOUR,
  91     wxRIBBON_ART_PANEL_HOVER_LABEL_COLOUR,
  92     wxRIBBON_ART_PANEL_MINIMISED_LABEL_COLOUR,
  93     wxRIBBON_ART_PANEL_ACTIVE_BACKGROUND_TOP_COLOUR,
  94     wxRIBBON_ART_PANEL_ACTIVE_BACKGROUND_TOP_GRADIENT_COLOUR,
  95     wxRIBBON_ART_PANEL_ACTIVE_BACKGROUND_COLOUR,
  96     wxRIBBON_ART_PANEL_ACTIVE_BACKGROUND_GRADIENT_COLOUR,
  97     wxRIBBON_ART_PAGE_BORDER_COLOUR,
  98     wxRIBBON_ART_PAGE_BACKGROUND_TOP_COLOUR,
  99     wxRIBBON_ART_PAGE_BACKGROUND_TOP_GRADIENT_COLOUR,
 100     wxRIBBON_ART_PAGE_BACKGROUND_COLOUR,
 101     wxRIBBON_ART_PAGE_BACKGROUND_GRADIENT_COLOUR,
 102     wxRIBBON_ART_PAGE_HOVER_BACKGROUND_TOP_COLOUR,
 103     wxRIBBON_ART_PAGE_HOVER_BACKGROUND_TOP_GRADIENT_COLOUR,
 104     wxRIBBON_ART_PAGE_HOVER_BACKGROUND_COLOUR,
 105     wxRIBBON_ART_PAGE_HOVER_BACKGROUND_GRADIENT_COLOUR,
 106     wxRIBBON_ART_TOOLBAR_BORDER_COLOUR,
 107     wxRIBBON_ART_TOOLBAR_HOVER_BORDER_COLOUR,
 108     wxRIBBON_ART_TOOLBAR_FACE_COLOUR,
 109     wxRIBBON_ART_TOOL_BACKGROUND_TOP_COLOUR,
 110     wxRIBBON_ART_TOOL_BACKGROUND_TOP_GRADIENT_COLOUR,
 111     wxRIBBON_ART_TOOL_BACKGROUND_COLOUR,
 112     wxRIBBON_ART_TOOL_BACKGROUND_GRADIENT_COLOUR,
 113     wxRIBBON_ART_TOOL_HOVER_BACKGROUND_TOP_COLOUR,
 114     wxRIBBON_ART_TOOL_HOVER_BACKGROUND_TOP_GRADIENT_COLOUR,
 115     wxRIBBON_ART_TOOL_HOVER_BACKGROUND_COLOUR,
 116     wxRIBBON_ART_TOOL_HOVER_BACKGROUND_GRADIENT_COLOUR,
 117     wxRIBBON_ART_TOOL_ACTIVE_BACKGROUND_TOP_COLOUR,
 118     wxRIBBON_ART_TOOL_ACTIVE_BACKGROUND_TOP_GRADIENT_COLOUR,
 119     wxRIBBON_ART_TOOL_ACTIVE_BACKGROUND_COLOUR,
 120     wxRIBBON_ART_TOOL_ACTIVE_BACKGROUND_GRADIENT_COLOUR,
 121 };
 122
 123 /**
 124     Flags used to describe the direction, state, and/or purpose of a
 125     ribbon-style scroll button.
 126
 127     @see wxRibbonArtProvider::DrawScrollButton()
 128     @see wxRibbonArtProvider::GetScrollButtonMinimumSize()
 129 */
 130 enum wxRibbonScrollButtonStyle
 131 {
 132     wxRIBBON_SCROLL_BTN_LEFT = 0, /**< Button will scroll to the left. */
 133     wxRIBBON_SCROLL_BTN_RIGHT = 1, /**< Button will scroll to the right. */
 134     wxRIBBON_SCROLL_BTN_UP = 2, /**< Button will scroll upward. */
 135     wxRIBBON_SCROLL_BTN_DOWN = 3, /**< Button will scroll downward. */
 136
 137   /** A mask to extract direction from a combination of flags. */
 138     wxRIBBON_SCROLL_BTN_DIRECTION_MASK = 3,
 139
 140     wxRIBBON_SCROLL_BTN_NORMAL = 0, /**< Button is not active or hovered. */
 141     wxRIBBON_SCROLL_BTN_HOVERED = 4, /**< Button has a cursor hovering over it. */
 142     wxRIBBON_SCROLL_BTN_ACTIVE = 8, /**< Button is being pressed. */
 143
 144   /** A mask to extract state from a combination of flags. */
 145     wxRIBBON_SCROLL_BTN_STATE_MASK = 12,
 146
 147     wxRIBBON_SCROLL_BTN_FOR_OTHER = 0, /**< Button is not for scrolling tabs nor pages. */
 148     wxRIBBON_SCROLL_BTN_FOR_TABS = 16, /**< Button is for scrolling tabs. */
 149     wxRIBBON_SCROLL_BTN_FOR_PAGE = 32, /**< Button is for scrolling pages. */
 150
 151   /** A mask to extract purpose from a combination of flags. */
 152     wxRIBBON_SCROLL_BTN_FOR_MASK = 48,
 153 };
 154
 155 /**
 156     Buttons on a ribbon button bar and tools on a ribbon tool bar can each be
 157     one of three different kinds.
 158 */
 159 enum wxRibbonButtonKind
 160 {
 161     /**
 162         Normal button or tool with a clickable area which causes some generic
 163         action.
 164     */
 165     wxRIBBON_BUTTON_NORMAL    = 1 << 0,
 166
 167     /**
 168         Dropdown button or tool with a clickable area which typically causes a
 169         dropdown menu.
 170     */
 171     wxRIBBON_BUTTON_DROPDOWN  = 1 << 1,
 172
 173     /**
 174         Button or tool with two clickable areas - one which causes a dropdown
 175         menu, and one which causes a generic action.
 176     */
 177     wxRIBBON_BUTTON_HYBRID    = wxRIBBON_BUTTON_NORMAL | wxRIBBON_BUTTON_DROPDOWN,
 178
 179     /**
 180         Normal button or tool with a clickable area which toggles the button
 181         between a pressed and unpressed state.
 182     */
 183     wxRIBBON_BUTTON_TOGGLE    = 1 << 2
 184 };
 185
 186 /**
 187     @class wxRibbonArtProvider
 188
 189     wxRibbonArtProvider is responsible for drawing all the components of the ribbon
 190     interface. This allows a ribbon bar to have a pluggable look-and-feel, while
 191     retaining the same underlying behaviour. As a single art provider is used for
 192     all ribbon components, a ribbon bar usually has a consistent (though unique)
 193     appearance.
 194
 195     By default, a wxRibbonBar uses an instance of this class called
 196     @c wxRibbonDefaultArtProvider, which resolves to @c wxRibbonAUIArtProvider,
 197     @c wxRibbonMSWArtProvider, or @c wxRibbonOSXArtProvider - whichever is most appropriate
 198     to the current platform. These art providers are all slightly configurable with
 199     regard to colours and fonts, but for larger modifications, you can derive from
 200     one of these classes, or write a completely new art provider class.
 201     Call wxRibbonBar::SetArtProvider to change the art provider being used.
 202
 203     @library{wxribbon}
 204     @category{ribbon}
 205
 206     @see wxRibbonBar
 207 */
 208 class wxRibbonArtProvider
 209 {
 210 public:
 211     /**
 212         Constructor.
 213     */
 214     wxRibbonArtProvider();
 215
 216     /**
 217         Destructor.
 218     */
 219     virtual ~wxRibbonArtProvider();
 220
 221     /**
 222         Create a new art provider which is a clone of this one.
 223     */
 224     virtual wxRibbonArtProvider* Clone() const = 0;
 225
 226     /**
 227         Set the style flags.
 228
 229         Normally called automatically by wxRibbonBar::SetArtProvider with the ribbon
 230         bar's style flags, so that the art provider has the same flags as the bar which
 231         it is serving.
 232     */
 233     virtual void SetFlags(long flags) = 0;
 234
 235     /**
 236         Get the previously set style flags.
 237     */
 238     virtual long GetFlags() const = 0;
 239
 240     /**
 241         Get the value of a certain integer setting.
 242         @a id can be one of the size values of @ref wxRibbonArtSetting.
 243     */
 244     virtual int GetMetric(int id) const = 0;
 245
 246     /**
 247         Set the value of a certain integer setting to the value @e new_val.
 248         @a id can be one of the size values of @ref wxRibbonArtSetting.
 249     */
 250     virtual void SetMetric(int id, int new_val) = 0;
 251
 252     /**
 253         Set the value of a certain font setting to the value @e font.
 254         @a id can be one of the font values of @ref wxRibbonArtSetting.
 255     */
 256     virtual void SetFont(int id, const wxFont& font) = 0;
 257
 258     /**
 259         Get the value of a certain font setting.
 260         @a id can be one of the font values of @ref wxRibbonArtSetting.
 261     */
 262     virtual wxFont GetFont(int id) const = 0;
 263
 264     /**
 265         Get the value of a certain colour setting.
 266         @a id can be one of the colour values of @ref wxRibbonArtSetting.
 267     */
 268     virtual wxColour GetColour(int id) const = 0;
 269
 270     /**
 271         Set the value of a certain colour setting to the value @e colour.
 272         @a id can be one of the colour values of @ref wxRibbonArtSetting, though
 273         not all colour settings will have an effect on every art provider.
 274
 275         @see SetColourScheme()
 276     */
 277     virtual void SetColour(int id, const wxColor& colour) = 0;
 278
 279     /**
 280         @see wxRibbonArtProvider::GetColour()
 281     */
 282     wxColour GetColor(int id) const;
 283
 284     /**
 285         @see wxRibbonArtProvider::SetColour()
 286     */
 287     void SetColor(int id, const wxColour& color);
 288
 289     /**
 290         Get the current colour scheme.
 291
 292         Returns three colours such that if SetColourScheme() were called with
 293         them, the colour scheme would be restored to what it was when
 294         SetColourScheme() was last called. In practice, this usually means that
 295         the returned values are the three colours given in the last call to
 296         SetColourScheme(), however if SetColourScheme() performs an idempotent
 297         operation upon the colours it is given (like clamping a component of
 298         the colour), then the returned values may not be the three colours
 299         given in the last call to SetColourScheme().
 300         If SetColourScheme() has not been called, then the returned values
 301         should result in a colour scheme similar to, if not identical to, the
 302         default colours of the art provider.
 303         Note that if SetColour() is called, then GetColourScheme() does not try
 304         and return a colour scheme similar to colours being used - it's return
 305         values are dependent upon the last values given to SetColourScheme(),
 306         as described above.
 307
 308         @param[out] primary
 309             Pointer to a location to store the primary colour, or NULL.
 310         @param[out] secondary
 311             Pointer to a location to store the secondary colour, or NULL.
 312         @param[out] tertiary
 313             Pointer to a location to store the tertiary colour, or NULL.
 314     */
 315     virtual void GetColourScheme(wxColour* primary,
 316                         wxColour* secondary,
 317                         wxColour* tertiary) const = 0;
 318
 319     /**
 320         Set all applicable colour settings from a few base colours.
 321
 322         Uses any or all of the three given colours to create a colour scheme,
 323         and then sets all colour settings which are relevant to the art
 324         provider using that scheme.
 325         Note that some art providers may not use the tertiary colour for
 326         anything, and some may not use the secondary colour either.
 327
 328         @see SetColour()
 329         @see GetColourScheme()
 330     */
 331     virtual void SetColourScheme(const wxColour& primary,
 332                         const wxColour& secondary,
 333                         const wxColour& tertiary) = 0;
 334
 335     /**
 336         Draw the background of the tab region of a ribbon bar.
 337
 338         @param dc
 339             The device context to draw onto.
 340         @param wnd
 341             The window which is being drawn onto.
 342         @param rect
 343             The rectangle within which to draw.
 344     */
 345     virtual void DrawTabCtrlBackground(
 346                         wxDC& dc,
 347                         wxWindow* wnd,
 348                         const wxRect& rect) = 0;
 349
 350     /**
 351         Draw a single tab in the tab region of a ribbon bar.
 352
 353         @param dc
 354             The device context to draw onto.
 355         @param wnd
 356             The window which is being drawn onto (not the wxRibbonPage
 357             associated with the tab being drawn).
 358         @param tab
 359             The rectangle within which to draw, and also the tab label, icon,
 360             and state (active and/or hovered). The drawing rectangle will be
 361             entirely within a rectangle on the same device context previously
 362             painted with DrawTabCtrlBackground(). The rectangle's width will
 363             be at least the minimum value returned by GetBarTabWidth(), and
 364             height will be the value returned by GetTabCtrlHeight().
 365     */
 366     virtual void DrawTab(wxDC& dc,
 367                         wxWindow* wnd,
 368                         const wxRibbonPageTabInfo& tab) = 0;
 369
 370     /**
 371         Draw a separator between two tabs in a ribbon bar.
 372
 373         @param dc
 374             The device context to draw onto.
 375         @param wnd
 376             The window which is being drawn onto.
 377         @param rect
 378             The rectangle within which to draw, which will be entirely within a
 379             rectangle on the same device context previously painted with
 380             DrawTabCtrlBackground().
 381         @param visibility
 382             The opacity with which to draw the separator. Values are in the range
 383             [0, 1], with 0 being totally transparent, and 1 being totally opaque.
 384     */
 385     virtual void DrawTabSeparator(wxDC& dc,
 386                         wxWindow* wnd,
 387                         const wxRect& rect,
 388                         double visibility) = 0;
 389
 390     /**
 391         Draw the background of a ribbon page.
 392
 393         @param dc
 394             The device context to draw onto.
 395         @param wnd
 396             The window which is being drawn onto (which is commonly the wxRibbonPage
 397             whose background is being drawn, but doesn't have to be).
 398         @param rect
 399             The rectangle within which to draw.
 400
 401         @sa GetPageBackgroundRedrawArea
 402     */
 403     virtual void DrawPageBackground(
 404                         wxDC& dc,
 405                         wxWindow* wnd,
 406                         const wxRect& rect) = 0;
 407
 408     /**
 409         Draw a ribbon-style scroll button.
 410
 411         @param dc
 412             The device context to draw onto.
 413         @param wnd
 414             The window which is being drawn onto.
 415         @param rect
 416             The rectangle within which to draw. The size of this rectangle
 417             will be at least the size returned by GetScrollButtonMinimumSize()
 418             for a scroll button with the same style. For tab scroll buttons,
 419             this rectangle will be entirely within a rectangle on the same
 420             device context previously painted with DrawTabCtrlBackground(), but
 421             this is not guaranteed for other types of button (for example,
 422             page scroll buttons will not be painted on an area previously
 423             painted with DrawPageBackground()).
 424         @param style
 425             A combination of flags from @ref wxRibbonScrollButtonStyle, including
 426             a direction, a for flag, and one or more states.
 427     */
 428     virtual void DrawScrollButton(
 429                         wxDC& dc,
 430                         wxWindow* wnd,
 431                         const wxRect& rect,
 432                         long style) = 0;
 433
 434     /**
 435         Draw the background and chrome for a ribbon panel. This should draw
 436         the border, background, label, and any other items of a panel which
 437         are outside the client area of a panel.
 438
 439         Note that when a panel is minimised, this function is not called - only
 440         DrawMinimisedPanel() is called, so a background should be explicitly
 441         painted by that if required.
 442
 443         @param dc
 444             The device context to draw onto.
 445         @param wnd
 446             The window which is being drawn onto, which is always the panel
 447             whose background and chrome is being drawn. The panel label and
 448             other panel attributes can be obtained by querying this.
 449         @param rect
 450             The rectangle within which to draw.
 451     */
 452     virtual void DrawPanelBackground(
 453                         wxDC& dc,
 454                         wxRibbonPanel* wnd,
 455                         const wxRect& rect) = 0;
 456
 457     /**
 458         Draw the background and chrome for a wxRibbonGallery control. This
 459         should draw the border, background, scroll buttons, extension button,
 460         and any other UI elements which are not attached to a specific gallery
 461         item.
 462
 463         @param dc
 464             The device context to draw onto.
 465         @param wnd
 466             The window which is being drawn onto, which is always the gallery
 467             whose background and chrome is being drawn. Attributes used during
 468             drawing like the gallery hover state and individual button states
 469             can be queried from this parameter by wxRibbonGallery::IsHovered(),
 470             wxRibbonGallery::GetExtensionButtonState(),
 471             wxRibbonGallery::GetUpButtonState(), and
 472             wxRibbonGallery::GetDownButtonState().
 473         @param rect
 474             The rectangle within which to draw. This rectangle is the entire
 475             area of the gallery control, not just the client rectangle.
 476     */
 477     virtual void DrawGalleryBackground(
 478                         wxDC& dc,
 479                         wxRibbonGallery* wnd,
 480                         const wxRect& rect) = 0;
 481
 482     /**
 483         Draw the background of a single item in a wxRibbonGallery control. This
 484         is painted on top of a gallery background, and behind the items bitmap.
 485         Unlike DrawButtonBarButton() and DrawTool(), it is not expected to draw
 486         the item bitmap - that is done by the gallery control itself.
 487
 488         @param dc
 489             The device context to draw onto.
 490         @param wnd
 491             The window which is being drawn onto, which is always the gallery
 492             which contains the item being drawn.
 493         @param rect
 494             The rectangle within which to draw. The size of this rectangle will
 495             be the size of the item's bitmap, expanded by gallery item padding
 496             values (wxRIBBON_ART_GALLERY_BITMAP_PADDING_LEFT_SIZE,
 497             wxRIBBON_ART_GALLERY_BITMAP_PADDING_RIGHT_SIZE,
 498             wxRIBBON_ART_GALLERY_BITMAP_PADDING_TOP_SIZE, and
 499             wxRIBBON_ART_GALLERY_BITMAP_PADDING_BOTTOM_SIZE). The drawing
 500             rectangle will be entirely within a rectangle on the same device
 501             context previously painted with DrawGalleryBackground().
 502         @param item
 503             The item whose background is being painted. Typically the
 504             background will vary if the item is hovered, active, or selected;
 505             wxRibbonGallery::GetSelection(), wxRibbonGallery::GetActiveItem(),
 506             and wxRibbonGallery::GetHoveredItem() can be called to test if the
 507             given item is in one of these states.
 508     */
 509     virtual void DrawGalleryItemBackground(
 510                         wxDC& dc,
 511                         wxRibbonGallery* wnd,
 512                         const wxRect& rect,
 513                         wxRibbonGalleryItem* item) = 0;
 514
 515     /**
 516         Draw a minimised ribbon panel.
 517
 518         @param dc
 519             The device context to draw onto.
 520         @param wnd
 521             The window which is being drawn onto, which is always the panel
 522             which is minimised. The panel label can be obtained from this
 523             window. The minimised icon obtained from querying the window may
 524             not be the size requested by GetMinimisedPanelMinimumSize() - the
 525             @a bitmap argument contains the icon in the requested size.
 526         @param rect
 527             The rectangle within which to draw. The size of the rectangle will
 528             be at least the size returned by GetMinimisedPanelMinimumSize().
 529         @param bitmap
 530             A copy of the panel's minimised bitmap rescaled to the size
 531             returned by GetMinimisedPanelMinimumSize().
 532     */
 533     virtual void DrawMinimisedPanel(
 534                         wxDC& dc,
 535                         wxRibbonPanel* wnd,
 536                         const wxRect& rect,
 537                         wxBitmap& bitmap) = 0;
 538
 539     /**
 540         Draw the background for a wxRibbonButtonBar control.
 541
 542         @param dc
 543             The device context to draw onto.
 544         @param wnd
 545             The window which is being drawn onto (which will typically be the
 546             button bar itself, though this is not guaranteed).
 547         @param rect
 548             The rectangle within which to draw.
 549     */
 550     virtual void DrawButtonBarBackground(
 551                         wxDC& dc,
 552                         wxWindow* wnd,
 553                         const wxRect& rect) = 0;
 554
 555     /**
 556         Draw a single button for a wxRibbonButtonBar control.
 557
 558         @param dc
 559             The device context to draw onto.
 560         @param wnd
 561             The window which is being drawn onto.
 562         @param rect
 563             The rectangle within which to draw. The size of this rectangle will
 564             be a size previously returned by GetButtonBarButtonSize(), and the
 565             rectangle will be entirely within a rectangle on the same device
 566             context previously painted with DrawButtonBarBackground().
 567         @param kind
 568             The kind of button to draw (normal, dropdown or hybrid).
 569         @param state
 570             Combination of a size flag and state flags from the
 571             wxRibbonButtonBarButtonState enumeration.
 572         @param label
 573             The label of the button.
 574         @param bitmap_large
 575             The large bitmap of the button (or the large disabled bitmap when
 576             wxRIBBON_BUTTONBAR_BUTTON_DISABLED is set in @a state).
 577         @param bitmap_small
 578             The small bitmap of the button (or the small disabled bitmap when
 579             wxRIBBON_BUTTONBAR_BUTTON_DISABLED is set in @a state).
 580     */
 581     virtual void DrawButtonBarButton(
 582                         wxDC& dc,
 583                         wxWindow* wnd,
 584                         const wxRect& rect,
 585                         wxRibbonButtonBarButtonKind kind,
 586                         long state,
 587                         const wxString& label,
 588                         const wxBitmap& bitmap_large,
 589                         const wxBitmap& bitmap_small) = 0;
 590
 591     /**
 592         Draw the background for a wxRibbonToolBar control.
 593
 594         @param dc
 595             The device context to draw onto.
 596         @param wnd
 597             The which is being drawn onto. In most cases this will be a
 598             wxRibbonToolBar, but it doesn't have to be.
 599         @param rect
 600             The rectangle within which to draw. Some of this rectangle will
 601             later be drawn over using DrawToolGroupBackground() and DrawTool(),
 602             but not all of it will (unless there is only a single group of
 603             tools).
 604     */
 605     virtual void DrawToolBarBackground(
 606                         wxDC& dc,
 607                         wxWindow* wnd,
 608                         const wxRect& rect) = 0;
 609
 610     /**
 611         Draw the background for a group of tools on a wxRibbonToolBar control.
 612
 613         @param dc
 614             The device context to draw onto.
 615         @param wnd
 616             The window which is being drawn onto. In most cases this will be a
 617             wxRibbonToolBar, but it doesn't have to be.
 618         @param rect
 619             The rectangle within which to draw. This rectangle is a union of
 620             the individual tools' rectangles. As there are no gaps between
 621             tools, this rectangle will be painted over exactly once by calls to
 622             DrawTool(). The group background could therefore be painted by
 623             DrawTool(), though it can be conceptually easier and more efficient
 624             to draw it all at once here. The rectangle will be entirely within
 625             a rectangle on the same device context previously painted with
 626             DrawToolBarBackground().
 627     */
 628     virtual void DrawToolGroupBackground(
 629                         wxDC& dc,
 630                         wxWindow* wnd,
 631                         const wxRect& rect) = 0;
 632
 633     /**
 634         Draw a single tool (for a wxRibbonToolBar control).
 635
 636         @param dc
 637             The device context to draw onto.
 638         @param wnd
 639             The window which is being drawn onto. In most cases this will be a
 640             wxRibbonToolBar, but it doesn't have to be.
 641         @param rect
 642             The rectangle within which to draw. The size of this rectangle will
 643             at least the size returned by GetToolSize(), and the height of it
 644             will be equal for all tools within the same group. The rectangle
 645             will be entirely within a rectangle on the same device context
 646             previously painted with DrawToolGroupBackground().
 647         @param bitmap
 648             The bitmap to use as the tool's foreground. If the tool is a hybrid
 649             or dropdown tool, then the foreground should also contain a
 650             standard dropdown button.
 651         @param kind
 652             The kind of tool to draw (normal, dropdown, or hybrid).
 653         @param state
 654             A combination of wxRibbonToolBarToolState flags giving the state of
 655             the tool and it's relative position within a tool group.
 656     */
 657     virtual void DrawTool(
 658                         wxDC& dc,
 659                         wxWindow* wnd,
 660                         const wxRect& rect,
 661                         const wxBitmap& bitmap,
 662                         wxRibbonButtonKind kind,
 663                         long state) = 0;
 664
 665     /**
 666         Draw toggle button on wxRibbonBar. This should draw a small toggle button
 667         at top right corner of ribbon bar.
 668
 669         @param dc
 670             The device context to draw onto.
 671         @param wnd
 672             The window which is being drawn onto, which is always the panel
 673             whose background and chrome is being drawn. The panel label and
 674             other panel attributes can be obtained by querying this.
 675         @param rect
 676             The rectangle within which to draw.
 677         @param mode
 678             The wxRibbonDisplayMode which should be applied to display button
 679
 680         @since 2.9.5
 681     */
 682     virtual void DrawToggleButton(wxDC& dc,
 683                                   wxRibbonBar* wnd,
 684                                   const wxRect& rect,
 685                                   wxRibbonDisplayMode mode) = 0;
 686
 687     /**
 688         Draw help button on wxRibbonBar. This should draw a help button
 689         at top right corner of ribbon bar.
 690
 691         @param dc
 692             The device context to draw onto.
 693         @param wnd
 694             The window which is being drawn onto, which is always the panel
 695             whose background and chrome is being drawn. The panel label and
 696             other panel attributes can be obtained by querying this.
 697         @param rect
 698             The rectangle within which to draw.
 699
 700         @since 2.9.5
 701     */
 702     virtual void DrawHelpButton(wxDC& dc,
 703                                 wxRibbonBar* wnd,
 704                                 const wxRect& rect) = 0;
 705
 706     /**
 707         Calculate the ideal and minimum width (in pixels) of a tab in a ribbon
 708         bar.
 709
 710         @param dc
 711             A device context to use when one is required for size calculations.
 712         @param wnd
 713             The window onto which the tab will eventually be drawn.
 714         @param label
 715             The tab's label (or wxEmptyString if it has none).
 716         @param bitmap
 717             The tab's icon (or wxNullBitmap if it has none).
 718         @param[out] ideal
 719             The ideal width (in pixels) of the tab.
 720         @param[out] small_begin_need_separator
 721             A size less than the @a ideal size, at which a tab separator should
 722             begin to be drawn (i.e. drawn, but still fairly transparent).
 723         @param[out] small_must_have_separator
 724             A size less than the @a small_begin_need_separator size, at which a
 725             tab separator must be drawn (i.e. drawn at full opacity).
 726         @param[out] minimum
 727             A size less than the @a small_must_have_separator size, and greater
 728             than or equal to zero, which is the minimum pixel width for the tab.
 729     */
 730     virtual void GetBarTabWidth(
 731                         wxDC& dc,
 732                         wxWindow* wnd,
 733                         const wxString& label,
 734                         const wxBitmap& bitmap,
 735                         int* ideal,
 736                         int* small_begin_need_separator,
 737                         int* small_must_have_separator,
 738                         int* minimum) = 0;
 739
 740     /**
 741         Calculate the height (in pixels) of the tab region of a ribbon bar.
 742         Note that as the tab region can contain scroll buttons, the height
 743         should be greater than or equal to the minimum height for a tab scroll
 744         button.
 745
 746         @param dc
 747             A device context to use when one is required for size calculations.
 748         @param wnd
 749             The window onto which the tabs will eventually be drawn.
 750         @param pages
 751             The tabs which will acquire the returned height.
 752     */
 753     virtual int GetTabCtrlHeight(
 754                         wxDC& dc,
 755                         wxWindow* wnd,
 756                         const wxRibbonPageTabInfoArray& pages) = 0;
 757
 758     /**
 759         Calculate the minimum size (in pixels) of a scroll button.
 760
 761         @param dc
 762             A device context to use when one is required for size calculations.
 763         @param wnd
 764             The window onto which the scroll button will eventually be drawn.
 765         @param style
 766             A combination of flags from @ref wxRibbonScrollButtonStyle, including
 767             a direction, and a for flag (state flags may be given too, but
 768             should be ignored, as a button should retain a constant size,
 769             regardless of its state).
 770     */
 771     virtual wxSize GetScrollButtonMinimumSize(
 772                         wxDC& dc,
 773                         wxWindow* wnd,
 774                         long style) = 0;
 775
 776     /**
 777         Calculate the size of a panel for a given client size. This should
 778         increment the given size by enough to fit the panel label and other
 779         chrome.
 780
 781         @param dc
 782             A device context to use if one is required for size calculations.
 783         @param wnd
 784             The ribbon panel in question.
 785         @param client_size
 786             The client size.
 787         @param[out] client_offset
 788             The offset where the client rectangle begins within the panel (may
 789             be NULL).
 790
 791         @sa GetPanelClientSize()
 792     */
 793     virtual wxSize GetPanelSize(
 794                         wxDC& dc,
 795                         const wxRibbonPanel* wnd,
 796                         wxSize client_size,
 797                         wxPoint* client_offset) = 0;
 798
 799     /**
 800         Calculate the client size of a panel for a given overall size. This
 801         should act as the inverse to GetPanelSize(), and decrement the given
 802         size by enough to fit the panel label and other chrome.
 803
 804         @param dc
 805             A device context to use if one is required for size calculations.
 806         @param wnd
 807             The ribbon panel in question.
 808         @param size
 809             The overall size to calculate client size for.
 810         @param[out] client_offset
 811             The offset where the returned client size begins within the given
 812             @a size (may be NULL).
 813
 814         @sa GetPanelSize()
 815     */
 816     virtual wxSize GetPanelClientSize(
 817                         wxDC& dc,
 818                         const wxRibbonPanel* wnd,
 819                         wxSize size,
 820                         wxPoint* client_offset) = 0;
 821
 822     /**
 823         Calculate the position and size of the panel extension button.
 824
 825         @param dc
 826             A device context to use if one is required for size calculations.
 827         @param wnd
 828             The ribbon panel in question.
 829         @param rect
 830             The panel rectangle from which calculate extension button rectangle.
 831
 832         @since 2.9.4
 833     */
 834     virtual wxRect GetPanelExtButtonArea(
 835                         wxDC& dc,
 836                         const wxRibbonPanel* wnd,
 837                         wxRect rect) = 0;
 838
 839     /**
 840         Calculate the size of a wxRibbonGallery control for a given client
 841         size. This should increment the given size by enough to fit the gallery
 842         border, buttons, and any other chrome.
 843
 844         @param dc
 845             A device context to use if one is required for size calculations.
 846         @param wnd
 847             The gallery in question.
 848         @param client_size
 849             The client size.
 850
 851         @sa GetGalleryClientSize()
 852     */
 853     virtual wxSize GetGallerySize(
 854                         wxDC& dc,
 855                         const wxRibbonGallery* wnd,
 856                         wxSize client_size) = 0;
 857
 858     /**
 859         Calculate the client size of a wxRibbonGallery control for a given
 860         size. This should act as the inverse to GetGallerySize(), and decrement
 861         the given size by enough to fir the gallery border, buttons, and other
 862         chrome.
 863
 864         @param dc
 865             A device context to use if one is required for size calculations.
 866         @param wnd
 867             The gallery in question.
 868         @param size
 869             The overall size to calculate the client size for.
 870         @param[out] client_offset
 871             The position within the given size at which the returned client
 872             size begins.
 873         @param[out] scroll_up_button
 874             The rectangle within the given size which the scroll up button
 875             occupies.
 876         @param[out] scroll_down_button
 877             The rectangle within the given size which the scroll down button
 878             occupies.
 879         @param[out] extension_button
 880             The rectangle within the given size which the extension button
 881             occupies.
 882     */
 883     virtual wxSize GetGalleryClientSize(
 884                         wxDC& dc,
 885                         const wxRibbonGallery* wnd,
 886                         wxSize size,
 887                         wxPoint* client_offset,
 888                         wxRect* scroll_up_button,
 889                         wxRect* scroll_down_button,
 890                         wxRect* extension_button) = 0;
 891
 892     /**
 893         Calculate the portion of a page background which needs to be redrawn
 894         when a page is resized. To optimise the drawing of page backgrounds, as
 895         small an area as possible should be returned. Of course, if the way in
 896         which a background is drawn means that the entire background needs to
 897         be repainted on resize, then the entire new size should be returned.
 898
 899         @param dc
 900             A device context to use when one is required for size calculations.
 901         @param wnd
 902             The page which is being resized.
 903         @param page_old_size
 904             The size of the page prior to the resize (which has already been
 905             painted).
 906         @param page_new_size
 907             The size of the page after the resize.
 908     */
 909     virtual wxRect GetPageBackgroundRedrawArea(
 910                         wxDC& dc,
 911                         const wxRibbonPage* wnd,
 912                         wxSize page_old_size,
 913                         wxSize page_new_size) = 0;
 914
 915     /**
 916         Calculate the size of a button within a wxRibbonButtonBar.
 917
 918         @param dc
 919             A device context to use when one is required for size calculations.
 920         @param wnd
 921             The window onto which the button will eventually be drawn (which is
 922             normally a wxRibbonButtonBar, though this is not guaranteed).
 923         @param kind
 924             The kind of button.
 925         @param size
 926             The size-class to calculate the size for. Buttons on a button bar
 927             can have three distinct sizes: wxRIBBON_BUTTONBAR_BUTTON_SMALL,
 928             wxRIBBON_BUTTONBAR_BUTTON_MEDIUM, and wxRIBBON_BUTTONBAR_BUTTON_LARGE.
 929             If the requested size-class is not applicable, then @false should
 930             be returned.
 931         @param label
 932             The label of the button.
 933         @param bitmap_size_large
 934             The size of all "large" bitmaps on the button bar.
 935         @param bitmap_size_small
 936             The size of all "small" bitmaps on the button bar.
 937         @param[out] button_size
 938             The size, in pixels, of the button.
 939         @param[out] normal_region
 940             The region of the button which constitutes the normal button.
 941         @param[out] dropdown_region
 942             The region of the button which constitutes the dropdown button.
 943
 944         @return @true if a size exists for the button, @false otherwise.
 945     */
 946     virtual bool GetButtonBarButtonSize(
 947                         wxDC& dc,
 948                         wxWindow* wnd,
 949                         wxRibbonButtonBarButtonKind kind,
 950                         wxRibbonButtonBarButtonState size,
 951                         const wxString& label,
 952                         wxSize bitmap_size_large,
 953                         wxSize bitmap_size_small,
 954                         wxSize* button_size,
 955                         wxRect* normal_region,
 956                         wxRect* dropdown_region) = 0;
 957
 958     /**
 959         Calculate the size of a minimised ribbon panel.
 960
 961         @param dc
 962             A device context to use when one is required for size calculations.
 963         @param wnd
 964             The ribbon panel in question. Attributes like the panel label can
 965             be queried from this.
 966         @param[out] desired_bitmap_size
 967             Optional parameter which is filled with the size of the bitmap
 968             suitable for a minimised ribbon panel.
 969         @param[out] expanded_panel_direction
 970             Optional parameter which is filled with the direction of the
 971             minimised panel (@c wxEAST or @c wxSOUTH depending on the style).
 972     */
 973     virtual wxSize GetMinimisedPanelMinimumSize(
 974                         wxDC& dc,
 975                         const wxRibbonPanel* wnd,
 976                         wxSize* desired_bitmap_size,
 977                         wxDirection* expanded_panel_direction) = 0;
 978
 979     /**
 980         Calculate the size of a tool within a wxRibbonToolBar.
 981
 982         @param dc
 983             A device context to use when one is required for size calculations.
 984         @param wnd
 985             The window onto which the tool will eventually be drawn.
 986         @param bitmap_size
 987             The size of the tool's foreground bitmap.
 988         @param kind
 989             The kind of tool (normal, dropdown, or hybrid).
 990         @param is_first
 991             @true if the tool is the first within its group. @false otherwise.
 992         @param is_last
 993             @true if the tool is the last within its group. @false otherwise.
 994         @param[out] dropdown_region
 995             For dropdown and hybrid tools, the region within the returned
 996             size which counts as the dropdown part.
 997     */
 998     virtual wxSize GetToolSize(
 999                         wxDC& dc,
1000                         wxWindow* wnd,
1001                         wxSize bitmap_size,
1002                         wxRibbonButtonKind kind,
1003                         bool is_first,
1004                         bool is_last,
1005                         wxRect* dropdown_region) = 0;
1006
1007     /**
1008         Calculate the position and size of the ribbon's toggle button.
1009
1010         @param rect
1011             The ribbon bar rectangle from which calculate toggle button rectangle.
1012
1013         @since 2.9.5
1014     */
1015     virtual wxRect GetBarToggleButtonArea(const wxRect& rect) = 0;
1016
1017     /**
1018         Calculate the position and size of the ribbon's help button.
1019
1020         @param rect
1021             The ribbon bar rectangle from which calculate help button rectangle.
1022
1023         @since 2.9.5
1024     */
1025     virtual wxRect GetRibbonHelpButtonArea(const wxRect& rect) = 0;
1026 };