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 the bitmap should be big enough to always cover the entire
 117         banner, e.g. for a horizontal banner with wxTOP style its width should
 118         be bigger than any reasonable window size.
 119
 120         For wxLEFT orientation the bitmap is truncated from the top, for wxTOP
 121         and wxBOTTOM -- from the right and for wxRIGHT -- from the bottom, so
 122         put the most important part of the bitmap information in the opposite
 123         direction.
 124
 125         If no valid background bitmap is specified, the banner draws gradient
 126         background but if a valid bitmap is given here, the gradient is not
 127         draw and the start and end colours specified for it are ignored.
 128
 129         @param bmp Bitmap to use as background. May be invalid to indicate
 130             that no background bitmap should be used.
 131      */
 132     void SetBitmap(const wxBitmap& bmp);
 133
 134     /**
 135         Set the text to display.
 136
 137         This is mutually exclusive with SetBitmap().
 138
 139         Title is rendered in bold and should be single line, message can have
 140         multiple lines but is not wrapped automatically, include explicit line
 141         breaks in the string if you want to have multiple lines.
 142      */
 143     void SetText(const wxString& title, const wxString& message);
 144
 145     /**
 146         Set the colours between which the gradient runs.
 147
 148         The gradient colours are ignored if SetBitmap() is used.
 149      */
 150     void SetGradient(const wxColour& start, const wxColour& end);
 151 };