interface/wx/ribbon/control.h

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