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 affect 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 dependant 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, brackground, 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         Calculate the ideal and minimum width (in pixels) of a tab in a ribbon
 666         bar.
 667
 668         @param dc
 669             A device context to use when one is required for size calculations.
 670         @param wnd
 671             The window onto which the tab will eventually be drawn.
 672         @param label
 673             The tab's label (or wxEmptyString if it has none).
 674         @param bitmap
 675             The tab's icon (or wxNullBitmap if it has none).
 676         @param[out] ideal
 677             The ideal width (in pixels) of the tab.
 678         @param[out] small_begin_need_separator
 679             A size less than the @a ideal size, at which a tab separator should
 680             begin to be drawn (i.e. drawn, but still fairly transparent).
 681         @param[out] small_must_have_separator
 682             A size less than the @a small_begin_need_separator size, at which a
 683             tab separator must be drawn (i.e. drawn at full opacity).
 684         @param[out] minimum
 685             A size less than the @a small_must_have_separator size, and greater
 686             than or equal to zero, which is the minimum pixel width for the tab.
 687     */
 688     virtual void GetBarTabWidth(
 689                         wxDC& dc,
 690                         wxWindow* wnd,
 691                         const wxString& label,
 692                         const wxBitmap& bitmap,
 693                         int* ideal,
 694                         int* small_begin_need_separator,
 695                         int* small_must_have_separator,
 696                         int* minimum) = 0;
 697
 698     /**
 699         Calculate the height (in pixels) of the tab region of a ribbon bar.
 700         Note that as the tab region can contain scroll buttons, the height
 701         should be greater than or equal to the minimum height for a tab scroll
 702         button.
 703
 704         @param dc
 705             A device context to use when one is required for size calculations.
 706         @param wnd
 707             The window onto which the tabs will eventually be drawn.
 708         @param pages
 709             The tabs which will acquire the returned height.
 710     */
 711     virtual int GetTabCtrlHeight(
 712                         wxDC& dc,
 713                         wxWindow* wnd,
 714                         const wxRibbonPageTabInfoArray& pages) = 0;
 715
 716     /**
 717         Calculate the minimum size (in pixels) of a scroll button.
 718
 719         @param dc
 720             A device context to use when one is required for size calculations.
 721         @param wnd
 722             The window onto which the scroll button will eventually be drawn.
 723         @param style
 724             A combination of flags from @ref wxRibbonScrollButtonStyle, including
 725             a direction, and a for flag (state flags may be given too, but
 726             should be ignored, as a button should retain a constant size,
 727             regardless of its state).
 728     */
 729     virtual wxSize GetScrollButtonMinimumSize(
 730                         wxDC& dc,
 731                         wxWindow* wnd,
 732                         long style) = 0;
 733
 734     /**
 735         Calculate the size of a panel for a given client size. This should
 736         increment the given size by enough to fit the panel label and other
 737         chrome.
 738
 739         @param dc
 740             A device context to use if one is required for size calculations.
 741         @param wnd
 742             The ribbon panel in question.
 743         @param client_size
 744             The client size.
 745         @param[out] client_offset
 746             The offset where the client rectangle begins within the panel (may
 747             be NULL).
 748
 749         @sa GetPanelClientSize()
 750     */
 751     virtual wxSize GetPanelSize(
 752                         wxDC& dc,
 753                         const wxRibbonPanel* wnd,
 754                         wxSize client_size,
 755                         wxPoint* client_offset) = 0;
 756
 757     /**
 758         Calculate the client size of a panel for a given overall size. This
 759         should act as the inverse to GetPanelSize(), and decrement the given
 760         size by enough to fit the panel label and other chrome.
 761
 762         @param dc
 763             A device context to use if one is required for size calculations.
 764         @param wnd
 765             The ribbon panel in question.
 766         @param size
 767             The overall size to calculate client size for.
 768         @param[out] client_offset
 769             The offset where the returned client size begins within the given
 770             @a size (may be NULL).
 771
 772         @sa GetPanelSize()
 773     */
 774     virtual wxSize GetPanelClientSize(
 775                         wxDC& dc,
 776                         const wxRibbonPanel* wnd,
 777                         wxSize size,
 778                         wxPoint* client_offset) = 0;
 779
 780     /**
 781         Calculate the size of a wxRibbonGallery control for a given client
 782         size. This should increment the given size by enough to fit the gallery
 783         border, buttons, and any other chrome.
 784
 785         @param dc
 786             A device context to use if one is required for size calculations.
 787         @param wnd
 788             The gallery in question.
 789         @param client_size
 790             The client size.
 791
 792         @sa GetGalleryClientSize()
 793     */
 794     virtual wxSize GetGallerySize(
 795                         wxDC& dc,
 796                         const wxRibbonGallery* wnd,
 797                         wxSize client_size) = 0;
 798
 799     /**
 800         Calculate the client size of a wxRibbonGallery control for a given
 801         size. This should act as the inverse to GetGallerySize(), and decrement
 802         the given size by enough to fir the gallery border, buttons, and other
 803         chrome.
 804
 805         @param dc
 806             A device context to use if one is required for size calculations.
 807         @param wnd
 808             The gallery in question.
 809         @param size
 810             The overall size to calculate the client size for.
 811         @param[out] client_offset
 812             The position within the given size at which the returned client
 813             size begins.
 814         @param[out] scroll_up_button
 815             The rectangle within the given size which the scroll up button
 816             occupies.
 817         @param[out] scroll_down_button
 818             The rectangle within the given size which the scroll down button
 819             occupies.
 820         @param[out] extension_button
 821             The rectangle within the given size which the extension button
 822             occupies.
 823     */
 824     virtual wxSize GetGalleryClientSize(
 825                         wxDC& dc,
 826                         const wxRibbonGallery* wnd,
 827                         wxSize size,
 828                         wxPoint* client_offset,
 829                         wxRect* scroll_up_button,
 830                         wxRect* scroll_down_button,
 831                         wxRect* extension_button) = 0;
 832
 833     /**
 834         Calculate the portion of a page background which needs to be redrawn
 835         when a page is resized. To optimise the drawing of page backgrounds, as
 836         small an area as possible should be returned. Of couse, if the way in
 837         which a background is drawn means that the entire background needs to
 838         be repainted on resize, then the entire new size should be returned.
 839
 840         @param dc
 841             A device context to use when one is required for size calculations.
 842         @param wnd
 843             The page which is being resized.
 844         @param page_old_size
 845             The size of the page prior to the resize (which has already been
 846             painted).
 847         @param page_new_size
 848             The size of the page after the resize.
 849     */
 850     virtual wxRect GetPageBackgroundRedrawArea(
 851                         wxDC& dc,
 852                         const wxRibbonPage* wnd,
 853                         wxSize page_old_size,
 854                         wxSize page_new_size) = 0;
 855
 856     /**
 857         Calculate the size of a button within a wxRibbonButtonBar.
 858
 859         @param dc
 860             A device context to use when one is required for size calculations.
 861         @param wnd
 862             The window onto which the button will eventually be drawn (which is
 863             normally a wxRibbonButtonBar, though this is not guaranteed).
 864         @param kind
 865             The kind of button.
 866         @param size
 867             The size-class to calculate the size for. Buttons on a button bar
 868             can have three distinct sizes: wxRIBBON_BUTTONBAR_BUTTON_SMALL,
 869             wxRIBBON_BUTTONBAR_BUTTON_MEDIUM, and wxRIBBON_BUTTONBAR_BUTTON_LARGE.
 870             If the requested size-class is not applicable, then @false should
 871             be returned.
 872         @param label
 873             The label of the button.
 874         @param bitmap_size_large
 875             The size of all "large" bitmaps on the button bar.
 876         @param bitmap_size_small
 877             The size of all "small" bitmaps on the button bar.
 878         @param[out] button_size
 879             The size, in pixels, of the button.
 880         @param[out] normal_region
 881             The region of the button which constitutes the normal button.
 882         @param[out] dropdown_region
 883             The region of the button which constitutes the dropdown button.
 884
 885         @return @true if a size exists for the button, @false otherwise.
 886     */
 887     virtual bool GetButtonBarButtonSize(
 888                         wxDC& dc,
 889                         wxWindow* wnd,
 890                         wxRibbonButtonBarButtonKind kind,
 891                         wxRibbonButtonBarButtonState size,
 892                         const wxString& label,
 893                         wxSize bitmap_size_large,
 894                         wxSize bitmap_size_small,
 895                         wxSize* button_size,
 896                         wxRect* normal_region,
 897                         wxRect* dropdown_region) = 0;
 898
 899     /**
 900         Calculate the size of a minimised ribbon panel.
 901
 902         @param dc
 903             A device context to use when one is required for size calculations.
 904         @param wnd
 905             The ribbon panel in question. Attributes like the panel label can
 906             be queried from this.
 907         @param[out] desired_bitmap_size
 908             Optional parameter which is filled with the size of the bitmap
 909             suitable for a minimised ribbon panel.
 910         @param[out] expanded_panel_direction
 911             Optional parameter which is filled with the direction of the
 912             minimised panel (@c wxEAST or @c wxSOUTH depending on the style).
 913     */
 914     virtual wxSize GetMinimisedPanelMinimumSize(
 915                         wxDC& dc,
 916                         const wxRibbonPanel* wnd,
 917                         wxSize* desired_bitmap_size,
 918                         wxDirection* expanded_panel_direction) = 0;
 919
 920     /**
 921         Calculate the size of a tool within a wxRibbonToolBar.
 922
 923         @param dc
 924             A device context to use when one is required for size calculations.
 925         @param wnd
 926             The window onto which the tool will eventually be drawn.
 927         @param bitmap_size
 928             The size of the tool's foreground bitmap.
 929         @param kind
 930             The kind of tool (normal, dropdown, or hybrid).
 931         @param is_first
 932             @true if the tool is the first within its group. @false otherwise.
 933         @param is_last
 934             @true if the tool is the last within its group. @false otherwise.
 935         @param[out] dropdown_region
 936             For dropdown and hybrid tools, the region within the returned
 937             size which counts as the dropdown part.
 938     */
 939     virtual wxSize GetToolSize(
 940                         wxDC& dc,
 941                         wxWindow* wnd,
 942                         wxSize bitmap_size,
 943                         wxRibbonButtonKind kind,
 944                         bool is_first,
 945                         bool is_last,
 946                         wxRect* dropdown_region) = 0;
 947 };