interface/wx/ribbon/page.h

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