]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/frame.tex
documented wxCONFIG_USE_RELATIVE_PATH
[wxWidgets.git] / docs / latex / wx / frame.tex
1 \section{\class{wxFrame}}\label{wxframe}
2
3 A frame is a window whose size and position can (usually) be changed by the user. It usually has
4 thick borders and a title bar, and can optionally contain a menu bar, toolbar and
5 status bar. A frame can contain any window that is not a frame or dialog.
6
7 A frame that has a status bar and toolbar created via the CreateStatusBar/CreateToolBar functions
8 manages these windows, and adjusts the value returned by GetClientSize to reflect
9 the remaining size available to application windows.
10
11 \wxheading{Derived from}
12
13 \helpref{wxWindow}{wxwindow}\\
14 \helpref{wxEvtHandler}{wxevthandler}\\
15 \helpref{wxObject}{wxobject}
16
17 \wxheading{Include files}
18
19 <wx/frame.h>
20
21 \wxheading{Window styles}
22
23 \twocolwidtha{5cm}
24 \begin{twocollist}\itemsep=0pt
25 \twocolitem{\windowstyle{wxICONIZE}}{Display the frame iconized (minimized) (Windows only).}
26 \twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the frame.}
27 \twocolitem{\windowstyle{wxDEFAULT\_FRAME\_STYLE}}{Defined as {\bf wxMINIMIZE\_BOX \pipe wxMAXIMIZE\_BOX \pipe wxTHICK\_FRAME \pipe wxSYSTEM\_MENU \pipe wxCAPTION}.}
28 \twocolitem{\windowstyle{wxMINIMIZE}}{Identical to {\bf wxICONIZE}.}
29 \twocolitem{\windowstyle{wxMINIMIZE\_BOX}}{Displays a minimize box on the frame (Windows and Motif only).}
30 \twocolitem{\windowstyle{wxMAXIMIZE}}{Displays the frame maximized (Windows only).}
31 \twocolitem{\windowstyle{wxMAXIMIZE\_BOX}}{Displays a maximize box on the frame (Windows and Motif only).}
32 \twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{Stay on top of other windows (Windows only).}
33 \twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Displays a system menu (Windows and Motif only).}
34 \twocolitem{\windowstyle{wxTHICK\_FRAME}}{Displays a thick frame around the window (Windows and Motif only).}
35 \twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Displays a resizeable border around the window (Motif only).}
36 \twocolitem{\windowstyle{wxFRAME\_FLOAT\_ON\_PARENT}}{Windows only. Causes the frame to be above the parent window in the
37 z-order and not shown in the taskbar. Without this style, frames are created as top-level windows that may be obscured by
38 the parent window, and frame titles are shown in the taskbar. On Motif and GTK, the behaviour is always as if this
39 style is not specified.}
40 \twocolitem{\windowstyle{wxFRAME\_TOOL\_WINDOW}}{Windows only. Causes a frame with a small titlebar to be created;
41 the frame title does not appear in the taskbar.}
42 \end{twocollist}
43
44 See also \helpref{window styles overview}{windowstyles}. Currently the GTK port of wxWindows
45 ignores all the window styles listed above as there is no standard way (yet) to inform the
46 window manager about such options. Therefore, the only relevant window style flag which
47 the GTK port recognizes is \windowstyle{wxSIMPLE\_BORDER} which brings up a frame without
48 any window decorations. This can be used for a splash screen or specialized tooltip etc.
49
50 \wxheading{Remarks}
51
52 An application should normally define an \helpref{OnCloseWindow}{wxwindowonclosewindow} handler for the
53 frame to respond to system close events, for example so that related data and subwindows can be cleaned up.
54
55 \wxheading{See also}
56
57 \helpref{wxMDIParentFrame}{wxmdiparentframe}, \helpref{wxMDIChildFrame}{wxmdichildframe},\rtfsp
58 \helpref{wxMiniFrame}{wxminiframe}, \helpref{wxDialog}{wxdialog}
59
60 \latexignore{\rtfignore{\wxheading{Members}}}
61
62 \membersection{wxFrame::wxFrame}\label{wxframeconstr}
63
64 \func{}{wxFrame}{\void}
65
66 Default constructor.
67
68 \func{}{wxFrame}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
69 \param{const wxString\& }{title}, \param{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
70 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = wxDEFAULT\_FRAME\_STYLE},\rtfsp
71 \param{const wxString\& }{name = ``frame"}}
72
73 Constructor, creating the window.
74
75 \wxheading{Parameters}
76
77 \docparam{parent}{The window parent. This may be NULL. If it is non-NULL, the frame will
78 always be displayed on top of the parent window on Windows.}
79
80 \docparam{id}{The window identifier. It may take a value of -1 to indicate a default value.}
81
82 \docparam{title}{The caption to be displayed on the frame's title bar.}
83
84 \docparam{pos}{The window position. A value of (-1, -1) indicates a default position, chosen by
85 either the windowing system or wxWindows, depending on platform.}
86
87 \docparam{size}{The window size. A value of (-1, -1) indicates a default size, chosen by
88 either the windowing system or wxWindows, depending on platform.}
89
90 \docparam{style}{The window style. See \helpref{wxFrame}{wxframe}.}
91
92 \docparam{name}{The name of the window. This parameter is used to associate a name with the item,
93 allowing the application user to set Motif resource values for
94 individual windows.}
95
96 \wxheading{Remarks}
97
98 For Motif, MWM (the Motif Window Manager) should be running for any window styles to work
99 (otherwise all styles take effect).
100
101 \wxheading{See also}
102
103 \helpref{wxFrame::Create}{wxframecreate}
104
105 \membersection{wxFrame::\destruct{wxFrame}}
106
107 \func{void}{\destruct{wxFrame}}{\void}
108
109 Destructor. Destroys all child windows and menu bar if present.
110
111 \membersection{wxFrame::Centre}\label{wxframecentre}
112
113 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}
114
115 Centres the frame on the display.
116
117 \wxheading{Parameters}
118
119 \docparam{direction}{The parameter may be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}
120
121 \membersection{wxFrame::Command}\label{wxframecommand}
122
123 \func{void}{Command}{\param{int }{id}}
124
125 Simulate a menu command.
126
127 \wxheading{Parameters}
128
129 \docparam{id}{The identifier for a menu item.}
130
131 \membersection{wxFrame::Create}\label{wxframecreate}
132
133 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
134 \param{const wxString\& }{title}, \param{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
135 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = wxDEFAULT\_FRAME\_STYLE},\rtfsp
136 \param{const wxString\& }{name = ``frame"}}
137
138 Used in two-step frame construction. See \helpref{wxFrame::wxFrame}{wxframeconstr}\rtfsp
139 for further details.
140
141 \membersection{wxFrame::CreateStatusBar}\label{wxframecreatestatusbar}
142
143 \func{virtual wxStatusBar*}{CreateStatusBar}{\param{int}{ number = 1},
144 \param{long}{ style = 0},
145 \param{wxWindowID}{ id = -1}, \param{const wxString\&}{ name = "statusBar"}}
146
147 Creates a status bar at the bottom of the frame.
148
149 \wxheading{Parameters}
150
151 \docparam{number}{The number of fields to create. Specify a
152 value greater than 1 to create a multi-field status bar.}
153
154 \docparam{style}{The status bar style. See \helpref{wxStatusBar}{wxstatusbar} for a list
155 of valid styles.}
156
157 \docparam{id}{The status bar window identifier. If -1, an identifier will be chosen by
158 wxWindows.}
159
160 \docparam{name}{The status bar window name.}
161
162 \wxheading{Return value}
163
164 A pointer to the the status bar if it was created successfully, NULL otherwise.
165
166 \wxheading{Remarks}
167
168 The width of the status bar is the whole width of the frame (adjusted automatically when
169 resizing), and the height and text size are chosen by the host windowing system.
170
171 By default, the status bar is an instance of wxStatusBar. To use a different class,
172 override \helpref{wxFrame::OnCreateStatusBar}{wxframeoncreatestatusbar}.
173
174 Note that you can put controls and other windows on the status bar if you wish.
175
176 \wxheading{See also}
177
178 \helpref{wxFrame::SetStatusText}{wxframesetstatustext},\rtfsp
179 \helpref{wxFrame::OnCreateStatusBar}{wxframeoncreatestatusbar},\rtfsp
180 \helpref{wxFrame::GetStatusBar}{wxframegetstatusbar}
181
182 \membersection{wxFrame::CreateToolBar}\label{wxframecreatetoolbar}
183
184 \func{virtual wxToolBar*}{CreateToolBar}{\param{long}{ style = wxNO\_BORDER \pipe wxTB\_HORIZONTAL},
185 \param{wxWindowID}{ id = -1}, \param{const wxString\&}{ name = "toolBar"}}
186
187 Creates a toolbar at the top or left of the frame.
188
189 \wxheading{Parameters}
190
191 \docparam{style}{The toolbar style. See \helpref{wxToolBar}{wxtoolbar} for a list
192 of valid styles.}
193
194 \docparam{id}{The toolbar window identifier. If -1, an identifier will be chosen by
195 wxWindows.}
196
197 \docparam{name}{The toolbar window name.}
198
199 \wxheading{Return value}
200
201 A pointer to the the toolbar if it was created successfully, NULL otherwise.
202
203 \wxheading{Remarks}
204
205 By default, the toolbar is an instance of wxToolBar (which is defined to be
206 a suitable toolbar class on each platform, such as wxToolBar95). To use a different class,
207 override \helpref{wxFrame::OnCreateToolBar}{wxframeoncreatetoolbar}.
208
209 When a toolbar has been created with this function, or made known to the frame
210 with \helpref{wxFrame::SetToolBar}{wxframesettoolbar}, the frame will manage the toolbar
211 position and adjust the return value from \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize} to
212 reflect the available space for application windows.
213
214 \wxheading{See also}
215
216 \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar},\rtfsp
217 \helpref{wxFrame::OnCreateToolBar}{wxframeoncreatetoolbar},\rtfsp
218 \helpref{wxFrame::SetToolBar}{wxframesettoolbar},\rtfsp
219 \helpref{wxFrame::GetToolBar}{wxframegettoolbar}
220
221 \membersection{wxFrame::GetMenuBar}\label{wxframegetmenubar}
222
223 \constfunc{wxMenuBar*}{GetMenuBar}{\void}
224
225 Returns a pointer to the menubar currently associated with the frame (if any).
226
227 \wxheading{See also}
228
229 \helpref{wxFrame::SetMenuBar}{wxframesetmenubar}, \helpref{wxMenuBar}{wxmenubar}, \helpref{wxMenu}{wxmenu}
230
231 \membersection{wxFrame::GetStatusBar}\label{wxframegetstatusbar}
232
233 \func{wxStatusBar*}{GetStatusBar}{\void}
234
235 Returns a pointer to the status bar currently associated with the frame (if any).
236
237 \wxheading{See also}
238
239 \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar}, \helpref{wxStatusBar}{wxstatusbar}
240
241 \membersection{wxFrame::GetTitle}\label{wxframegettitle}
242
243 \func{wxString\&}{GetTitle}{\void}
244
245 Gets a temporary pointer to the frame title. See
246 \helpref{wxFrame::SetTitle}{wxframesettitle}.
247
248 \membersection{wxFrame::GetToolBar}\label{wxframegettoolbar}
249
250 \func{wxToolBar*}{GetToolBar}{\void}
251
252 Returns a pointer to the toolbar currently associated with the frame (if any).
253
254 \wxheading{See also}
255
256 \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}, \helpref{wxToolBar}{wxtoolbar},\rtfsp
257 \helpref{wxFrame::SetToolBar}{wxframesettoolbar}
258
259 \membersection{wxFrame::Iconize}\label{wxframeiconize}
260
261 \func{void}{Iconize}{\param{const bool}{ iconize}}
262
263 Iconizes or restores the frame.
264
265 \wxheading{Parameters}
266
267 \docparam{izonize}{If TRUE, iconizes the frame; if FALSE, shows and restores it.}
268
269 \wxheading{See also}
270
271 \helpref{wxFrame::IsIconized}{wxframeisiconized}, \helpref{wxFrame::Maximize}{wxframemaximize}.
272
273 \membersection{wxFrame::IsIconized}\label{wxframeisiconized}
274
275 \constfunc{bool}{IsIconized}{\void}
276
277 Returns TRUE if the frame is iconized.
278
279 \membersection{wxFrame::IsMaximized}\label{wxframeismaximized}
280
281 \constfunc{bool}{IsMaximized}{\void}
282
283 Returns TRUE if the frame is maximized.
284
285 \membersection{wxFrame::Maximize}\label{wxframemaximize}
286
287 \func{void}{Maximize}{\param{const bool }{maximize}}
288
289 Maximizes or restores the frame.
290
291 \wxheading{Parameters}
292
293 \docparam{maximize}{If TRUE, maximizes the frame, otherwise it restores it}.
294
295 \wxheading{Remarks}
296
297 This function only works under Windows.
298
299 \wxheading{See also}
300
301 \helpref{wxFrame::Iconize}{wxframeiconize}
302
303 \membersection{wxFrame::OnActivate}
304
305 \func{void}{OnActivate}{\param{wxActivateEvent\&}{ event}}
306
307 Called when a window is activated or deactivated (MS Windows
308 only). See also \helpref{wxActivateEvent}{wxactivateevent}.
309
310 \membersection{wxFrame::OnCreateStatusBar}\label{wxframeoncreatestatusbar}
311
312 \func{virtual wxStatusBar*}{OnCreateStatusBar}{\param{int }{number},
313 \param{long}{ style},
314 \param{wxWindowID}{ id}, \param{const wxString\&}{ name}}
315
316 Virtual function called when a status bar is requested by \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar}.
317
318 \wxheading{Parameters}
319
320 \docparam{number}{The number of fields to create.}
321
322 \docparam{style}{The window style. See \helpref{wxStatusBar}{wxstatusbar} for a list
323 of valid styles.}
324
325 \docparam{id}{The window identifier. If -1, an identifier will be chosen by
326 wxWindows.}
327
328 \docparam{name}{The window name.}
329
330 \wxheading{Return value}
331
332 A status bar object.
333
334 \wxheading{Remarks}
335
336 An application can override this function to return a different kind of status bar. The default
337 implementation returns an instance of \helpref{wxStatusBar}{wxstatusbar}.
338
339 \wxheading{See also}
340
341 \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar}, \helpref{wxStatusBar}{wxstatusbar}.
342
343 \membersection{wxFrame::OnCreateToolBar}\label{wxframeoncreatetoolbar}
344
345 \func{virtual wxToolBar*}{OnCreateToolBar}{\param{long}{ style},
346 \param{wxWindowID}{ id}, \param{const wxString\&}{ name}}
347
348 Virtual function called when a toolbar is requested by \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}.
349
350 \wxheading{Parameters}
351
352 \docparam{style}{The toolbar style. See \helpref{wxToolBar}{wxtoolbar} for a list
353 of valid styles.}
354
355 \docparam{id}{The toolbar window identifier. If -1, an identifier will be chosen by
356 wxWindows.}
357
358 \docparam{name}{The toolbar window name.}
359
360 \wxheading{Return value}
361
362 A toolbar object.
363
364 \wxheading{Remarks}
365
366 An application can override this function to return a different kind of toolbar. The default
367 implementation returns an instance of \helpref{wxToolBar}{wxtoolbar}.
368
369 \wxheading{See also}
370
371 \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}, \helpref{wxToolBar}{wxtoolbar}.
372
373 \membersection{wxFrame::OnMenuCommand}\label{wxframeonmenucommand}
374
375 \func{void}{OnMenuCommand}{\param{wxCommandEvent\&}{ event}}
376
377 See \helpref{wxWindow::OnMenuCommand}{wxwindowonmenucommand}.
378
379 \membersection{wxFrame::OnMenuHighlight}\label{wxframeonmenuhighlight}
380
381 \func{void}{OnMenuHighlight}{\param{wxMenuEvent\&}{ event}}
382
383 See \helpref{wxWindow::OnMenuHighlight}{wxwindowonmenuhighlight}.
384
385 \membersection{wxFrame::OnSize}\label{wxframeonsize}
386
387 \func{void}{OnSize}{\param{wxSizeEvent\& }{event}}
388
389 See \helpref{wxWindow::OnSize}{wxwindowonsize}.
390
391 The default {\bf wxFrame::OnSize} implementation looks for a single subwindow,
392 and if one is found, resizes it to fit
393 inside the frame. Override this member if more complex behaviour
394 is required (for example, if there are several subwindows).
395
396 \membersection{wxFrame::SetIcon}\label{wxframeseticon}
397
398 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
399
400 Sets the icon for this frame.
401
402 \wxheading{Parameters}
403
404 \docparam{icon}{The icon to associate with this frame.}
405
406 \wxheading{Remarks}
407
408 The frame takes a `copy' of {\it icon}, but since it uses reference
409 counting, the copy is very quick. It is safe to delete {\it icon} after
410 calling this function.
411
412 Under Windows, instead of using {\bf SetIcon}, you can add the
413 following lines to your MS Windows resource file:
414
415 \begin{verbatim}
416 wxSTD_MDIPARENTFRAME ICON icon1.ico
417 wxSTD_MDICHILDFRAME ICON icon2.ico
418 wxSTD_FRAME ICON icon3.ico
419 \end{verbatim}
420
421 where icon1.ico will be used for the MDI parent frame, icon2.ico
422 will be used for MDI child frames, and icon3.ico will be used for
423 non-MDI frames.
424
425 If these icons are not supplied, and {\bf SetIcon} is not called either,
426 then the following defaults apply if you have included wx.rc.
427
428 \begin{verbatim}
429 wxDEFAULT_FRAME ICON std.ico
430 wxDEFAULT_MDIPARENTFRAME ICON mdi.ico
431 wxDEFAULT_MDICHILDFRAME ICON child.ico
432 \end{verbatim}
433
434 You can replace std.ico, mdi.ico and child.ico with your own defaults
435 for all your wxWindows application. Currently they show the same icon.
436
437 {\it Note:} a wxWindows application linked with subsystem equal to 4.0
438 (i.e. marked as a Windows 95 application) doesn't respond properly
439 to wxFrame::SetIcon. To work around this until a solution is found,
440 mark your program as a 3.5 application. This will also ensure
441 that Windows provides small icons for the application automatically.
442
443 See also \helpref{wxIcon}{wxicon}.
444
445 \membersection{wxFrame::SetMenuBar}\label{wxframesetmenubar}
446
447 \func{void}{SetMenuBar}{\param{wxMenuBar* }{menuBar}}
448
449 Tells the frame to show the given menu bar.
450
451 \wxheading{Parameters}
452
453 \docparam{menuBar}{The menu bar to associate with the frame.}
454
455 \wxheading{Remarks}
456
457 If the frame is destroyed, the
458 menu bar and its menus will be destroyed also, so do not delete the menu
459 bar explicitly (except by resetting the frame's menu bar to another
460 frame or NULL).
461
462 Under Windows, a call to \helpref{wxFrame::OnSize}{wxframeonsize} is generated, so be sure to initialize
463 data members properly before calling {\bf SetMenuBar}.
464
465 Note that it is not possible to call this function twice for the same frame object.
466
467 \wxheading{See also}
468
469 \helpref{wxFrame::GetMenuBar}{wxframegetmenubar}, \helpref{wxMenuBar}{wxmenubar}, \helpref{wxMenu}{wxmenu}.
470
471 \membersection{wxFrame::SetStatusBar}\label{wxframesetstatusbar}
472
473 \func{void}{SetStatusBar}{\param{wxStatusBar*}{ statusBar}}
474
475 Associates a status bar with the frame.
476
477 \wxheading{See also}
478
479 \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar}, \helpref{wxStatusBar}{wxstatusbar},\rtfsp
480 \helpref{wxFrame::GetStatusBar}{wxframegetstatusbar}
481
482 \membersection{wxFrame::SetStatusText}\label{wxframesetstatustext}
483
484 \func{virtual void}{SetStatusText}{\param{const wxString\& }{ text}, \param{int}{ number = 0}}
485
486 Sets the status bar text and redraws the status bar.
487
488 \wxheading{Parameters}
489
490 \docparam{text}{The text for the status field.}
491
492 \docparam{number}{The status field (starting from zero).}
493
494 \wxheading{Remarks}
495
496 Use an empty string to clear the status bar.
497
498 \wxheading{See also}
499
500 \helpref{wxFrame::CreateStatusBar}{wxframecreatestatusbar}, \helpref{wxStatusBar}{wxstatusbar}
501
502 \membersection{wxFrame::SetStatusWidths}\label{wxframesetstatuswidths}
503
504 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
505
506 Sets the widths of the fields in the status bar.
507
508 \wxheading{Parameters}
509
510 \wxheading{n}{The number of fields in the status bar. It must be the
511 same used in \helpref{CreateStatusBar}{wxframecreatestatusbar}.}
512
513 \docparam{widths}{Must contain an array of {\it n} integers, each of which is a status field width
514 in pixels. A value of -1 indicates that the field is variable width; at least one
515 field must be -1. You should delete this array after calling {\bf SetStatusWidths}.}
516
517 \wxheading{Remarks}
518
519 The widths of the variable fields are calculated from the total width of all fields,
520 minus the sum of widths of the non-variable fields, divided by the number of
521 variable fields.
522
523 \membersection{wxFrame::SetToolBar}\label{wxframesettoolbar}
524
525 \func{void}{SetToolBar}{\param{wxToolBar*}{ toolBar}}
526
527 Associates a toolbar with the frame.
528
529 \wxheading{See also}
530
531 \helpref{wxFrame::CreateToolBar}{wxframecreatetoolbar}, \helpref{wxToolBar}{wxtoolbar},\rtfsp
532 \helpref{wxFrame::GetToolBar}{wxframegettoolbar}
533
534 \membersection{wxFrame::SetTitle}\label{wxframesettitle}
535
536 \func{virtual void}{SetTitle}{\param{const wxString\& }{ title}}
537
538 Sets the frame title.
539
540 \wxheading{Parameters}
541
542 \docparam{title}{The frame title.}
543
544 \wxheading{See also}
545
546 \helpref{wxFrame::GetTitle}{wxframegettitle}
547