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