]> git.saurik.com Git - wxWidgets.git/blob - interface/aui/auibook.h
adjusted indentation with astyle; added Id keyword
[wxWidgets.git] / interface / aui / auibook.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: aui/auibook.h
3 // Purpose: documentation for wxAuiNotebook class
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxAuiNotebook
11 @headerfile auibook.h wx/aui/auibook.h
12
13 wxAuiNotebook is part of the wxAUI class framework.
14 See also @ref overview_wxauioverview "wxAUI overview".
15
16 wxAuiNotebook is a notebook control which implements many features common in
17 applications with dockable panes.
18 Specifically, wxAuiNotebook implements functionality which allows the user to
19 rearrange tab order via drag-and-drop,
20 split the tab window into many different splitter configurations, and toggle
21 through different themes to customize
22 the control's look and feel.
23
24 An effort has been made to try to maintain an API as similar to that of
25 wxNotebook.
26
27 The default theme that is used is wxAuiDefaultTabArt, which provides a modern,
28 glossy look and feel.
29 The theme can be changed by calling wxAuiNotebook::SetArtProvider.
30
31 @beginStyleTable
32 @style{wxAUI_NB_DEFAULT_STYLE}:
33 Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE |
34 wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB.
35 @style{wxAUI_NB_TAB_SPLIT}:
36 Allows the tab control to be split by dragging a tab.
37 @style{wxAUI_NB_TAB_MOVE}:
38 Allows a tab to be moved horizontally by dragging.
39 @style{wxAUI_NB_TAB_EXTERNAL_MOVE}:
40 Allows a tab to be moved to another tab control.
41 @style{wxAUI_NB_TAB_FIXED_WIDTH}:
42 With this style, all tabs have the same width.
43 @style{wxAUI_NB_SCROLL_BUTTONS}:
44 With this style, left and right scroll buttons are displayed.
45 @style{wxAUI_NB_WINDOWLIST_BUTTON}:
46 With this style, a drop-down list of windows is available.
47 @style{wxAUI_NB_CLOSE_BUTTON}:
48 With this style, a close button is available on the tab bar.
49 @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB}:
50 With this style, the close button is visible on the active tab.
51 @style{wxAUI_NB_CLOSE_ON_ALL_TABS}:
52 With this style, the close button is visible on all tabs.
53 @style{wxAUI_NB_TOP}:
54 With this style, tabs are drawn along the top of the notebook.
55 @style{wxAUI_NB_BOTTOM}:
56 With this style, tabs are drawn along the bottom of the notebook.
57 @endStyleTable
58
59 @library{wxaui}
60 @category{aui}
61 */
62 class wxAuiNotebook : public wxControl
63 {
64 public:
65 //@{
66 /**
67 Constructor. Creates a wxAuiNotebok control.
68 */
69 wxAuiNotebook();
70 wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY,
71 const wxPoint& pos = wxDefaultPosition,
72 const wxSize& size = wxDefaultSize,
73 long style = wxAUI_NB_DEFAULT_STYLE);
74 //@}
75
76 /**
77 Adds a page. If the @e select parameter is @true, calling this will generate a
78 page change event.
79 */
80 bool AddPage(wxWindow* page, const wxString& caption,
81 bool select = @false,
82 const wxBitmap& bitmap = wxNullBitmap);
83
84 /**
85 Sets the selection to the next or previous page.
86 */
87 void AdvanceSelection(bool forward = @true);
88
89 /**
90 Creates the notebook window.
91 */
92 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
93 const wxPoint& pos = wxDefaultPosition,
94 const wxSize& size = wxDefaultSize,
95 long style = 0);
96
97 /**
98 Deletes a page at the given index. Calling this method will generate a page
99 change event.
100 */
101 bool DeletePage(size_t page);
102
103 /**
104 Returns the associated art provider.
105 */
106 wxAuiTabArt* GetArtProvider();
107
108 /**
109 Returns the desired height of the notebook for the given page height. Use this
110 to fit the notebook to
111 a given page size.
112 */
113 int GetHeightForPageHeight(int pageHeight);
114
115 /**
116 Returns the page specified by the given index.
117 */
118 wxWindow* GetPage(size_t page_idx);
119
120 /**
121 Returns the tab bitmap for the page.
122 */
123 wxBitmap GetPageBitmap(size_t page);
124
125 /**
126 Returns the number of pages in the notebook.
127 */
128 size_t GetPageCount();
129
130 /**
131 Returns the page index for the specified window. If the window is not found in
132 the notebook, wxNOT_FOUND is returned.
133 */
134 int GetPageIndex(wxWindow* page_wnd);
135
136 /**
137 Returns the tab label for the page.
138 */
139 wxString GetPageText(size_t page);
140
141 /**
142 Returns the currently selected page.
143 */
144 int GetSelection();
145
146 /**
147 Returns the height of the tab control.
148 */
149 int GetTabCtrlHeight();
150
151 /**
152 InsertPage() is similar to AddPage, but allows the ability to specify the
153 insert location.
154 If the @e select parameter is @true, calling this will generate a page change
155 event.
156 */
157 bool InsertPage(size_t page_idx, wxWindow* page,
158 const wxString& caption,
159 bool select = @false,
160 const wxBitmap& bitmap = wxNullBitmap);
161
162 /**
163 Removes a page, without deleting the window pointer.
164 */
165 bool RemovePage(size_t page);
166
167 /**
168 Sets the art provider to be used by the notebook.
169 */
170 void SetArtProvider(wxAuiTabArt* art);
171
172 /**
173 Sets the font for drawing the tab labels, using a bold version of the font for
174 selected tab labels.
175 */
176 bool SetFont(const wxFont& font);
177
178 /**
179 Sets the font for measuring tab labels.
180 */
181 void SetMeasuringFont(const wxFont& font);
182
183 /**
184 Sets the font for drawing unselected tab labels.
185 */
186 void SetNormalFont(const wxFont& font);
187
188 /**
189 Sets the bitmap for the page. To remove a bitmap from the tab caption, pass
190 wxNullBitmap.
191 */
192 bool SetPageBitmap(size_t page, const wxBitmap& bitmap);
193
194 /**
195 Sets the tab label for the page.
196 */
197 bool SetPageText(size_t page, const wxString& text);
198
199 /**
200 Sets the font for drawing selected tab labels.
201 */
202 void SetSelectedFont(const wxFont& font);
203
204 /**
205 Sets the page selection. Calling this method will generate a page change event.
206 */
207 size_t SetSelection(size_t new_page);
208
209 /**
210 Sets the tab height. By default, the tab control height is calculated
211 by measuring the text height and bitmap sizes on the tab captions. Calling this
212 method will override that calculation and set the tab control to the specified
213 height parameter. A call to this method will override any call to
214 SetUniformBitmapSize().
215 Specifying -1 as the height will return the control to its default auto-sizing
216 behaviour.
217 */
218 void SetTabCtrlHeight(int height);
219
220 //@{
221 /**
222 Split performs a split operation programmatically. The argument @e page
223 indicates
224 the page that will be split off. This page will also become the active page
225 after the
226 split. The @e direction argument specifies where the pane should go, it should
227 be one
228 of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT.
229 */
230 void SetUniformBitmapSize(const wxSize& size);
231 void Split(size_t page, int direction);
232 //@}
233
234 /**
235 Shows the window menu for the active tab control associated with this notebook,
236 and returns @true if a selection was made.
237 */
238 bool ShowWindowMenu();
239 };
240
241
242 /**
243 @class wxAuiTabArt
244 @headerfile auibook.h wx/aui/auibook.h
245
246 Tab art class.
247
248 @library{wxaui}
249 @category{aui}
250 */
251 class wxAuiTabArt
252 {
253 public:
254 /**
255 Constructor.
256 */
257 wxAuiTabArt();
258
259 /**
260 Clones the art object.
261 */
262 wxAuiTabArt* Clone();
263
264 /**
265 Draws a background on the given area.
266 */
267 void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect);
268
269 /**
270 Draws a button.
271 */
272 void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
273 int bitmap_id,
274 int button_state,
275 int orientation,
276 const wxBitmap& bitmap_override,
277 wxRect* out_rect);
278
279 /**
280 Draws a tab.
281 */
282 void DrawTab(wxDC& dc, wxWindow* wnd, const wxRect& in_rect,
283 const wxString& caption,
284 const wxBitmap& bitmap,
285 bool active,
286 int close_button_state,
287 wxRect* out_tab_rect,
288 wxRect* out_button_rect,
289 int* x_extent);
290
291 /**
292 Returns the tab control size.
293 */
294 int GetBestTabCtrlSize(wxWindow* wnd,
295 wxAuiNotebookPageArray& pages);
296
297 /**
298 Returns the indent size.
299 */
300 int GetIndentSize();
301
302 /**
303 Returns the tab size for the given caption, bitmap and state.
304 */
305 wxSize GetTabSize(wxDC& dc, wxWindow* wnd,
306 const wxString& caption,
307 const wxBitmap& bitmap,
308 bool active,
309 int close_button_state,
310 int* x_extent);
311
312 /**
313 Sets flags.
314 */
315 void SetFlags(unsigned int flags);
316
317 /**
318 Sets the font used for calculating measurements.
319 */
320 void SetMeasuringFont(const wxFont& font);
321
322 /**
323 Sets the normal font for drawing labels.
324 */
325 void SetNormalFont(const wxFont& font);
326
327 /**
328 Sets the font for drawing text for selected UI elements.
329 */
330 void SetSelectedFont(const wxFont& font);
331
332 /**
333 Sets sizing information.
334 */
335 void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count);
336
337 /**
338 Pops up a menu to show the list of windows managed by wxAui.
339 */
340 int ShowWindowList(wxWindow* wnd, const wxArrayString& items,
341 int active_idx);
342 };