]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/notebook.h
remove deprecation from wxWizard::SetPageSize
[wxWidgets.git] / interface / wx / notebook.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: notebook.h
3e97a905 3// Purpose: interface of wxNotebook
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
23324ae1
FM
9/**
10 @class wxNotebook
7c913512 11
23324ae1
FM
12 This class represents a notebook control, which manages multiple windows with
13 associated tabs.
7c913512 14
3e97a905
VZ
15 To use the class, create a wxNotebook object and call wxNotebook::AddPage
16 or wxNotebook::InsertPage, passing a window to be used as the page. Do not
17 explicitly delete the window for a page that is currently managed by
18 wxNotebook.
7c913512 19
23324ae1 20 @b wxNotebookPage is a typedef for wxWindow.
7c913512 21
23324ae1 22 @beginStyleTable
8c6791e4 23 @style{wxNB_TOP}
23324ae1 24 Place tabs on the top side.
8c6791e4 25 @style{wxNB_LEFT}
23324ae1 26 Place tabs on the left side.
8c6791e4 27 @style{wxNB_RIGHT}
23324ae1 28 Place tabs on the right side.
8c6791e4 29 @style{wxNB_BOTTOM}
23324ae1 30 Place tabs under instead of above the notebook pages.
8c6791e4 31 @style{wxNB_FIXEDWIDTH}
23324ae1 32 (Windows only) All tabs will have same width.
8c6791e4 33 @style{wxNB_MULTILINE}
23324ae1 34 (Windows only) There can be several rows of tabs.
8c6791e4 35 @style{wxNB_NOPAGETHEME}
23324ae1
FM
36 (Windows only) Display a solid colour on notebook pages, and not a
37 gradient, which can reduce performance.
8c6791e4 38 @style{wxNB_FLAT}
23324ae1
FM
39 (Windows CE only) Show tabs in a flat style.
40 @endStyleTable
7c913512 41
23324ae1
FM
42 @library{wxcore}
43 @category{miscwnd}
7c913512 44
3e97a905
VZ
45 @see wxBookCtrl, wxBookCtrlEvent, wxImageList,
46 @ref page_samples_notebook "Notebook Sample"
23324ae1
FM
47*/
48class wxNotebook : public wxBookCtrl overview
49{
50public:
90ae878f
RR
51
52 /**
53 Constructs a notebook control.
54 */
55 wxNotebook();
56
23324ae1
FM
57 /**
58 Constructs a notebook control.
23324ae1
FM
59 Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN
60 window style.
3c4f71cc 61
7c913512 62 @param parent
4cc4bfaf 63 The parent window. Must be non-@NULL.
7c913512 64 @param id
4cc4bfaf 65 The window identifier.
7c913512 66 @param pos
4cc4bfaf 67 The window position.
7c913512 68 @param size
4cc4bfaf 69 The window size.
7c913512 70 @param style
4cc4bfaf 71 The window style. See wxNotebook.
7c913512 72 @param name
4cc4bfaf 73 The name of the control (used only under Motif).
23324ae1 74 */
7c913512
FM
75 wxNotebook(wxWindow* parent, wxWindowID id,
76 const wxPoint& pos = wxDefaultPosition,
77 const wxSize& size = wxDefaultSize,
78 long style = 0,
79 const wxString& name = wxNotebookNameStr);
23324ae1
FM
80
81 /**
82 Destroys the wxNotebook object.
83 */
a6052817 84 virtual ~wxNotebook();
23324ae1
FM
85
86 /**
87 Adds a new page.
23324ae1 88 The call to this function may generate the page changing events.
3c4f71cc 89
7c913512 90 @param page
4cc4bfaf 91 Specifies the new page.
7c913512 92 @param text
4cc4bfaf 93 Specifies the text for the new page.
7c913512 94 @param select
4cc4bfaf 95 Specifies whether the page should be selected.
7c913512 96 @param imageId
4cc4bfaf 97 Specifies the optional image index for the new page.
3c4f71cc 98
d29a9a8a 99 @return @true if successful, @false otherwise.
3c4f71cc 100
23324ae1 101 @remarks Do not delete the page, it will be deleted by the notebook.
3c4f71cc 102
4cc4bfaf 103 @see InsertPage()
23324ae1
FM
104 */
105 bool AddPage(wxNotebookPage* page, const wxString& text,
4cc4bfaf 106 bool select = false,
23324ae1
FM
107 int imageId = -1);
108
109 /**
110 Cycles through the tabs.
23324ae1
FM
111 The call to this function generates the page changing events.
112 */
4cc4bfaf 113 void AdvanceSelection(bool forward = true);
23324ae1
FM
114
115 /**
116 Sets the image list for the page control and takes ownership of
117 the list.
3c4f71cc 118
4cc4bfaf 119 @see wxImageList, SetImageList()
23324ae1
FM
120 */
121 void AssignImageList(wxImageList* imageList);
122
123 /**
124 Changes the selection for the given page, returning the previous selection.
23324ae1 125 The call to this function does not generate the page changing events.
3e97a905 126 This is the only difference with SetSelection(). See
90ae878f
RR
127 @ref overview_eventhandling_prog "User Generated Events"
128 for more infomation.
23324ae1 129 */
a6052817 130 virtual int ChangeSelection(size_t page);
23324ae1
FM
131
132 /**
133 Creates a notebook control. See wxNotebook() for a description
134 of the parameters.
135 */
136 bool Create(wxWindow* parent, wxWindowID id,
137 const wxPoint& pos = wxDefaultPosition,
a6052817
FM
138 const wxSize& size = wxDefaultSize,
139 long style = 0,
23324ae1
FM
140 const wxString& name = wxNotebookNameStr);
141
142 /**
143 Deletes all pages.
144 */
a6052817 145 virtual bool DeleteAllPages();
23324ae1
FM
146
147 /**
148 Deletes the specified page, and the associated window.
23324ae1
FM
149 The call to this function generates the page changing events.
150 */
151 bool DeletePage(size_t page);
152
153 /**
154 Returns the currently selected notebook page or @NULL.
155 */
328f5751 156 wxWindow* GetCurrentPage() const;
23324ae1
FM
157
158 /**
159 Returns the associated image list.
3c4f71cc 160
4cc4bfaf 161 @see wxImageList, SetImageList()
23324ae1 162 */
328f5751 163 wxImageList* GetImageList() const;
23324ae1
FM
164
165 /**
166 Returns the window at the given page position.
167 */
168 wxNotebookPage* GetPage(size_t page);
169
170 /**
171 Returns the number of pages in the notebook control.
172 */
328f5751 173 size_t GetPageCount() const;
23324ae1
FM
174
175 /**
176 Returns the image index for the given page.
177 */
a6052817 178 virtual int GetPageImage(size_t nPage) const;
23324ae1
FM
179
180 /**
181 Returns the string for the given page.
182 */
a6052817 183 virtual wxString GetPageText(size_t nPage) const;
23324ae1
FM
184
185 /**
186 Returns the number of rows in the notebook control.
187 */
a6052817 188 virtual int GetRowCount() const;
23324ae1
FM
189
190 /**
191 Returns the currently selected page, or -1 if none was selected.
3e97a905
VZ
192 Note that this method may return either the previously or newly
193 selected page when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler
194 depending on the platform and so wxBookCtrlEvent::GetSelection should be
23324ae1
FM
195 used instead in this case.
196 */
a6052817 197 virtual int GetSelection() const;
23324ae1
FM
198
199 /**
200 If running under Windows and themes are enabled for the application, this
201 function
202 returns a suitable colour for painting the background of a notebook page, and
203 can be passed
204 to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned.
205 */
a6052817 206 virtual wxColour GetThemeBackgroundColour() const;
23324ae1
FM
207
208 /**
209 Returns the index of the tab at the specified position or @c wxNOT_FOUND
4cc4bfaf 210 if none. If @a flags parameter is non-@NULL, the position of the point
23324ae1 211 inside the tab is returned as well.
3c4f71cc 212
7c913512 213 @param pt
4cc4bfaf 214 Specifies the point for the hit test.
7c913512 215 @param flags
4cc4bfaf 216 Return value for detailed information. One of the following values:
90ae878f
RR
217 <TABLE><TR><TD>wxBK_HITTEST_NOWHERE</TD>
218 <TD>There was no tab under this point.</TD></TR>
219 <TR><TD>wxBK_HITTEST_ONICON</TD>
220 <TD>The point was over an icon (currently wxMSW only).</TD></TR>
221 <TR><TD>wxBK_HITTEST_ONLABEL</TD>
222 <TD>The point was over a label (currently wxMSW only).</TD></TR>
223 <TR><TD>wxBK_HITTEST_ONITEM</TD>
224 <TD>The point was over an item, but not on the label or icon.</TD></TR>
225 <TR><TD>wxBK_HITTEST_ONPAGE</TD>
226 <TD>The point was over a currently selected page, not over any tab.
227 Note that this flag is present only if wxNOT_FOUND is returned.</TD></TR>
228 </TABLE>
229@return Returns the zero-based tab index or wxNOT_FOUND if there is no
230 tab at the specified position.
23324ae1 231 */
90ae878f 232 virtual int HitTest(const wxPoint& pt, long* flags = NULL) const;
23324ae1
FM
233
234 /**
235 Inserts a new page at the specified position.
3c4f71cc 236
7c913512 237 @param index
4cc4bfaf 238 Specifies the position for the new page.
7c913512 239 @param page
4cc4bfaf 240 Specifies the new page.
7c913512 241 @param text
4cc4bfaf 242 Specifies the text for the new page.
7c913512 243 @param select
4cc4bfaf 244 Specifies whether the page should be selected.
7c913512 245 @param imageId
4cc4bfaf 246 Specifies the optional image index for the new page.
3c4f71cc 247
d29a9a8a 248 @return @true if successful, @false otherwise.
3c4f71cc 249
23324ae1 250 @remarks Do not delete the page, it will be deleted by the notebook.
3c4f71cc 251
4cc4bfaf 252 @see AddPage()
23324ae1 253 */
adaaa686
FM
254 virtual bool InsertPage(size_t index, wxNotebookPage* page,
255 const wxString& text, bool select = false,
256 int imageId = -1);
23324ae1
FM
257
258 /**
259 An event handler function, called when the page selection is changed.
3c4f71cc 260
3e97a905 261 @see wxBookCtrlEvent
23324ae1 262 */
3e97a905 263 void OnSelChange(wxBookCtrlEvent& event);
23324ae1
FM
264
265 /**
266 Deletes the specified page, without deleting the associated window.
267 */
268 bool RemovePage(size_t page);
269
270 /**
271 Sets the image list for the page control. It does not take
272 ownership of the image list, you must delete it yourself.
3c4f71cc 273
4cc4bfaf 274 @see wxImageList, AssignImageList()
23324ae1
FM
275 */
276 void SetImageList(wxImageList* imageList);
277
278 /**
279 Sets the amount of space around each page's icon and label, in pixels.
1f1d2182 280 @note The vertical padding cannot be changed in wxGTK.
23324ae1 281 */
adaaa686 282 virtual void SetPadding(const wxSize& padding);
23324ae1
FM
283
284 /**
4cc4bfaf 285 Sets the image index for the given page. @a image is an index into
23324ae1
FM
286 the image list which was set with SetImageList().
287 */
a6052817 288 virtual bool SetPageImage(size_t page, int image);
23324ae1
FM
289
290 /**
291 Sets the width and height of the pages.
1f1d2182 292 @note This method is currently not implemented for wxGTK.
23324ae1 293 */
a6052817 294 virtual void SetPageSize(const wxSize& size);
23324ae1
FM
295
296 /**
297 Sets the text for the given page.
298 */
a6052817 299 virtual bool SetPageText(size_t page, const wxString& text);
23324ae1
FM
300
301 /**
302 Sets the selection for the given page, returning the previous selection.
23324ae1 303 The call to this function generates the page changing events.
23324ae1
FM
304 This function is deprecated and should not be used in new code. Please use the
305 ChangeSelection() function instead.
3c4f71cc 306
4cc4bfaf 307 @see GetSelection()
23324ae1 308 */
a6052817 309 virtual int SetSelection(size_t page);
23324ae1 310};
e54c96f1 311