include/wx/bannerwindow.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/bannerwindow.h
   3 // Purpose:     wxBannerWindow class declaration
   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 #ifndef _WX_BANNERWINDOW_H_
  12 #define _WX_BANNERWINDOW_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_BANNERWINDOW
  17
  18 #include "wx/bitmap.h"
  19 #include "wx/event.h"
  20 #include "wx/window.h"
  21
  22 class WXDLLIMPEXP_FWD_CORE wxBitmap;
  23 class WXDLLIMPEXP_FWD_CORE wxColour;
  24 class WXDLLIMPEXP_FWD_CORE wxDC;
  25
  26 extern WXDLLIMPEXP_DATA_ADV(const char) wxBannerWindowNameStr[];
  27
  28 // ----------------------------------------------------------------------------
  29 // A simple banner window showing either a bitmap or text.
  30 // ----------------------------------------------------------------------------
  31
  32 class WXDLLIMPEXP_ADV wxBannerWindow : public wxWindow
  33 {
  34 public:
  35     // Default constructor, use Create() later.
  36     wxBannerWindow() { Init(); }
  37
  38     // Convenient constructor that should be used in the majority of cases.
  39     //
  40     // The banner orientation changes how the text in it is displayed and also
  41     // defines where is the bitmap truncated if it's too big to fit but doesn't
  42     // do anything for the banner position, this is supposed to be taken care
  43     // of in the usual way, e.g. using sizers.
  44     wxBannerWindow(wxWindow* parent, wxDirection dir = wxLEFT)
  45     {
  46         Init();
  47
  48         Create(parent, wxID_ANY, dir);
  49     }
  50
  51     // Full constructor provided for consistency with the other classes only.
  52     wxBannerWindow(wxWindow* parent,
  53                    wxWindowID winid,
  54                    wxDirection dir = wxLEFT,
  55                    const wxPoint& pos = wxDefaultPosition,
  56                    const wxSize& size = wxDefaultSize,
  57                    long style = 0,
  58                    const wxString& name = wxBannerWindowNameStr)
  59     {
  60         Init();
  61
  62         Create(parent, winid, dir, pos, size, style, name);
  63     }
  64
  65     // Can be only called on objects created with the default constructor.
  66     bool Create(wxWindow* parent,
  67                 wxWindowID winid,
  68                 wxDirection dir = wxLEFT,
  69                 const wxPoint& pos = wxDefaultPosition,
  70                 const wxSize& size = wxDefaultSize,
  71                 long style = 0,
  72                 const wxString& name = wxBannerWindowNameStr);
  73
  74
  75     // Provide an existing bitmap to show. For wxLEFT orientation the bitmap is
  76     // truncated from the top, for wxTOP and wxBOTTOM -- from the right and for
  77     // wxRIGHT -- from the bottom, so put the most important part of the bitmap
  78     // information in the opposite direction.
  79     void SetBitmap(const wxBitmap& bmp);
  80
  81     // Set the text to display. This is mutually exclusive with SetBitmap().
  82     // Title is rendered in bold and should be single line, message can have
  83     // multiple lines but is not wrapped automatically.
  84     void SetText(const wxString& title, const wxString& message);
  85
  86     // Set the colours between which the gradient runs. This can be combined
  87     // with SetText() but not SetBitmap().
  88     void SetGradient(const wxColour& start, const wxColour& end);
  89
  90 protected:
  91     virtual wxSize DoGetBestClientSize() const;
  92
  93 private:
  94     // Common part of all constructors.
  95     void Init();
  96
  97     // Fully invalidates the window.
  98     void OnSize(wxSizeEvent& event);
  99
 100     // Redraws the window using either m_bitmap or m_title/m_message.
 101     void OnPaint(wxPaintEvent& event);
 102
 103     // Helper of OnPaint(): draw the bitmap at the correct position depending
 104     // on our orientation.
 105     void DrawBitmapBackground(wxDC& dc);
 106
 107     // Helper of OnPaint(): draw the text in the appropriate direction.
 108     void DrawBannerTextLine(wxDC& dc, const wxString& str, const wxPoint& pos);
 109
 110     // Return the font to use for the title. Currently this is hardcoded as a
 111     // larger bold version of the standard window font but could be made
 112     // configurable in the future.
 113     wxFont GetTitleFont() const;
 114
 115     // Return the colour to use for extending the bitmap. Non-const as it
 116     // updates m_colBitmapBg if needed.
 117     wxColour GetBitmapBg();
 118
 119
 120     // The window side along which the banner is laid out.
 121     wxDirection m_direction;
 122
 123     // If valid, this bitmap is drawn as is.
 124     wxBitmap m_bitmap;
 125
 126     // If bitmap is valid, this is the colour we use to extend it if the bitmap
 127     // is smaller than this window. It is computed on demand by GetBitmapBg().
 128     wxColour m_colBitmapBg;
 129
 130     // The title and main message to draw, used if m_bitmap is invalid.
 131     wxString m_title,
 132              m_message;
 133
 134     // Start and stop gradient colours, only used when drawing text.
 135     wxColour m_colStart,
 136              m_colEnd;
 137
 138     wxDECLARE_EVENT_TABLE();
 139
 140     wxDECLARE_NO_COPY_CLASS(wxBannerWindow);
 141 };
 142
 143 #endif // wxUSE_BANNERWINDOW
 144
 145 #endif // _WX_BANNERWINDOW_H_