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 /**
 180     @class wxRibbonArtProvider
 181
 182     wxRibbonArtProvider is responsible for drawing all the components of the ribbon
 183     interface. This allows a ribbon bar to have a pluggable look-and-feel, while
 184     retaining the same underlying behaviour. As a single art provider is used for
 185     all ribbon components, a ribbon bar usually has a consistent (though unique)
 186     appearance.
 187
 188     By default, a wxRibbonBar uses an instance of this class called
 189     wxRibbonDefaultArtProvider, which resolves to wxRibbonAUIArtProvider,
 190     wxRibbonMSWArtProvider, or wxRibbonOSXArtProvider - whichever is most appropriate
 191     to the current platform. These art providers are all slightly configurable with
 192     regard to colours and fonts, but for larger modifications, you can derive from
 193     one of these classes, or write a completely new art provider class.
 194     Call wxRibbonBar::SetArtProvider to change the art provider being used.
 195
 196     @library{wxribbon}
 197     @category{ribbon}
 198
 199     @see wxRibbonBar
 200 */
 201 class wxRibbonArtProvider
 202 {
 203 public:
 204     /**
 205         Constructor.
 206     */
 207     wxRibbonArtProvider();
 208
 209     /**
 210         Destructor.
 211     */
 212     virtual ~wxRibbonArtProvider();
 213
 214     /**
 215         Create a new art provider which is a clone of this one.
 216     */
 217     virtual wxRibbonArtProvider* Clone() const = 0;
 218
 219     /**
 220         Set the style flags.
 221
 222         Normally called automatically by wxRibbonBar::SetArtProvider with the ribbon
 223         bar's style flags, so that the art provider has the same flags as the bar which
 224         it is serving.
 225     */
 226     virtual void SetFlags(long flags) = 0;
 227
 228     /**
 229         Get the previously set style flags.
 230     */
 231     virtual long GetFlags() const = 0;
 232
 233     /**
 234         Get the value of a certain integer setting.
 235         @a id can be one of the size values of @ref wxRibbonArtSetting.
 236     */
 237     virtual int GetMetric(int id) const = 0;
 238
 239     /**
 240         Set the value of a certain integer setting to the value @e new_val.
 241         @a id can be one of the size values of @ref wxRibbonArtSetting.
 242     */
 243     virtual void SetMetric(int id, int new_val) = 0;
 244
 245     /**
 246         Set the value of a certain font setting to the value @e font.
 247         @a id can be one of the font values of @ref wxRibbonArtSetting.
 248     */
 249     virtual void SetFont(int id, const wxFont& font) = 0;
 250
 251     /**
 252         Get the value of a certain font setting.
 253         @a id can be one of the font values of @ref wxRibbonArtSetting.
 254     */
 255     virtual wxFont GetFont(int id) const = 0;
 256
 257     /**
 258         Get the value of a certain colour setting.
 259         @a id can be one of the colour values of @ref wxRibbonArtSetting.
 260     */
 261     virtual wxColour GetColour(int id) const = 0;
 262
 263     /**
 264         Set the value of a certain colour setting to the value @e colour.
 265         @a id can be one of the colour values of @ref wxRibbonArtSetting, though
 266         not all colour settings will have an affect on every art provider.
 267
 268         \see SetColourScheme()
 269     */
 270     virtual void SetColour(int id, const wxColor& colour) = 0;
 271
 272     /**
 273         \see wxRibbonArtProvider::GetColour()
 274     */
 275     wxColour GetColor(int id) const;
 276
 277     /**
 278         \see wxRibbonArtProvider::SetColour()
 279     */
 280     void SetColor(int id, const wxColour& color);
 281
 282     /**
 283         Get the current colour scheme.
 284
 285         Returns three colours such that if SetColourScheme() were called with
 286         them, the colour scheme would be restored to what it was when
 287         SetColourScheme() was last called. In practice, this usually means that
 288         the returned values are the three colours given in the last call to
 289         SetColourScheme(), however if SetColourScheme() performs an idempotent
 290         operation upon the colours it is given (like clamping a component of
 291         the colour), then the returned values may not be the three colours
 292         given in the last call to SetColourScheme().
 293         If SetColourScheme() has not been called, then the returned values
 294         should result in a colour scheme similar to, if not identical to, the
 295         default colours of the art provider.
 296         Note that if SetColour() is called, then GetColourScheme() does not try
 297         and return a colour scheme similar to colours being used - it's return
 298         values are dependant upon the last values given to SetColourScheme(),
 299         as described above.
 300
 301         \param[out] primary
 302             Pointer to a location to store the primary colour, or NULL.
 303         \param[out] secondary
 304             Pointer to a location to store the secondary colour, or NULL.
 305         \param[out] tertiary
 306             Pointer to a location to store the tertiary colour, or NULL.
 307     */
 308     virtual void GetColourScheme(wxColour* primary,
 309                         wxColour* secondary,
 310                         wxColour* tertiary) const = 0;
 311
 312     /**
 313         Set all applicable colour settings from a few base colours.
 314
 315         Uses any or all of the three given colours to create a colour scheme,
 316         and then sets all colour settings which are relevant to the art
 317         provider using that scheme.
 318         Note that some art providers may not use the tertiary colour for
 319         anything, and some may not use the secondary colour either.
 320
 321         \see SetColour()
 322         \see GetColourScheme()
 323     */
 324     virtual void SetColourScheme(const wxColour& primary,
 325                         const wxColour& secondary,
 326                         const wxColour& tertiary) = 0;
 327
 328     /**
 329         Draw the background of the tab region of a ribbon bar.
 330
 331         @param dc
 332             The device context to draw onto.
 333         @param wnd
 334             The window which is being drawn onto.
 335         @param rect
 336             The rectangle within which to draw.
 337     */
 338     virtual void DrawTabCtrlBackground(
 339                         wxDC& dc,
 340                         wxWindow* wnd,
 341                         const wxRect& rect) = 0;
 342
 343     /**
 344         Draw a single tab in the tab region of a ribbon bar.
 345
 346         @param dc
 347             The device context to draw onto.
 348         @param wnd
 349             The window which is being drawn onto (not the wxRibbonPage
 350             associated with the tab being drawn).
 351         @param tab
 352             The rectangle within which to draw, and also the tab label, icon,
 353             and state (active and/or hovered). The drawing rectangle will be
 354             entirely within a rectangle on the same device context previously
 355             painted with DrawTabCtrlBackground(). The rectangle's width will
 356             be at least the minimum value returned by GetBarTabWidth(), and
 357             height will be the value returned by GetTabCtrlHeight().
 358     */
 359     virtual void DrawTab(wxDC& dc,
 360                         wxWindow* wnd,
 361                         const wxRibbonPageTabInfo& tab) = 0;
 362
 363     /**
 364         Draw a separator between two tabs in a ribbon bar.
 365
 366         @param dc
 367             The device context to draw onto.
 368         @param wnd
 369             The window which is being drawn onto.
 370         @param rect
 371             The rectangle within which to draw, which will be entirely within a
 372             rectangle on the same device context previously painted with
 373             DrawTabCtrlBackground().
 374         @param visibility
 375             The opacity with which to draw the separator. Values are in the range
 376             [0, 1], with 0 being totally transparent, and 1 being totally opaque.
 377     */
 378     virtual void DrawTabSeparator(wxDC& dc,
 379                         wxWindow* wnd,
 380                         const wxRect& rect,
 381                         double visibility) = 0;
 382
 383     /**
 384         Draw the background of a ribbon page.
 385
 386         @param dc
 387             The device context to draw onto.
 388         @param wnd
 389             The window which is being drawn onto (which is commonly the wxRibbonPage
 390             whose background is being drawn, but doesn't have to be).
 391         @param rect
 392             The rectangle within which to draw.
 393
 394         @sa GetPageBackgroundRedrawArea
 395     */
 396     virtual void DrawPageBackground(
 397                         wxDC& dc,
 398                         wxWindow* wnd,
 399                         const wxRect& rect) = 0;
 400
 401     /**
 402         Draw a ribbon-style scroll button.
 403
 404         @param dc
 405             The device context to draw onto.
 406         @param wnd
 407             The window which is being drawn onto.
 408         @param rect
 409             The rectangle within which to draw. The size of this rectangle
 410             will be at least the size returned by GetScrollButtonMinimumSize()
 411             for a scroll button with the same style. For tab scroll buttons,
 412             this rectangle will be entirely within a rectangle on the same
 413             device context previously painted with DrawTabCtrlBackground(), but
 414             this is not guaranteed for other types of button (for example,
 415             page scroll buttons will not be painted on an area previously
 416             painted with DrawPageBackground()).
 417         @param style
 418             A combination of flags from @ref wxRibbonScrollButtonStyle, including
 419             a direction, a for flag, and one or more states.
 420     */
 421     virtual void DrawScrollButton(
 422                         wxDC& dc,
 423                         wxWindow* wnd,
 424                         const wxRect& rect,
 425                         long style) = 0;
 426
 427     /**
 428         Draw the background and chrome for a ribbon panel. This should draw
 429         the border, background, label, and any other items of a panel which
 430         are outside the client area of a panel.
 431
 432         Note that when a panel is minimised, this function is not called - only
 433         DrawMinimisedPanel() is called, so a background should be explicitly
 434         painted by that if required.
 435
 436         @param dc
 437             The device context to draw onto.
 438         @param wnd
 439             The window which is being drawn onto, which is always the panel
 440             whose background and chrome is being drawn. The panel label and
 441             other panel attributes can be obtained by querying this.
 442         @param rect
 443             The rectangle within which to draw.
 444     */
 445     virtual void DrawPanelBackground(
 446                         wxDC& dc,
 447                         wxRibbonPanel* wnd,
 448                         const wxRect& rect) = 0;
 449
 450     /**
 451         Draw the background and chrome for a wxRibbonGallery control. This
 452         should draw the border, brackground, scroll buttons, extension button,
 453         and any other UI elements which are not attached to a specific gallery
 454         item.
 455
 456         @param dc
 457             The device context to draw onto.
 458         @param wnd
 459             The window which is being drawn onto, which is always the gallery
 460             whose background and chrome is being drawn. Attributes used during
 461             drawing like the gallery hover state and individual button states
 462             can be queried from this parameter by wxRibbonGallery::IsHovered(),
 463             wxRibbonGallery::GetExtensionButtonState(),
 464             wxRibbonGallery::GetUpButtonState(), and
 465             wxRibbonGallery::GetDownButtonState().
 466         @param rect
 467             The rectangle within which to draw. This rectangle is the entire
 468             area of the gallery control, not just the client rectangle.
 469     */
 470     virtual void DrawGalleryBackground(
 471                         wxDC& dc,
 472                         wxRibbonGallery* wnd,
 473                         const wxRect& rect) = 0;
 474
 475     /**
 476         Draw the background of a single item in a wxRibbonGallery control. This
 477         is painted on top of a gallery background, and behind the items bitmap.
 478         Unlike DrawButtonBarButton() and DrawTool(), it is not expected to draw
 479         the item bitmap - that is done by the gallery control itself.
 480
 481         @param dc
 482             The device context to draw onto.
 483         @param wnd
 484             The window which is being drawn onto, which is always the gallery
 485             which contains the item being drawn.
 486         @param rect
 487             The rectangle within which to draw. The size of this rectangle will
 488             be the size of the item's bitmap, expanded by gallery item padding
 489             values (wxRIBBON_ART_GALLERY_BITMAP_PADDING_LEFT_SIZE,
 490             wxRIBBON_ART_GALLERY_BITMAP_PADDING_RIGHT_SIZE,
 491             wxRIBBON_ART_GALLERY_BITMAP_PADDING_TOP_SIZE, and
 492             wxRIBBON_ART_GALLERY_BITMAP_PADDING_BOTTOM_SIZE). The drawing
 493             rectangle will be entirely within a rectangle on the same device
 494             context previously painted with DrawGalleryBackground().
 495         @param item
 496             The item whose background is being painted. Typically the
 497             background will vary if the item is hovered, active, or selected;
 498             wxRibbonGallery::GetSelection(), wxRibbonGallery::GetActiveItem(),
 499             and wxRibbonGallery::GetHoveredItem() can be called to test if the
 500             given item is in one of these states.
 501     */
 502     virtual void DrawGalleryItemBackground(
 503                         wxDC& dc,
 504                         wxRibbonGallery* wnd,
 505                         const wxRect& rect,
 506                         wxRibbonGalleryItem* item) = 0;
 507
 508     /**
 509         Draw a minimised ribbon panel.
 510
 511         @param dc
 512             The device context to draw onto.
 513         @param wnd
 514             The window which is being drawn onto, which is always the panel
 515             which is minimised. The panel label can be obtained from this
 516             window. The minimised icon obtained from querying the window may
 517             not be the size requested by GetMinimisedPanelMinimumSize() - the
 518             @a bitmap argument contains the icon in the requested size.
 519         @param rect
 520             The rectangle within which to draw. The size of the rectangle will
 521             be at least the size returned by GetMinimisedPanelMinimumSize().
 522         @param bitmap
 523             A copy of the panel's minimised bitmap rescaled to the size
 524             returned by GetMinimisedPanelMinimumSize().
 525     */
 526     virtual void DrawMinimisedPanel(
 527                         wxDC& dc,
 528                         wxRibbonPanel* wnd,
 529                         const wxRect& rect,
 530                         wxBitmap& bitmap) = 0;
 531
 532     /**
 533         Draw the background for a wxRibbonButtonBar control.
 534
 535         @param dc
 536             The device context to draw onto.
 537         @param wnd
 538             The window which is being drawn onto (which will typically be the
 539             button bar itself, though this is not guaranteed).
 540         @param rect
 541             The rectangle within which to draw.
 542     */
 543     virtual void DrawButtonBarBackground(
 544                         wxDC& dc,
 545                         wxWindow* wnd,
 546                         const wxRect& rect) = 0;
 547
 548     /**
 549         Draw a single button for a wxRibbonButtonBar control.
 550
 551         @param dc
 552             The device context to draw onto.
 553         @param wnd
 554             The window which is being drawn onto.
 555         @param rect
 556             The rectangle within which to draw. The size of this rectangle will
 557             be a size previously returned by GetButtonBarButtonSize(), and the
 558             rectangle will be entirely within a rectangle on the same device
 559             context previously painted with DrawButtonBarBackground().
 560         @param kind
 561             The kind of button to draw (normal, dropdown or hybrid).
 562         @param state
 563             Combination of a size flag and state flags from the
 564             wxRibbonButtonBarButtonState enumeration.
 565         @param label
 566             The label of the button.
 567         @param bitmap_large
 568             The large bitmap of the button (or the large disabled bitmap when
 569             wxRIBBON_BUTTONBAR_BUTTON_DISABLED is set in @a state).
 570         @param bitmap_small
 571             The small bitmap of the button (or the small disabled bitmap when
 572             wxRIBBON_BUTTONBAR_BUTTON_DISABLED is set in @a state).
 573     */
 574     virtual void DrawButtonBarButton(
 575                         wxDC& dc,
 576                         wxWindow* wnd,
 577                         const wxRect& rect,
 578                         wxRibbonButtonBarButtonKind kind,
 579                         long state,
 580                         const wxString& label,
 581                         const wxBitmap& bitmap_large,
 582                         const wxBitmap& bitmap_small) = 0;
 583
 584     /**
 585         Draw the background for a wxRibbonToolBar control.
 586
 587         @param dc
 588             The device context to draw onto.
 589         @param wnd
 590             The which is being drawn onto. In most cases this will be a
 591             wxRibbonToolBar, but it doesn't have to be.
 592         @param rect
 593             The rectangle within which to draw. Some of this rectangle will
 594             later be drawn over using DrawToolGroupBackground() and DrawTool(),
 595             but not all of it will (unless there is only a single group of
 596             tools).
 597     */
 598     virtual void DrawToolBarBackground(
 599                         wxDC& dc,
 600                         wxWindow* wnd,
 601                         const wxRect& rect) = 0;
 602
 603     /**
 604         Draw the background for a group of tools on a wxRibbonToolBar control.
 605
 606         @param dc
 607             The device context to draw onto.
 608         @param wnd
 609             The window which is being drawn onto. In most cases this will be a
 610             wxRibbonToolBar, but it doesn't have to be.
 611         @param rect
 612             The rectangle within which to draw. This rectangle is a union of
 613             the individual tools' rectangles. As there are no gaps between
 614             tools, this rectangle will be painted over exactly once by calls to
 615             DrawTool(). The group background could therefore be painted by
 616             DrawTool(), though it can be conceptually easier and more efficient
 617             to draw it all at once here. The rectangle will be entirely within
 618             a rectangle on the same device context previously painted with
 619             DrawToolBarBackground().
 620     */
 621     virtual void DrawToolGroupBackground(
 622                         wxDC& dc,
 623                         wxWindow* wnd,
 624                         const wxRect& rect) = 0;
 625
 626     /**
 627         Draw a single tool (for a wxRibbonToolBar control).
 628
 629         @param dc
 630             The device context to draw onto.
 631         @param wnd
 632             The window which is being drawn onto. In most cases this will be a
 633             wxRibbonToolBar, but it doesn't have to be.
 634         @param rect
 635             The rectangle within which to draw. The size of this rectangle will
 636             at least the size returned by GetToolSize(), and the height of it
 637             will be equal for all tools within the same group. The rectangle
 638             will be entirely within a rectangle on the same device context
 639             previously painted with DrawToolGroupBackground().
 640         @param bitmap
 641             The bitmap to use as the tool's foreground. If the tool is a hybrid
 642             or dropdown tool, then the foreground should also contain a
 643             standard dropdown button.
 644         @param kind
 645             The kind of tool to draw (normal, dropdown, or hybrid).
 646         @param state
 647             A combination of wxRibbonToolBarToolState flags giving the state of
 648             the tool and it's relative position within a tool group.
 649     */
 650     virtual void DrawTool(
 651                         wxDC& dc,
 652                         wxWindow* wnd,
 653                         const wxRect& rect,
 654                         const wxBitmap& bitmap,
 655                         wxRibbonButtonKind kind,
 656                         long state) = 0;
 657
 658     /**
 659         Calculate the ideal and minimum width (in pixels) of a tab in a ribbon
 660         bar.
 661
 662         @param dc
 663             A device context to use when one is required for size calculations.
 664         @param wnd
 665             The window onto which the tab will eventually be drawn.
 666         @param label
 667             The tab's label (or wxEmptyString if it has none).
 668         @param bitmap
 669             The tab's icon (or wxNullBitmap if it has none).
 670         @param[out] ideal
 671             The ideal width (in pixels) of the tab.
 672         @param[out] small_begin_need_separator
 673             A size less than the @a ideal size, at which a tab separator should
 674             begin to be drawn (i.e. drawn, but still fairly transparent).
 675         @param[out] small_must_have_separator
 676             A size less than the @a small_begin_need_separator size, at which a
 677             tab separator must be drawn (i.e. drawn at full opacity).
 678         @param[out] minimum
 679             A size less than the @a small_must_have_separator size, and greater
 680             than or equal to zero, which is the minimum pixel width for the tab.
 681     */
 682     virtual void GetBarTabWidth(
 683                         wxDC& dc,
 684                         wxWindow* wnd,
 685                         const wxString& label,
 686                         const wxBitmap& bitmap,
 687                         int* ideal,
 688                         int* small_begin_need_separator,
 689                         int* small_must_have_separator,
 690                         int* minimum) = 0;
 691
 692     /**
 693         Calculate the height (in pixels) of the tab region of a ribbon bar.
 694         Note that as the tab region can contain scroll buttons, the height
 695         should be greater than or equal to the minimum height for a tab scroll
 696         button.
 697
 698         @param dc
 699             A device context to use when one is required for size calculations.
 700         @param wnd
 701             The window onto which the tabs will eventually be drawn.
 702         @param pages
 703             The tabs which will acquire the returned height.
 704     */
 705     virtual int GetTabCtrlHeight(
 706                         wxDC& dc,
 707                         wxWindow* wnd,
 708                         const wxRibbonPageTabInfoArray& pages) = 0;
 709
 710     /**
 711         Calculate the minimum size (in pixels) of a scroll button.
 712
 713         @param dc
 714             A device context to use when one is required for size calculations.
 715         @param wnd
 716             The window onto which the scroll button will eventually be drawn.
 717         @param style
 718             A combination of flags from @ref wxRibbonScrollButtonStyle, including
 719             a direction, and a for flag (state flags may be given too, but
 720             should be ignored, as a button should retain a constant size,
 721             regardless of its state).
 722     */
 723     virtual wxSize GetScrollButtonMinimumSize(
 724                         wxDC& dc,
 725                         wxWindow* wnd,
 726                         long style) = 0;
 727
 728     /**
 729         Calculate the size of a panel for a given client size. This should
 730         increment the given size by enough to fit the panel label and other
 731         chrome.
 732
 733         @param dc
 734             A device context to use if one is required for size calculations.
 735         @param wnd
 736             The ribbon panel in question.
 737         @param client_size
 738             The client size.
 739         @param[out] client_offset
 740             The offset where the client rectangle begins within the panel (may
 741             be NULL).
 742
 743         @sa GetPanelClientSize()
 744     */
 745     virtual wxSize GetPanelSize(
 746                         wxDC& dc,
 747                         const wxRibbonPanel* wnd,
 748                         wxSize client_size,
 749                         wxPoint* client_offset) = 0;
 750
 751     /**
 752         Calculate the client size of a panel for a given overall size. This
 753         should act as the inverse to GetPanelSize(), and decrement the given
 754         size by enough to fit the panel label and other chrome.
 755
 756         @param dc
 757             A device context to use if one is required for size calculations.
 758         @param wnd
 759             The ribbon panel in question.
 760         @param size
 761             The overall size to calculate client size for.
 762         @param[out] client_offset
 763             The offset where the returned client size begins within the given
 764             @a size (may be NULL).
 765
 766         @sa GetPanelSize()
 767     */
 768     virtual wxSize GetPanelClientSize(
 769                         wxDC& dc,
 770                         const wxRibbonPanel* wnd,
 771                         wxSize size,
 772                         wxPoint* client_offset) = 0;
 773
 774     /**
 775         Calculate the size of a wxRibbonGallery control for a given client
 776         size. This should increment the given size by enough to fit the gallery
 777         border, buttons, and any other chrome.
 778
 779         @param dc
 780             A device context to use if one is required for size calculations.
 781         @param wnd
 782             The gallery in question.
 783         @param client_size
 784             The client size.
 785
 786         @sa GetGalleryClientSize()
 787     */
 788     virtual wxSize GetGallerySize(
 789                         wxDC& dc,
 790                         const wxRibbonGallery* wnd,
 791                         wxSize client_size) = 0;
 792
 793     /**
 794         Calculate the client size of a wxRibbonGallery control for a given
 795         size. This should act as the inverse to GetGallerySize(), and decrement
 796         the given size by enough to fir the gallery border, buttons, and other
 797         chrome.
 798
 799         @param dc
 800             A device context to use if one is required for size calculations.
 801         @param wnd
 802             The gallery in question.
 803         @param size
 804             The overall size to calculate the client size for.
 805         @param[out] client_offset
 806             The position within the given size at which the returned client
 807             size begins.
 808         @param[out] scroll_up_button
 809             The rectangle within the given size which the scroll up button
 810             occupies.
 811         @param[out] scroll_down_button
 812             The rectangle within the given size which the scroll down button
 813             occupies.
 814         @param[out] extension_button
 815             The rectangle within the given size which the extension button
 816             occupies.
 817     */
 818     virtual wxSize GetGalleryClientSize(
 819                         wxDC& dc,
 820                         const wxRibbonGallery* wnd,
 821                         wxSize size,
 822                         wxPoint* client_offset,
 823                         wxRect* scroll_up_button,
 824                         wxRect* scroll_down_button,
 825                         wxRect* extension_button) = 0;
 826
 827     /**
 828         Calculate the portion of a page background which needs to be redrawn
 829         when a page is resized. To optimise the drawing of page backgrounds, as
 830         small an area as possible should be returned. Of couse, if the way in
 831         which a background is drawn means that the entire background needs to
 832         be repainted on resize, then the entire new size should be returned.
 833
 834         @param dc
 835             A device context to use when one is required for size calculations.
 836         @param wnd
 837             The page which is being resized.
 838         @param page_old_size
 839             The size of the page prior to the resize (which has already been
 840             painted).
 841         @param page_new_size
 842             The size of the page after the resize.
 843     */
 844     virtual wxRect GetPageBackgroundRedrawArea(
 845                         wxDC& dc,
 846                         const wxRibbonPage* wnd,
 847                         wxSize page_old_size,
 848                         wxSize page_new_size) = 0;
 849
 850     /**
 851         Calculate the size of a button within a wxRibbonButtonBar.
 852
 853         @param dc
 854             A device context to use when one is required for size calculations.
 855         @param wnd
 856             The window onto which the button will eventually be drawn (which is
 857             normally a wxRibbonButtonBar, though this is not guaranteed).
 858         @param kind
 859             The kind of button.
 860         @param size
 861             The size-class to calculate the size for. Buttons on a button bar
 862             can have three distinct sizes: wxRIBBON_BUTTONBAR_BUTTON_SMALL,
 863             wxRIBBON_BUTTONBAR_BUTTON_MEDIUM, and wxRIBBON_BUTTONBAR_BUTTON_LARGE.
 864             If the requested size-class is not applicable, then @false should
 865             be returned.
 866         @param label
 867             The label of the button.
 868         @param bitmap_size_large
 869             The size of all "large" bitmaps on the button bar.
 870         @param bitmap_size_small
 871             The size of all "small" bitmaps on the button bar.
 872         @param[out] button_size
 873             The size, in pixels, of the button.
 874         @param[out] normal_region
 875             The region of the button which constitutes the normal button.
 876         @param[out] dropdown_region
 877             The region of the button which constitutes the dropdown button.
 878
 879         @return @true if a size exists for the button, @false otherwise.
 880     */
 881     virtual bool GetButtonBarButtonSize(
 882                         wxDC& dc,
 883                         wxWindow* wnd,
 884                         wxRibbonButtonBarButtonKind kind,
 885                         wxRibbonButtonBarButtonState size,
 886                         const wxString& label,
 887                         wxSize bitmap_size_large,
 888                         wxSize bitmap_size_small,
 889                         wxSize* button_size,
 890                         wxRect* normal_region,
 891                         wxRect* dropdown_region) = 0;
 892
 893     /**
 894         Calculate the size of a minimised ribbon panel.
 895
 896         @param dc
 897             A device context to use when one is required for size calculations.
 898         @param wnd
 899             The ribbon panel in question. Attributes like the panel label can
 900             be queried from this.
 901         @param[out] desired_bitmap_size
 902
 903     */
 904     virtual wxSize GetMinimisedPanelMinimumSize(
 905                         wxDC& dc,
 906                         const wxRibbonPanel* wnd,
 907                         wxSize* desired_bitmap_size,
 908                         wxDirection* expanded_panel_direction) = 0;
 909
 910     /**
 911         Calculate the size of a tool within a wxRibbonToolBar.
 912
 913         @param dc
 914             A device context to use when one is required for size calculations.
 915         @param wnd
 916             The window onto which the tool will eventually be drawn.
 917         @param bitmap_size
 918             The size of the tool's foreground bitmap.
 919         @param kind
 920             The kind of tool (normal, dropdown, or hybrid).
 921         @param is_first
 922             @true if the tool is the first within its group. @false otherwise.
 923         @param is_last
 924             @true if the tool is the last within its group. @false otherwise.
 925         @param[out] dropdown_region
 926             For dropdown and hybrid tools, the region within the returned
 927             size which counts as the dropdown part.
 928     */
 929     virtual wxSize GetToolSize(
 930                         wxDC& dc,
 931                         wxWindow* wnd,
 932                         wxSize bitmap_size,
 933                         wxRibbonButtonKind kind,
 934                         bool is_first,
 935                         bool is_last,
 936                         wxRect* dropdown_region) = 0;
 937 };