interface/wx/ribbon/control.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/control.h
   3 // Purpose:     interface of wxRibbonControl
   4 // Author:      Peter Cawley
   5 // Licence:     wxWindows licence
   6 ///////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxRibbonControl
  10
  11     wxRibbonControl serves as a base class for all controls which share the
  12     ribbon characteristics of having a ribbon art provider, and (optionally)
  13     non-continuous resizing. Despite what the name may imply, it is not the
  14     top-level control for creating a ribbon interface - that is wxRibbonBar.
  15
  16     Ribbon controls often have a region which is "transparent", and shows the
  17     contents of the ribbon page or panel behind it. If implementing a new
  18     ribbon control, then it may be useful to realise that this effect is done
  19     by the art provider when painting the background of the control, and hence
  20     in the paint handler for the new control, you should call a draw background
  21     method on the art provider (wxRibbonArtProvider::DrawButtonBarBackground()
  22     and wxRibbonArtProvider::DrawToolBarBackground() typically just redraw what
  23     is behind the rectangle being painted) if you want transparent regions.
  24
  25     @library{wxribbon}
  26     @category{ribbon}
  27 */
  28 class wxRibbonControl : public wxControl
  29 {
  30 public:
  31     /**
  32         Constructor.
  33     */
  34     wxRibbonControl();
  35
  36     /**
  37         Constructor.
  38
  39         If @a parent is a wxRibbonControl with a non-NULL art provider, then
  40         the art provider of new control is set to that of @a parent.
  41     */
  42     wxRibbonControl(wxWindow *parent, wxWindowID id,
  43                     const wxPoint& pos = wxDefaultPosition,
  44                     const wxSize& size = wxDefaultSize, long style = 0,
  45                     const wxValidator& validator = wxDefaultValidator,
  46                     const wxString& name = wxControlNameStr);
  47
  48     /**
  49         Set the art provider to be used. In many cases, setting the art provider
  50         will also set the art provider on all child windows which extend
  51         wxRibbonControl.
  52
  53         In most cases, controls will not take ownership of the given pointer,
  54         with the notable exception being wxRibbonBar::SetArtProvider().
  55     */
  56     virtual void SetArtProvider(wxRibbonArtProvider* art);
  57
  58     /**
  59         Get the art provider to be used. Note that until an art provider has
  60         been set in some way, this function may return NULL.
  61     */
  62     wxRibbonArtProvider* GetArtProvider() const;
  63
  64     /**
  65         @return @true if this window can take any size (greater than its minimum
  66         size), @false if it can only take certain sizes.
  67
  68         @see GetNextSmallerSize()
  69         @see GetNextLargerSize()
  70     */
  71     virtual bool IsSizingContinuous() const;
  72
  73     /**
  74         If sizing is not continuous, then return a suitable size for the control
  75         which is smaller than the current size.
  76
  77         @param direction
  78             The direction(s) in which the size should reduce.
  79         @return
  80             The current size if there is no smaller size, otherwise a suitable
  81             size which is smaller in the given direction(s), and the same as the
  82             current size in the other direction (if any).
  83
  84         @see IsSizingContinuous()
  85     */
  86     wxSize GetNextSmallerSize(wxOrientation direction) const;
  87
  88     /**
  89         If sizing is not continuous, then return a suitable size for the control
  90         which is smaller than the given size.
  91
  92         @param direction
  93             The direction(s) in which the size should reduce.
  94         @param relative_to
  95             The size for which a smaller size should be found.
  96         @return
  97             @a relative_to if there is no smaller size, otherwise a suitable
  98             size which is smaller in the given direction(s), and the same as
  99             @a relative_to in the other direction (if any).
 100
 101         @see IsSizingContinuous()
 102         @see DoGetNextSmallerSize()
 103     */
 104     wxSize GetNextSmallerSize(wxOrientation direction, wxSize relative_to) const;
 105
 106     /**
 107         If sizing is not continuous, then return a suitable size for the control
 108         which is larger than the current size.
 109
 110         @param direction
 111             The direction(s) in which the size should increase.
 112         @return
 113             The current size if there is no larger size, otherwise a suitable
 114             size which is larger in the given direction(s), and the same as the
 115             current size in the other direction (if any).
 116
 117         @see IsSizingContinuous()
 118     */
 119     wxSize GetNextLargerSize(wxOrientation direction) const;
 120
 121     /**
 122         If sizing is not continuous, then return a suitable size for the control
 123         which is larger than the given size.
 124
 125         @param direction
 126             The direction(s) in which the size should increase.
 127         @param relative_to
 128             The size for which a larger size should be found.
 129         @return
 130             @a relative_to if there is no larger size, otherwise a suitable
 131             size which is larger in the given direction(s), and the same as
 132             @a relative_to in the other direction (if any).
 133
 134         @see IsSizingContinuous()
 135         @see DoGetNextLargerSize()
 136     */
 137     wxSize GetNextLargerSize(wxOrientation direction, wxSize relative_to) const;
 138
 139     /**
 140         Perform initial size and layout calculations after children have been
 141         added, and/or realize children.
 142     */
 143     virtual bool Realize();
 144
 145     /**
 146         Alias for Realize().
 147     */
 148     bool Realise();
 149
 150     /**
 151         Get the first ancestor which is a wxRibbonBar (or derived) or NULL
 152         if not having such parent.
 153
 154         @since 2.9.4
 155      */
 156     virtual wxRibbonBar* GetAncestorRibbonBar()const;
 157
 158
 159     /**
 160         Finds the best width and height given the parent's width and height.
 161         Used to implement the wxRIBBON_PANEL_FLEXIBLE panel style.
 162     */
 163     virtual wxSize GetBestSizeForParentSize(const wxSize& parentSize) const;
 164 protected:
 165     /**
 166         Implementation of GetNextSmallerSize().
 167         Controls which have non-continuous sizing must override this virtual
 168         function rather than GetNextSmallerSize().
 169     */
 170     virtual wxSize DoGetNextSmallerSize(wxOrientation direction,
 171                                         wxSize relative_to) const;
 172
 173     /**
 174         Implementation of GetNextLargerSize().
 175         Controls which have non-continuous sizing must override this virtual
 176         function rather than GetNextLargerSize().
 177     */
 178     virtual wxSize DoGetNextLargerSize(wxOrientation direction,
 179                                        wxSize relative_to) const;
 180 };