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     */
 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     */
 169     bool ScrollPixels(int pixels);
 170
 171     /**
 172         Get the direction in which ribbon panels are stacked within the page.
 173
 174         This is controlled by the style of the containing wxRibbonBar, meaning
 175         that all pages within a bar will have the same major axis. As well as
 176         being the direction in which panels are stacked, it is also the axis in
 177         which scrolling will occur (when required).
 178
 179         @return wxHORIZONTAL or wxVERTICAL (never wxBOTH).
 180     */
 181     wxOrientation GetMajorAxis() const;
 182 };