]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/bannerwindow.h
Add missing interface items for Phoenix
[wxWidgets.git] / interface / wx / bannerwindow.h
CommitLineData
ea11bf3a 1///////////////////////////////////////////////////////////////////////////////
d50fc4dc 2// Name: interface/wx/bannerwindow.h
ea11bf3a
VZ
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 */
52class wxBannerWindow : public wxWindow
53{
54public:
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
4e2b91bb
VZ
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.
ea11bf3a
VZ
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};