]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/frame.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / frame.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: frame.h
e54c96f1 3// Purpose: interface of wxFrame
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
7d40f0a5
RD
8/**
9 Frame specific styles
10*/
11#define wxFRAME_NO_TASKBAR 0x0002 // No taskbar button (MSW only)
12#define wxFRAME_TOOL_WINDOW 0x0004 // No taskbar button, no system menu
13#define wxFRAME_FLOAT_ON_PARENT 0x0008 // Always above its parent
14
15
23324ae1
FM
16/**
17 @class wxFrame
7c913512 18
ea6a2ccb
FM
19 A frame is a window whose size and position can (usually) be changed by the user.
20
21 It usually has thick borders and a title bar, and can optionally contain a
22 menu bar, toolbar and status bar. A frame can contain any window that is not
23324ae1 23 a frame or dialog.
7c913512 24
ea6a2ccb
FM
25 A frame that has a status bar and toolbar, created via the CreateStatusBar() and
26 CreateToolBar() functions, manages these windows and adjusts the value returned
27 by GetClientSize() to reflect the remaining size available to application windows.
28
29 @remarks An application should normally define an wxCloseEvent handler for the
30 frame to respond to system close events, for example so that related
31 data and subwindows can be cleaned up.
32
33
674d80a7 34 @section frame_defaultevent Default event processing
ea6a2ccb
FM
35
36 wxFrame processes the following events:
37
38 @li @c wxEVT_SIZE: if the frame has exactly one child window, not counting the
39 status and toolbar, this child is resized to take the entire frame client area.
40 If two or more windows are present, they should be laid out explicitly either
9d157d59 41 by manually handling @c wxEVT_SIZE or using sizers;
ea6a2ccb
FM
42 @li @c wxEVT_MENU_HIGHLIGHT: the default implementation displays the help string
43 associated with the selected item in the first pane of the status bar, if there is one.
44
7c913512 45
23324ae1 46 @beginStyleTable
8c6791e4 47 @style{wxDEFAULT_FRAME_STYLE}
7c913512 48 Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER |
23324ae1 49 wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN.
8c6791e4 50 @style{wxICONIZE}
23324ae1 51 Display the frame iconized (minimized). Windows only.
8c6791e4 52 @style{wxCAPTION}
7832ada0
VZ
53 Puts a caption on the frame. Notice that this flag is required by
54 wxMINIMIZE_BOX, wxMAXIMIZE_BOX and wxCLOSE_BOX on most systems as
55 the corresponding buttons cannot be shown if the window has no title
56 bar at all. I.e. if wxCAPTION is not specified those styles would be
57 simply ignored.
8c6791e4 58 @style{wxMINIMIZE}
23324ae1 59 Identical to wxICONIZE. Windows only.
8c6791e4 60 @style{wxMINIMIZE_BOX}
23324ae1 61 Displays a minimize box on the frame.
8c6791e4 62 @style{wxMAXIMIZE}
62fc18ef 63 Displays the frame maximized. Windows and GTK+ only.
8c6791e4 64 @style{wxMAXIMIZE_BOX}
7832ada0
VZ
65 Displays a maximize box on the frame. Notice that under wxGTK
66 wxRESIZE_BORDER must be used as well or this style is ignored.
8c6791e4 67 @style{wxCLOSE_BOX}
23324ae1 68 Displays a close box on the frame.
8c6791e4 69 @style{wxSTAY_ON_TOP}
23324ae1 70 Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT.
8c6791e4 71 @style{wxSYSTEM_MENU}
7832ada0
VZ
72 Displays a system menu containing the list of various windows
73 commands in the window title bar. Unlike wxMINIMIZE_BOX,
74 wxMAXIMIZE_BOX and wxCLOSE_BOX styles this style can be used without
75 wxCAPTION, at least under Windows, and makes the system menu
76 available without showing it on screen in this case. However it is
77 recommended to only use it together with wxCAPTION for consistent
78 behaviour under all platforms.
8c6791e4 79 @style{wxRESIZE_BORDER}
d13b34d3 80 Displays a resizable border around the window.
8c6791e4 81 @style{wxFRAME_TOOL_WINDOW}
7832ada0 82 Causes a frame with a small title bar to be created; the frame does
23324ae1 83 not appear in the taskbar under Windows or GTK+.
8c6791e4 84 @style{wxFRAME_NO_TASKBAR}
23324ae1
FM
85 Creates an otherwise normal frame but it does not appear in the
86 taskbar under Windows or GTK+ (note that it will minimize to the
87 desktop window under Windows which may seem strange to the users
88 and thus it might be better to use this style only without
7832ada0
VZ
89 wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if the
90 window manager supports _NET_WM_STATE_SKIP_TASKBAR hint.
8c6791e4 91 @style{wxFRAME_FLOAT_ON_PARENT}
ea6a2ccb
FM
92 The frame will always be on top of its parent (unlike wxSTAY_ON_TOP).
93 A frame created with this style must have a non-@NULL parent.
94 @style{wxFRAME_SHAPED}
7832ada0 95 Windows with this style are allowed to have their shape changed
ea6a2ccb
FM
96 with the SetShape() method.
97 @endStyleTable
98
d13b34d3 99 The default frame style is for normal, resizable frames.
4c51a665 100 To create a frame which cannot be resized by user, you may use the following
ea6a2ccb
FM
101 combination of styles:
102
103 @code
15840e67 104 wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxMAXIMIZE_BOX)
ea6a2ccb
FM
105 @endcode
106
107 See also the @ref overview_windowstyles.
108
109 @beginExtraStyleTable
8c6791e4 110 @style{wxFRAME_EX_CONTEXTHELP}
23324ae1
FM
111 Under Windows, puts a query button on the caption. When pressed,
112 Windows will go into a context-sensitive help mode and wxWidgets
3a194bda 113 will send a @c wxEVT_HELP event if the user clicked on an application
23324ae1
FM
114 window. Note that this is an extended style and must be set by
115 calling SetExtraStyle before Create is called (two-step
116 construction). You cannot use this style together with
117 wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use
118 wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the
119 frames having this style (the dialogs don't have a minimize or a
120 maximize box by default)
8c6791e4 121 @style{wxFRAME_EX_METAL}
23324ae1
FM
122 On Mac OS X, frames with this style will be shown with a metallic
123 look. This is an extra style.
ea6a2ccb 124 @endExtraStyleTable
7c913512 125
3051a44a 126 @beginEventEmissionTable
9d157d59 127 @event{EVT_CLOSE(func)}
96b57f0d
VZ
128 Process a @c wxEVT_CLOSE_WINDOW event when the frame is being
129 closed by the user or programmatically (see wxWindow::Close).
9d157d59
FM
130 The user may generate this event clicking the close button
131 (typically the 'X' on the top-right of the title bar) if it's present
3051a44a
FM
132 (see the @c wxCLOSE_BOX style). See wxCloseEvent.
133 @event{EVT_ICONIZE(func)}
134 Process a @c wxEVT_ICONIZE event. See wxIconizeEvent.
135 @event{EVT_MENU_OPEN(func)}
136 A menu is about to be opened. See wxMenuEvent.
137 @event{EVT_MENU_CLOSE(func)}
138 A menu has been just closed. See wxMenuEvent.
139 @event{EVT_MENU_HIGHLIGHT(id, func)}
140 The menu item with the specified id has been highlighted: used to show
141 help prompts in the status bar by wxFrame. See wxMenuEvent.
142 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
143 A menu item has been highlighted, i.e. the currently selected menu item has changed.
144 See wxMenuEvent.
9d157d59
FM
145 @endEventTable
146
23324ae1
FM
147 @library{wxcore}
148 @category{managedwnd}
7c913512 149
e54c96f1 150 @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
23324ae1
FM
151*/
152class wxFrame : public wxTopLevelWindow
153{
154public:
674d80a7
FM
155 /**
156 Default constructor.
157 */
158 wxFrame();
159
23324ae1
FM
160 /**
161 Constructor, creating the window.
3c4f71cc 162
7c913512 163 @param parent
4cc4bfaf
FM
164 The window parent. This may be @NULL. If it is non-@NULL, the frame will
165 always be displayed on top of the parent window on Windows.
7c913512 166 @param id
674d80a7 167 The window identifier. It may take a value of -1 to indicate a default value.
7c913512 168 @param title
4cc4bfaf 169 The caption to be displayed on the frame's title bar.
7c913512 170 @param pos
4cc4bfaf 171 The window position. The value wxDefaultPosition indicates a default position,
674d80a7 172 chosen by either the windowing system or wxWidgets, depending on platform.
7c913512 173 @param size
4cc4bfaf
FM
174 The window size. The value wxDefaultSize indicates a default size, chosen by
175 either the windowing system or wxWidgets, depending on platform.
7c913512 176 @param style
674d80a7 177 The window style. See wxFrame class description.
7c913512 178 @param name
674d80a7
FM
179 The name of the window. This parameter is used to associate a name with
180 the item, allowing the application user to set Motif resource values for
4cc4bfaf 181 individual windows.
3c4f71cc 182
23324ae1 183 @remarks For Motif, MWM (the Motif Window Manager) should be running for
674d80a7 184 any window styles to work (otherwise all styles take effect).
3c4f71cc 185
4cc4bfaf 186 @see Create()
23324ae1 187 */
7c913512
FM
188 wxFrame(wxWindow* parent, wxWindowID id,
189 const wxString& title,
190 const wxPoint& pos = wxDefaultPosition,
191 const wxSize& size = wxDefaultSize,
192 long style = wxDEFAULT_FRAME_STYLE,
408776d0 193 const wxString& name = wxFrameNameStr);
23324ae1
FM
194
195 /**
196 Destructor. Destroys all child windows and menu bar if present.
2e4f32d7
FM
197
198 See @ref overview_windowdeletion for more info.
23324ae1 199 */
adaaa686 200 virtual ~wxFrame();
23324ae1
FM
201
202 /**
203 Centres the frame on the display.
3c4f71cc 204
7c913512 205 @param direction
4cc4bfaf 206 The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
23324ae1
FM
207 */
208 void Centre(int direction = wxBOTH);
209
210 /**
674d80a7
FM
211 Used in two-step frame construction.
212 See wxFrame() for further details.
23324ae1 213 */
43c48e1e 214 bool Create(wxWindow* parent, wxWindowID id, const wxString& title,
23324ae1
FM
215 const wxPoint& pos = wxDefaultPosition,
216 const wxSize& size = wxDefaultSize,
217 long style = wxDEFAULT_FRAME_STYLE,
43c48e1e 218 const wxString& name = wxFrameNameStr);
23324ae1
FM
219
220 /**
221 Creates a status bar at the bottom of the frame.
3c4f71cc 222
7c913512 223 @param number
4cc4bfaf
FM
224 The number of fields to create. Specify a
225 value greater than 1 to create a multi-field status bar.
7c913512 226 @param style
674d80a7 227 The status bar style. See wxStatusBar for a list of valid styles.
7c913512 228 @param id
674d80a7
FM
229 The status bar window identifier. If -1, an identifier will be chosen
230 by wxWidgets.
7c913512 231 @param name
4cc4bfaf 232 The status bar window name.
3c4f71cc 233
d29a9a8a 234 @return A pointer to the status bar if it was created successfully, @NULL
674d80a7 235 otherwise.
3c4f71cc 236
23324ae1 237 @remarks The width of the status bar is the whole width of the frame
4cc4bfaf
FM
238 (adjusted automatically when resizing), and the height
239 and text size are chosen by the host windowing system.
3c4f71cc 240
4cc4bfaf 241 @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
23324ae1 242 */
c4c178c1 243 virtual wxStatusBar* CreateStatusBar(int number = 1, long style = wxSTB_DEFAULT_STYLE,
43c48e1e 244 wxWindowID id = 0,
6fc53251 245 const wxString& name = wxStatusBarNameStr);
23324ae1
FM
246
247 /**
248 Creates a toolbar at the top or left of the frame.
3c4f71cc 249
7c913512 250 @param style
674d80a7 251 The toolbar style. See wxToolBar for a list of valid styles.
7c913512 252 @param id
674d80a7
FM
253 The toolbar window identifier. If -1, an identifier will be chosen
254 by wxWidgets.
7c913512 255 @param name
4cc4bfaf 256 The toolbar window name.
3c4f71cc 257
d29a9a8a 258 @return A pointer to the toolbar if it was created successfully, @NULL
674d80a7 259 otherwise.
3c4f71cc 260
bb69632a
FM
261 @remarks
262 By default, the toolbar is an instance of wxToolBar.
263 To use a different class, override OnCreateToolBar().
264 When a toolbar has been created with this function, or made
265 known to the frame with wxFrame::SetToolBar(), the frame will
266 manage the toolbar position and adjust the return value from
267 wxWindow::GetClientSize() to reflect the available space for
268 application windows.
269 Under Pocket PC, you should always use this function for creating
270 the toolbar to be managed by the frame, so that wxWidgets can
271 use a combined menubar and toolbar.
272 Where you manage your own toolbars, create a wxToolBar as usual.
674d80a7
FM
273
274 @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
23324ae1 275 */
f75b1bd3 276 virtual wxToolBar* CreateToolBar(long style = wxTB_DEFAULT_STYLE,
43c48e1e
FM
277 wxWindowID id = wxID_ANY,
278 const wxString& name = wxToolBarNameStr);
23324ae1
FM
279
280 /**
674d80a7
FM
281 Returns the origin of the frame client area (in client coordinates).
282 It may be different from (0, 0) if the frame has a toolbar.
23324ae1 283 */
adaaa686 284 virtual wxPoint GetClientAreaOrigin() const;
23324ae1
FM
285
286 /**
287 Returns a pointer to the menubar currently associated with the frame (if any).
3c4f71cc 288
4cc4bfaf 289 @see SetMenuBar(), wxMenuBar, wxMenu
23324ae1 290 */
adaaa686 291 virtual wxMenuBar* GetMenuBar() const;
23324ae1
FM
292
293 /**
674d80a7
FM
294 Returns a pointer to the status bar currently associated with the frame
295 (if any).
3c4f71cc 296
4cc4bfaf 297 @see CreateStatusBar(), wxStatusBar
23324ae1 298 */
adaaa686 299 virtual wxStatusBar* GetStatusBar() const;
23324ae1
FM
300
301 /**
302 Returns the status bar pane used to display menu and toolbar help.
3c4f71cc 303
4cc4bfaf 304 @see SetStatusBarPane()
23324ae1 305 */
adaaa686 306 int GetStatusBarPane() const;
23324ae1
FM
307
308 /**
309 Returns a pointer to the toolbar currently associated with the frame (if any).
3c4f71cc 310
4cc4bfaf 311 @see CreateToolBar(), wxToolBar, SetToolBar()
23324ae1 312 */
adaaa686 313 virtual wxToolBar* GetToolBar() const;
23324ae1
FM
314
315 /**
316 Virtual function called when a status bar is requested by CreateStatusBar().
3c4f71cc 317
7c913512 318 @param number
4cc4bfaf 319 The number of fields to create.
7c913512 320 @param style
4cc4bfaf
FM
321 The window style. See wxStatusBar for a list
322 of valid styles.
7c913512 323 @param id
4cc4bfaf
FM
324 The window identifier. If -1, an identifier will be chosen by
325 wxWidgets.
7c913512 326 @param name
4cc4bfaf 327 The window name.
3c4f71cc 328
d29a9a8a 329 @return A status bar object.
3c4f71cc 330
23324ae1 331 @remarks An application can override this function to return a different
4cc4bfaf
FM
332 kind of status bar. The default implementation returns
333 an instance of wxStatusBar.
3c4f71cc 334
4cc4bfaf 335 @see CreateStatusBar(), wxStatusBar.
23324ae1
FM
336 */
337 virtual wxStatusBar* OnCreateStatusBar(int number, long style,
338 wxWindowID id,
339 const wxString& name);
340
341 /**
342 Virtual function called when a toolbar is requested by CreateToolBar().
3c4f71cc 343
7c913512 344 @param style
4cc4bfaf
FM
345 The toolbar style. See wxToolBar for a list
346 of valid styles.
7c913512 347 @param id
4cc4bfaf
FM
348 The toolbar window identifier. If -1, an identifier will be chosen by
349 wxWidgets.
7c913512 350 @param name
4cc4bfaf 351 The toolbar window name.
3c4f71cc 352
d29a9a8a 353 @return A toolbar object.
3c4f71cc 354
23324ae1 355 @remarks An application can override this function to return a different
4cc4bfaf
FM
356 kind of toolbar. The default implementation returns an
357 instance of wxToolBar.
3c4f71cc 358
4cc4bfaf 359 @see CreateToolBar(), wxToolBar.
23324ae1
FM
360 */
361 virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
362 const wxString& name);
363
364 /**
365 Simulate a menu command.
3c4f71cc 366
7c913512 367 @param id
4cc4bfaf 368 The identifier for a menu item.
23324ae1 369 */
a44f3b5a 370 bool ProcessCommand(int id);
23324ae1 371
23324ae1
FM
372 /**
373 Tells the frame to show the given menu bar.
3c4f71cc 374
7c913512 375 @param menuBar
4cc4bfaf 376 The menu bar to associate with the frame.
3c4f71cc 377
23324ae1 378 @remarks If the frame is destroyed, the menu bar and its menus will be
4cc4bfaf
FM
379 destroyed also, so do not delete the menu bar
380 explicitly (except by resetting the frame's menu bar to
381 another frame or @NULL).
674d80a7
FM
382 Under Windows, a size event is generated, so be sure to
383 initialize data members properly before calling SetMenuBar().
384 Note that on some platforms, it is not possible to call this
385 function twice for the same frame object.
3c4f71cc 386
4cc4bfaf 387 @see GetMenuBar(), wxMenuBar, wxMenu.
23324ae1 388 */
adaaa686 389 virtual void SetMenuBar(wxMenuBar* menuBar);
23324ae1
FM
390
391 /**
392 Associates a status bar with the frame.
3c4f71cc 393
c4c178c1
FM
394 If @a statusBar is @NULL, then the status bar, if present, is detached from
395 the frame, but @e not deleted.
396
4cc4bfaf 397 @see CreateStatusBar(), wxStatusBar, GetStatusBar()
23324ae1 398 */
adaaa686 399 virtual void SetStatusBar(wxStatusBar* statusBar);
23324ae1
FM
400
401 /**
402 Set the status bar pane used to display menu and toolbar help.
403 Using -1 disables help display.
404 */
405 void SetStatusBarPane(int n);
406
407 /**
408 Sets the status bar text and redraws the status bar.
3c4f71cc 409
7c913512 410 @param text
4cc4bfaf 411 The text for the status field.
7c913512 412 @param number
4cc4bfaf 413 The status field (starting from zero).
3c4f71cc 414
23324ae1 415 @remarks Use an empty string to clear the status bar.
3c4f71cc 416
4cc4bfaf 417 @see CreateStatusBar(), wxStatusBar
23324ae1
FM
418 */
419 virtual void SetStatusText(const wxString& text, int number = 0);
420
421 /**
422 Sets the widths of the fields in the status bar.
3c4f71cc 423
7c913512 424 @param n
4cc4bfaf
FM
425 The number of fields in the status bar. It must be the
426 same used in CreateStatusBar.
f21dd16b 427 @param widths_field
4cc4bfaf
FM
428 Must contain an array of n integers, each of which is a status field width
429 in pixels. A value of -1 indicates that the field is variable width; at
674d80a7
FM
430 least one field must be -1. You should delete this array after calling
431 SetStatusWidths().
3c4f71cc 432
23324ae1 433 @remarks The widths of the variable fields are calculated from the total
4cc4bfaf 434 width of all fields, minus the sum of widths of the
674d80a7 435 non-variable fields, divided by the number of variable fields.
1058f652
MB
436
437 @beginWxPerlOnly
438 In wxPerl this method takes the field widths as parameters.
439 @endWxPerlOnly
23324ae1 440 */
43c48e1e 441 virtual void SetStatusWidths(int n, const int* widths_field);
23324ae1
FM
442
443 /**
444 Associates a toolbar with the frame.
445 */
adaaa686 446 virtual void SetToolBar(wxToolBar* toolBar);
05b0355a
RD
447
448
449 void PushStatusText(const wxString &text, int number = 0);
450 void PopStatusText(int number = 0);
451
23324ae1 452};
e54c96f1 453