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