interface/wx/ribbon/page.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/page.h
   3 // Purpose:     interface of wxRibbonPage
   4 // Author:      Peter Cawley
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 ///////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRibbonPage
  11
  12     Container for related ribbon panels, and a tab within a ribbon bar.
  13
  14     @see wxRibbonBar
  15     @see wxRibbonPanel
  16
  17     @library{wxribbon}
  18     @category{ribbon}
  19 */
  20 class wxRibbonPage : public wxRibbonControl
  21 {
  22 public:
  23     /**
  24         Default constructor.
  25         With this constructor, Create() should be called in order to create
  26         the ribbon page.
  27     */
  28     wxRibbonPage();
  29
  30     /**
  31         Constructs a ribbon page, which must be a child of a ribbon bar.
  32
  33         @param parent
  34             Pointer to a parent wxRibbonBar (unlike most controls, a wxRibbonPage
  35             can only have wxRibbonBar as a parent).
  36         @param id
  37             Window identifier.
  38         @param label
  39             Label to be used in the wxRibbonBar's tab list for this page (if the
  40             ribbon bar is set to display labels).
  41         @param icon
  42             Icon to be used in the wxRibbonBar's tab list for this page (if the
  43             ribbon bar is set to display icons).
  44         @param style
  45             Currently unused, should be zero.
  46     */
  47     wxRibbonPage(wxRibbonBar* parent,
  48                 wxWindowID id = wxID_ANY,
  49                 const wxString& label = wxEmptyString,
  50                 const wxBitmap& icon = wxNullBitmap,
  51                 long style = 0);
  52
  53     /**
  54         Destructor.
  55     */
  56     virtual ~wxRibbonPage();
  57
  58     /**
  59         Create a ribbon page in two-step ribbon page construction.
  60         Should only be called when the default constructor is used, and
  61         arguments have the same meaning as in the full constructor.
  62     */
  63     bool Create(wxRibbonBar* parent,
  64                 wxWindowID id = wxID_ANY,
  65                 const wxString& label = wxEmptyString,
  66                 const wxBitmap& icon = wxNullBitmap,
  67                 long style = 0);
  68
  69     /**
  70         Set the art provider to be used. Normally called automatically by
  71         wxRibbonBar when the page is created, or the art provider changed on the
  72         bar.
  73
  74         The new art provider will be propagated to the children of the page.
  75     */
  76     void SetArtProvider(wxRibbonArtProvider* art);
  77
  78     /**
  79         Get the icon used for the page in the ribbon bar tab area (only
  80         displayed if the ribbon bar is actually showing icons).
  81     */
  82     wxBitmap& GetIcon();
  83
  84     /**
  85         Set the size of the page and the external scroll buttons (if any).
  86
  87         When a page is too small to display all of its children, scroll buttons
  88         will appear (and if the page is sized up enough, they will disappear again).
  89         Slightly counter-intuitively, these buttons are created as siblings of the
  90         page rather than children of the page (to achieve correct cropping and
  91         paint ordering of the children and the buttons). When there are no scroll
  92         buttons, this function behaves the same as SetSize(), however when there
  93         are scroll buttons, it positions them at the edges of the given area, and
  94         then calls SetSize() with the remaining area.
  95
  96         This is provided as a separate function to SetSize() rather than within
  97         the implementation of SetSize(), as interacting algorithms may not expect
  98         SetSize() to also set the size of siblings.
  99     */
 100     void SetSizeWithScrollButtonAdjustment(int x, int y, int width, int height);
 101
 102     /**
 103         Expand a rectangle of the page to include external scroll buttons (if
 104         any). When no scroll buttons are shown, has no effect.
 105
 106         @param[in,out] rect
 107             The rectangle to adjust. The width and height will not be reduced,
 108             and the x and y will not be increased.
 109     */
 110     void AdjustRectToIncludeScrollButtons(wxRect* rect) const;
 111
 112     /**
 113         Dismiss the current externally expanded panel, if there is one.
 114
 115         When a ribbon panel automatically minimises, it can be externally
 116         expanded into a floating window. When the user clicks a button in such
 117         a panel, the panel should generally re-minimise. Event handlers for
 118         buttons on ribbon panels should call this method to achieve this
 119         behaviour.
 120
 121         @return @true if a panel was minimised, @false otherwise.
 122     */
 123     bool DismissExpandedPanel();
 124
 125     /**
 126         Perform a full re-layout of all panels on the page.
 127
 128         Should be called after panels are added to the page, or the sizing
 129         behaviour of a panel on the page changes (i.e. due to children being
 130         added to it). Usually called automatically when wxRibbonBar::Realize()
 131         is called.
 132
 133         Will invoke wxRibbonPanel::Realize() for all child panels.
 134     */
 135     virtual bool Realize();
 136
 137     /**
 138         Scroll the page by some amount up / down / left / right.
 139
 140         When the page's children are too big to fit in the onscreen area given to
 141         the page, scroll buttons will appear, and the page can be programmatically
 142         scrolled. Positive values of @a lines will scroll right or down, while
 143         negative values will scroll up or left (depending on the direction in which
 144         panels are stacked). A line is equivalent to a constant number of pixels.
 145
 146         @return @true if the page scrolled at least one pixel in the given
 147             direction, @false if it did not scroll.
 148
 149         @see GetMajorAxis()
 150         @see ScrollPixels()
 151         @see ScrollSections()
 152     */
 153     virtual bool ScrollLines(int lines);
 154
 155     /**
 156         Scroll the page by a set number of pixels up / down / left / right.
 157
 158         When the page's children are too big to fit in the onscreen area given to
 159         the page, scroll buttons will appear, and the page can be programmatically
 160         scrolled. Positive values of @a lines will scroll right or down, while
 161         negative values will scroll up or left (depending on the direction in which
 162         panels are stacked).
 163
 164         @return @true if the page scrolled at least one pixel in the given
 165             direction, @false if it did not scroll.
 166
 167         @see GetMajorAxis()
 168         @see ScrollLines()
 169         @see ScrollSections()
 170     */
 171     bool ScrollPixels(int pixels);
 172
 173     /**
 174         Scroll the page by an entire child section.
 175
 176         The @a sections parameter value should be 1 or -1. This will scroll
 177         enough to uncover a partially visible child section or totally uncover
 178         the next child section that may not be visible at all.
 179
 180         @return @true if the page scrolled at least one pixel in the given
 181             direction, @false if it did not scroll.
 182
 183         @see ScrollPixels()
 184         @see ScrollSections()
 185
 186         @since 2.9.5
 187     */
 188     bool ScrollSections(int sections);
 189
 190     /**
 191         Get the direction in which ribbon panels are stacked within the page.
 192
 193         This is controlled by the style of the containing wxRibbonBar, meaning
 194         that all pages within a bar will have the same major axis. As well as
 195         being the direction in which panels are stacked, it is also the axis in
 196         which scrolling will occur (when required).
 197
 198         @return wxHORIZONTAL or wxVERTICAL (never wxBOTH).
 199     */
 200     wxOrientation GetMajorAxis() const;
 201 };