]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/toplevel.h
clarify role of wxToolBarToolBase (fixes #9874)
[wxWidgets.git] / interface / wx / toplevel.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: toplevel.h
e54c96f1 3// Purpose: interface of wxTopLevelWindow
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
f992f2ae
BP
9/**
10 Styles used with wxTopLevelWindow::RequestUserAttention().
11*/
12enum
13{
14 wxUSER_ATTENTION_INFO = 1, ///< Requests user attention,
15 wxUSER_ATTENTION_ERROR = 2 ///< Results in a more drastic action.
16};
17
18/**
19 Styles used with wxTopLevelWindow::ShowFullScreen().
20*/
21enum
22{
23 wxFULLSCREEN_NOMENUBAR = 0x0001, ///< Don't display the menu bar.
24 wxFULLSCREEN_NOTOOLBAR = 0x0002, ///< Don't display toolbar bars.
25 wxFULLSCREEN_NOSTATUSBAR = 0x0004, ///< Don't display the status bar.
26 wxFULLSCREEN_NOBORDER = 0x0008, ///< Don't display any border.
27 wxFULLSCREEN_NOCAPTION = 0x0010, ///< Don't display a caption.
28
29 /**
30 Combination of all above, will display the least possible.
31 */
32 wxFULLSCREEN_ALL = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR |
33 wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER |
34 wxFULLSCREEN_NOCAPTION
35};
36
23324ae1
FM
37/**
38 @class wxTopLevelWindow
7c913512 39
f992f2ae
BP
40 wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an
41 abstract base class meaning that you never work with objects of this class
42 directly, but all of its methods are also applicable for the two classes
43 above.
7c913512 44
afc31d8a
FM
45 Note that the instances of wxTopLevelWindow are managed by wxWidgets in the
46 internal top level window list.
47
23324ae1
FM
48 @library{wxcore}
49 @category{managedwnd}
7c913512 50
f992f2ae 51 @see wxDialog, wxFrame
23324ae1
FM
52*/
53class wxTopLevelWindow : public wxWindow
54{
55public:
56 /**
57 Returns @true if the platform supports making the window translucent.
3c4f71cc 58
4cc4bfaf 59 @see SetTransparent()
23324ae1
FM
60 */
61 virtual bool CanSetTransparent();
62
63 /**
64 A synonym for CentreOnScreen().
65 */
66 void CenterOnScreen(int direction);
67
68 /**
69 Centres the window on screen.
3c4f71cc 70
7c913512 71 @param direction
f992f2ae
BP
72 Specifies the direction for the centering. May be @c wxHORIZONTAL,
73 @c wxVERTICAL or @c wxBOTH.
3c4f71cc 74
f992f2ae 75 @see wxWindow::CentreOnParent()
23324ae1
FM
76 */
77 void CentreOnScreen(int direction = wxBOTH);
78
79 /**
f992f2ae
BP
80 Enables or disables the Close button (most often in the right upper
81 corner of a dialog) and the Close entry of the system menu (most often
82 in the left upper corner of the dialog).
83
84 Currently only implemented for wxMSW and wxGTK.
85
86 Returns @true if operation was successful. This may be wrong on X11
87 (including GTK+) where the window manager may not support this operation
88 and there is no way to find out.
23324ae1 89 */
0004982c 90 virtual bool EnableCloseButton(bool enable = true);
23324ae1
FM
91
92 /**
f992f2ae
BP
93 Returns a pointer to the button which is the default for this window, or
94 @c @NULL. The default button is the one activated by pressing the Enter
95 key.
23324ae1 96 */
328f5751 97 wxWindow* GetDefaultItem() const;
23324ae1
FM
98
99 /**
f992f2ae
BP
100 Returns the standard icon of the window. The icon will be invalid if it
101 hadn't been previously set by SetIcon().
3c4f71cc 102
4cc4bfaf 103 @see GetIcons()
23324ae1 104 */
cfbe5614 105 wxIcon GetIcon() const;
23324ae1
FM
106
107 /**
f992f2ae
BP
108 Returns all icons associated with the window, there will be none of them
109 if neither SetIcon() nor SetIcons() had been called before. Use
110 GetIcon() to get the main icon of the window.
3c4f71cc 111
4cc4bfaf 112 @see wxIconBundle
23324ae1 113 */
cfbe5614 114 const wxIconBundle& GetIcons() const;
23324ae1
FM
115
116 /**
117 Gets a string containing the window title.
3c4f71cc 118
4cc4bfaf 119 @see SetTitle()
23324ae1 120 */
0004982c 121 virtual wxString GetTitle() const;
23324ae1
FM
122
123 /**
f992f2ae
BP
124 Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input
125 panel) area and resize window accordingly. Override this if you want to
126 avoid resizing or do additional operations.
23324ae1
FM
127 */
128 virtual bool HandleSettingChange(WXWPARAM wParam,
129 WXLPARAM lParam);
130
131 /**
132 Iconizes or restores the window.
3c4f71cc 133
7c913512 134 @param iconize
4cc4bfaf 135 If @true, iconizes the window; if @false, shows and restores it.
3c4f71cc 136
d317fdeb 137 @see IsIconized(), Maximize(), wxIconizeEvent.
23324ae1 138 */
cfbe5614 139 virtual void Iconize(bool iconize = true);
23324ae1
FM
140
141 /**
142 Returns @true if this window is currently active, i.e. if the user is
f992f2ae 143 currently working with it.
23324ae1 144 */
adaaa686 145 virtual bool IsActive();
23324ae1
FM
146
147 /**
f992f2ae
BP
148 Returns @true if this window is expected to be always maximized, either
149 due to platform policy or due to local policy regarding particular
150 class.
23324ae1 151 */
328f5751 152 virtual bool IsAlwaysMaximized() const;
23324ae1
FM
153
154 /**
155 Returns @true if the window is in fullscreen mode.
3c4f71cc 156
4cc4bfaf 157 @see ShowFullScreen()
23324ae1 158 */
0004982c 159 virtual bool IsFullScreen() const;
23324ae1
FM
160
161 /**
162 Returns @true if the window is iconized.
163 */
0004982c 164 virtual bool IsIconized() const;
23324ae1
FM
165
166 /**
167 Returns @true if the window is maximized.
168 */
0004982c 169 virtual bool IsMaximized() const;
23324ae1
FM
170
171 /**
f992f2ae
BP
172 This method is specific to wxUniversal port.
173
174 Returns @true if this window is using native decorations, @false if we
175 draw them ourselves.
3c4f71cc 176
4cc4bfaf
FM
177 @see UseNativeDecorations(),
178 UseNativeDecorationsByDefault()
23324ae1 179 */
328f5751 180 bool IsUsingNativeDecorations() const;
23324ae1 181
dcc5fcbf
FM
182 /**
183 See wxWindow::SetAutoLayout(): when auto layout is on, this function gets
184 called automatically when the window is resized.
185 */
186 virtual bool Layout();
187
23324ae1
FM
188 /**
189 Maximizes or restores the window.
3c4f71cc 190
7c913512 191 @param maximize
4cc4bfaf 192 If @true, maximizes the window, otherwise it restores it.
3c4f71cc 193
4cc4bfaf 194 @see Iconize()
23324ae1 195 */
cfbe5614 196 virtual void Maximize(bool maximize = true);
23324ae1
FM
197
198 /**
f992f2ae
BP
199 Use a system-dependent way to attract users attention to the window when
200 it is in background.
201
202 @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO
203 (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic
23324ae1 204 action. When in doubt, use the default value.
f992f2ae
BP
205
206
207 @note This function should normally be only used when the application
208 is not already in foreground.
209
210 This function is currently implemented for Win32 where it flashes
211 the window icon in the taskbar, and for wxGTK with task bars
212 supporting it.
213
23324ae1 214 */
adaaa686 215 virtual void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);
23324ae1
FM
216
217 /**
4cc4bfaf 218 Changes the default item for the panel, usually @a win is a button.
3c4f71cc 219
4cc4bfaf 220 @see GetDefaultItem()
23324ae1 221 */
cfbe5614 222 wxWindow* SetDefaultItem(wxWindow* win);
23324ae1
FM
223
224 /**
225 Sets the icon for this window.
3c4f71cc 226
7c913512 227 @param icon
f992f2ae
BP
228 The wxIcon to associate with this window.
229
230 @remarks The window takes a 'copy' of @a icon, but since it uses
231 reference counting, the copy is very quick. It is safe to
232 delete @a icon after calling this function.
3c4f71cc 233
0f278d77
VS
234 @note In wxMSW, @a icon must be either 16x16 or 32x32 icon.
235
236 @see wxIcon, SetIcons()
23324ae1
FM
237 */
238 void SetIcon(const wxIcon& icon);
239
240 /**
f992f2ae
BP
241 Sets several icons of different sizes for this window: this allows to
242 use different icons for different situations (e.g. task switching bar,
243 taskbar, window title bar) instead of scaling, with possibly bad looking
244 results, the only icon set by SetIcon().
3c4f71cc 245
7c913512 246 @param icons
4cc4bfaf 247 The icons to associate with this window.
3c4f71cc 248
0f278d77
VS
249 @note In wxMSW, @a icons must contain a 16x16 or 32x32 icon,
250 preferably both.
251
252 @see wxIconBundle
23324ae1 253 */
adaaa686 254 virtual void SetIcons(const wxIconBundle& icons);
23324ae1
FM
255
256 /**
f992f2ae
BP
257 Sets action or menu activated by pressing left hardware button on the
258 smart phones. Unavailable on full keyboard machines.
3c4f71cc 259
7c913512 260 @param id
4cc4bfaf 261 Identifier for this button.
7c913512 262 @param label
f992f2ae
BP
263 Text to be displayed on the screen area dedicated to this hardware
264 button.
7c913512 265 @param subMenu
4cc4bfaf 266 The menu to be opened after pressing this hardware button.
3c4f71cc 267
4cc4bfaf 268 @see SetRightMenu().
23324ae1
FM
269 */
270 void SetLeftMenu(int id = wxID_ANY,
271 const wxString& label = wxEmptyString,
4cc4bfaf 272 wxMenu* subMenu = NULL);
23324ae1
FM
273
274 /**
f992f2ae 275 A simpler interface for setting the size hints than SetSizeHints().
23324ae1 276 */
adaaa686 277 virtual void SetMaxSize(const wxSize& size);
23324ae1
FM
278
279 /**
f992f2ae 280 A simpler interface for setting the size hints than SetSizeHints().
23324ae1 281 */
adaaa686 282 virtual void SetMinSize(const wxSize& size);
23324ae1
FM
283
284 /**
f992f2ae
BP
285 Sets action or menu activated by pressing right hardware button on the
286 smart phones. Unavailable on full keyboard machines.
3c4f71cc 287
7c913512 288 @param id
4cc4bfaf 289 Identifier for this button.
7c913512 290 @param label
f992f2ae 291 Text to be displayed on the screen area dedicated to this hardware
77bfb902 292 button.
7c913512 293 @param subMenu
4cc4bfaf 294 The menu to be opened after pressing this hardware button.
3c4f71cc 295
4cc4bfaf 296 @see SetLeftMenu().
23324ae1
FM
297 */
298 void SetRightMenu(int id = wxID_ANY,
299 const wxString& label = wxEmptyString,
4cc4bfaf 300 wxMenu* subMenu = NULL);
23324ae1
FM
301
302 /**
303 If the platform supports it, sets the shape of the window to that
f992f2ae
BP
304 depicted by @a region. The system will not display or respond to any
305 mouse event for the pixels that lie outside of the region. To reset the
306 window to the normal rectangular shape simply call SetShape() again with
307 an empty wxRegion. Returns @true if the operation is successful.
23324ae1 308 */
adaaa686 309 virtual bool SetShape(const wxRegion& region);
23324ae1 310
23324ae1 311 /**
f992f2ae
BP
312 Allows specification of minimum and maximum window sizes, and window
313 size increments. If a pair of values is not set (or set to -1), no
314 constraints will be used.
3c4f71cc 315
77bfb902
FM
316 @param minW
317 The minimum width.
318 @param minH
319 The minimum height.
320 @param maxW
321 The maximum width.
322 @param maxH
323 The maximum height.
7c913512 324 @param incW
4cc4bfaf 325 Specifies the increment for sizing the width (GTK/Motif/Xt only).
7c913512 326 @param incH
4cc4bfaf 327 Specifies the increment for sizing the height (GTK/Motif/Xt only).
3c4f71cc 328
23324ae1 329 @remarks Notice that this function not only prevents the user from
f992f2ae
BP
330 resizing the window outside the given bounds but it also
331 prevents the program itself from doing it using
332 wxWindow::SetSize().
333
4cc4bfaf 334 */
77bfb902
FM
335 virtual void SetSizeHints(int minW, int minH,
336 int maxW = -1, int maxH = -1,
337 int incW = -1, int incH = -1);
f992f2ae
BP
338
339 /**
340 Allows specification of minimum and maximum window sizes, and window
341 size increments. If a pair of values is not set (or set to -1), no
342 constraints will be used.
343
77bfb902
FM
344 @param minSize
345 The minimum size of the window.
346 @param maxSize
347 The maximum size of the window.
f992f2ae
BP
348 @param incSize
349 Increment size (only taken into account under X11-based ports such
350 as wxGTK/wxMotif/wxX11).
351
352 @remarks Notice that this function not only prevents the user from
353 resizing the window outside the given bounds but it also
354 prevents the program itself from doing it using
355 wxWindow::SetSize().
356 */
7c913512 357 void SetSizeHints(const wxSize& minSize,
4cc4bfaf
FM
358 const wxSize& maxSize = wxDefaultSize,
359 const wxSize& incSize = wxDefaultSize);
23324ae1
FM
360
361 /**
362 Sets the window title.
3c4f71cc 363
7c913512 364 @param title
4cc4bfaf 365 The window title.
3c4f71cc 366
4cc4bfaf 367 @see GetTitle()
23324ae1
FM
368 */
369 virtual void SetTitle(const wxString& title);
370
371 /**
f992f2ae 372 If the platform supports it will set the window to be translucent.
3c4f71cc 373
7c913512 374 @param alpha
f992f2ae
BP
375 Determines how opaque or transparent the window will be, if the
376 platform supports the opreration. A value of 0 sets the window to be
377 fully transparent, and a value of 255 sets the window to be fully
378 opaque.
23324ae1 379 */
cfbe5614 380 virtual bool SetTransparent(wxByte alpha);
23324ae1
FM
381
382 /**
f992f2ae
BP
383 This virtual function is not meant to be called directly but can be
384 overridden to return @false (it returns @true by default) to allow the
385 application to close even if this, presumably not very important, window
386 is still opened. By default, the application stays alive as long as
387 there are any open top level windows.
23324ae1 388 */
328f5751 389 virtual bool ShouldPreventAppExit() const;
23324ae1
FM
390
391 /**
f992f2ae
BP
392 Depending on the value of @a show parameter the window is either shown
393 full screen or restored to its normal state. @a style is a bit list
394 containing some or all of the following values, which indicate what
395 elements of the window to hide in full-screen mode:
396
397 - @c ::wxFULLSCREEN_NOMENUBAR
398 - @c ::wxFULLSCREEN_NOTOOLBAR
399 - @c ::wxFULLSCREEN_NOSTATUSBAR
400 - @c ::wxFULLSCREEN_NOBORDER
401 - @c ::wxFULLSCREEN_NOCAPTION
402 - @c ::wxFULLSCREEN_ALL (all of the above)
403
23324ae1 404 This function has not been tested with MDI frames.
f992f2ae
BP
405
406 @note Showing a window full screen also actually @ref wxWindow::Show()
407 "Show()"s the window if it isn't shown.
3c4f71cc 408
4cc4bfaf 409 @see IsFullScreen()
23324ae1 410 */
0004982c 411 virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
23324ae1
FM
412
413 /**
f992f2ae
BP
414 This method is specific to wxUniversal port.
415
416 Use native or custom-drawn decorations for this window only. Notice that
417 to have any effect this method must be called before really creating the
418 window, i.e. two step creation must be used:
419
420 @code
421 MyFrame *frame = new MyFrame; // use default ctor
422 frame->UseNativeDecorations(false); // change from default "true"
423 frame->Create(parent, title, ...); // really create the frame
424 @endcode
3c4f71cc 425
4cc4bfaf
FM
426 @see UseNativeDecorationsByDefault(),
427 IsUsingNativeDecorations()
23324ae1 428 */
4cc4bfaf 429 void UseNativeDecorations(bool native = true);
23324ae1
FM
430
431 /**
f992f2ae
BP
432 This method is specific to wxUniversal port.
433
434 Top level windows in wxUniversal port can use either system-provided
435 window decorations (i.e. title bar and various icons, buttons and menus
436 in it) or draw the decorations themselves. By default the system
437 decorations are used if they are available, but this method can be
438 called with @a native set to @false to change this for all windows
439 created after this point.
440
23324ae1 441 Also note that if @c WXDECOR environment variable is set, then custom
f992f2ae
BP
442 decorations are used by default and so it may make sense to call this
443 method with default argument if the application can't use custom
444 decorations at all for some reason.
77bfb902 445
f992f2ae 446 @see UseNativeDecorations()
23324ae1 447 */
4cc4bfaf 448 void UseNativeDecorationsByDefault(bool native = true);
23324ae1 449};
e54c96f1 450