interface/wx/bannerwindow.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        interface/wx/bannerwindow.h
   3 // Purpose:     wxBannerWindow class documentation
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-08-16
   6 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     A simple banner window showing either a bitmap or text.
  12
  13     Banner windows can be used to present some overview of the current window
  14     contents to the user in an aesthetically pleasant way. They are typically
  15     positioned along the left or top edge of the window (although this class
  16     also supports right- and bottom-aligned banners) and show either a bitmap
  17     with a logo or a few lines of text on a gradient-filled background.
  18
  19     Using this class is very simple, e.g.:
  20     @code
  21     MyFrame::MyFrame(...)
  22     {
  23         ... create the frame itself ...
  24
  25         // Create and initialize the banner.
  26         wxBannerWindow* banner = new wxBannerWindow(this, wxTOP);
  27         banner->SetText("Welcome to my wonderful program",
  28                         "  Before doing anything else, you need to connect to "
  29                         "the online server.\n"
  30                         "  Please enter your credentials in the controls below.");
  31
  32         // And position it along the left edge of the window.
  33         wxSizer* sizer = new wxBoxSizer(wxVERTICAL);
  34         sizer->Add(banner, wxSizerFlags().Expand());
  35
  36         ... add the rest of the window contents to the same sizer ...
  37
  38         SetSizerAndFit(sizer);
  39     }
  40     @endcode
  41
  42     This class is currently implemented generically and so looks the same under
  43     all platforms.
  44
  45     @library{wxadv}
  46     @category{miscwnd}
  47     @genericAppearance{bannerwindow}
  48
  49     @since 2.9.3
  50  */
  51 class wxBannerWindow : public wxWindow
  52 {
  53 public:
  54     /**
  55         Default constructor, use Create() later.
  56
  57         This constructor is only used for two-step creation, if possible,
  58         prefer using the constructor below directly instead of using this one
  59         and calling Create() later.
  60      */
  61     wxBannerWindow();
  62
  63     /**
  64         Convenient constructor that should be used in the majority of cases.
  65
  66         The only really important arguments of the full constructor below are
  67         @a parent and @a dir so this class provides a convenient constructor
  68         taking only them.
  69
  70         The banner orientation changes how the text in it is displayed and also
  71         defines where is the bitmap truncated if it's too big to fit but doesn't
  72         do anything for the banner position, this is supposed to be taken care
  73         of in the usual way, e.g. using sizers.
  74     */
  75     wxBannerWindow(wxWindow* parent, wxDirection dir = wxLEFT);
  76
  77     /**
  78         Full constructor provided for consistency with the other classes only.
  79
  80         Prefer to use the shorter constructor documented above. You should
  81         rarely, if ever, need to use non-default values for any other
  82         parameters: as the banner window doesn't generate any events, its
  83         identifier is not particularly useful; its position and size will be
  84         almost always managed by the containing sizer and it doesn't have any
  85         specific styles. So only the parent and the banner direction need to be
  86         specified.
  87      */
  88     wxBannerWindow(wxWindow* parent,
  89                    wxWindowID winid,
  90                    wxDirection dir = wxLEFT,
  91                    const wxPoint& pos = wxDefaultPosition,
  92                    const wxSize& size = wxDefaultSize,
  93                    long style = 0,
  94                    const wxString& name = wxBannerWindowNameStr);
  95
  96     /**
  97         Really create the banner window for the objects created using the
  98         default constructor.
  99
 100         It's an error to call Create() for the objects created using
 101         non-default constructor.
 102      */
 103     bool Create(wxWindow* parent,
 104                 wxWindowID winid,
 105                 wxDirection dir = wxLEFT,
 106                 const wxPoint& pos = wxDefaultPosition,
 107                 const wxSize& size = wxDefaultSize,
 108                 long style = 0,
 109                 const wxString& name = wxBannerWindowNameStr);
 110
 111
 112     /**
 113         Provide the bitmap to use as background.
 114
 115         Notice that ideally the bitmap should be big enough to always cover the
 116         entire banner, e.g. for a horizontal banner with wxTOP style its width
 117         should be bigger than any reasonable window size. Otherwise the bitmap
 118         is extended to cover the entire window area with a solid colour taken
 119         from the bitmap pixel on the edge in which direction the extension
 120         occurs so all bitmap pixels on this edge (top for wxLEFT, right for
 121         wxTOP and wxBOTTOM and bottom for wxRIGHT) should have the same colour
 122         to avoid jarring discontinuity.
 123
 124         If, on the other hand, the bitmap is bigger than the window size, then
 125         it is truncated. For wxLEFT orientation the bitmap is truncated from
 126         the top, for wxTOP and wxBOTTOM -- from the right and for wxRIGHT --
 127         from the bottom, so put the most important part of the bitmap
 128         information in the opposite direction where it will never be truncated.
 129
 130         If no valid background bitmap is specified, the banner draws gradient
 131         background but if a valid bitmap is given here, the gradient is not
 132         draw and the start and end colours specified for it are ignored.
 133
 134         @param bmp Bitmap to use as background. May be invalid to indicate
 135             that no background bitmap should be used.
 136      */
 137     void SetBitmap(const wxBitmap& bmp);
 138
 139     /**
 140         Set the text to display.
 141
 142         This is mutually exclusive with SetBitmap().
 143
 144         Title is rendered in bold and should be single line, message can have
 145         multiple lines but is not wrapped automatically, include explicit line
 146         breaks in the string if you want to have multiple lines.
 147      */
 148     void SetText(const wxString& title, const wxString& message);
 149
 150     /**
 151         Set the colours between which the gradient runs.
 152
 153         The gradient colours are ignored if SetBitmap() is used.
 154      */
 155     void SetGradient(const wxColour& start, const wxColour& end);
 156 };