interface/wx/ribbon/art.h

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