1 \section{\class{wxFrame
}}\label{wxframe
}
3 A frame is a window whose size and position can (usually) be changed by the
4 user. It usually has thick borders and a title bar, and can optionally contain
5 a menu bar, toolbar and status bar. A frame can contain any window that is not
8 A frame that has a status bar and toolbar created via the
9 CreateStatusBar/CreateToolBar functions manages these windows, and adjusts the
10 value returned by GetClientSize to reflect the remaining size available to
13 \wxheading{Derived from
}
15 \helpref{wxWindow
}{wxwindow
}\\
16 \helpref{wxEvtHandler
}{wxevthandler
}\\
17 \helpref{wxObject
}{wxobject
}
19 \wxheading{Include files
}
23 \wxheading{Window styles
}
26 \begin{twocollist
}\itemsep=
0pt
27 \twocolitem{\windowstyle{wxICONIZE
}}{Display the frame iconized (minimized). Windows only.
}
28 \twocolitem{\windowstyle{wxCAPTION
}}{Puts a caption on the frame.
}
29 \twocolitem{\windowstyle{wxDEFAULT
\_FRAME\_STYLE}}{Defined as
{\bf wxMINIMIZE
\_BOX \pipe wxMAXIMIZE
\_BOX \pipe wxTHICK
\_FRAME \pipe wxSYSTEM
\_MENU \pipe wxCAPTION
}.
}
30 \twocolitem{\windowstyle{wxMINIMIZE
}}{Identical to
{\bf wxICONIZE
}. Windows only.
}
31 \twocolitem{\windowstyle{wxMINIMIZE
\_BOX}}{Displays a minimize box on the frame.
}
32 \twocolitem{\windowstyle{wxMAXIMIZE
}}{Displays the frame maximized. Windows only.
}
33 \twocolitem{\windowstyle{wxMAXIMIZE
\_BOX}}{Displays a maximize box on the frame.
}
34 \twocolitem{\windowstyle{wxSTAY
\_ON\_TOP}}{Stay on top of other windows. Windows only.
}
35 \twocolitem{\windowstyle{wxSYSTEM
\_MENU}}{Displays a system menu.
}
36 \twocolitem{\windowstyle{wxTHICK
\_FRAME}}{Displays a thick frame around the window. Windows and Motif only.
}
37 \twocolitem{\windowstyle{wxSIMPLE
\_BORDER}}{Displays no border or decorations. GTK and Windows only (?).
}
38 \twocolitem{\windowstyle{wxRESIZE
\_BORDER}}{Displays a resizeable border around the window (Unix only).
}
39 \twocolitem{\windowstyle{wxFRAME
\_FLOAT\_ON\_PARENT}}{Causes the frame to be above the parent window in the
40 z-order and not shown in the taskbar. Without this style, frames are created as top-level windows that may be obscured by
41 the parent window, and frame titles are shown in the taskbar. Windows only.
}
42 \twocolitem{\windowstyle{wxFRAME
\_TOOL\_WINDOW}}{Causes a frame with a small titlebar to be created;
43 the frame title does not appear in the taskbar. Windows only.
}
46 See also
\helpref{window styles overview
}{windowstyles
}.
50 An application should normally define an
\helpref{OnCloseWindow
}{wxwindowonclosewindow
} handler for the
51 frame to respond to system close events, for example so that related data and subwindows can be cleaned up.
55 \helpref{wxMDIParentFrame
}{wxmdiparentframe
},
\helpref{wxMDIChildFrame
}{wxmdichildframe
},
\rtfsp
56 \helpref{wxMiniFrame
}{wxminiframe
},
\helpref{wxDialog
}{wxdialog
}
58 \latexignore{\rtfignore{\wxheading{Members
}}}
60 \membersection{wxFrame::wxFrame
}\label{wxframeconstr
}
62 \func{}{wxFrame
}{\void}
66 \func{}{wxFrame
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
67 \param{const wxString\&
}{title
},
\param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\rtfsp
68 \param{const wxSize\&
}{ size = wxDefaultSize
},
\param{long
}{ style = wxDEFAULT
\_FRAME\_STYLE},
\rtfsp
69 \param{const wxString\&
}{name = ``frame"
}}
71 Constructor, creating the window.
73 \wxheading{Parameters
}
75 \docparam{parent
}{The window parent. This may be NULL. If it is non-NULL, the frame will
76 always be displayed on top of the parent window on Windows.
}
78 \docparam{id
}{The window identifier. It may take a value of -
1 to indicate a default value.
}
80 \docparam{title
}{The caption to be displayed on the frame's title bar.
}
82 \docparam{pos
}{The window position. A value of (-
1, -
1) indicates a default position, chosen by
83 either the windowing system or wxWindows, depending on platform.
}
85 \docparam{size
}{The window size. A value of (-
1, -
1) indicates a default size, chosen by
86 either the windowing system or wxWindows, depending on platform.
}
88 \docparam{style
}{The window style. See
\helpref{wxFrame
}{wxframe
}.
}
90 \docparam{name
}{The name of the window. This parameter is used to associate a name with the item,
91 allowing the application user to set Motif resource values for
96 For Motif, MWM (the Motif Window Manager) should be running for any window styles to work
97 (otherwise all styles take effect).
101 \helpref{wxFrame::Create
}{wxframecreate
}
103 \membersection{wxFrame::
\destruct{wxFrame
}}
105 \func{void
}{\destruct{wxFrame
}}{\void}
107 Destructor. Destroys all child windows and menu bar if present.
109 \membersection{wxFrame::Centre
}\label{wxframecentre
}
111 \func{void
}{Centre
}{\param{int
}{ direction = wxBOTH
}}
113 Centres the frame on the display.
115 \wxheading{Parameters
}
117 \docparam{direction
}{The parameter may be
{\tt wxHORIZONTAL
},
{\tt wxVERTICAL
} or
{\tt wxBOTH
}.
}
119 \membersection{wxFrame::Command
}\label{wxframecommand
}
121 \func{void
}{Command
}{\param{int
}{id
}}
123 Simulate a menu command.
125 \wxheading{Parameters
}
127 \docparam{id
}{The identifier for a menu item.
}
129 \membersection{wxFrame::Create
}\label{wxframecreate
}
131 \func{bool
}{Create
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
132 \param{const wxString\&
}{title
},
\param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\rtfsp
133 \param{const wxSize\&
}{ size = wxDefaultSize
},
\param{long
}{ style = wxDEFAULT
\_FRAME\_STYLE},
\rtfsp
134 \param{const wxString\&
}{name = ``frame"
}}
136 Used in two-step frame construction. See
\helpref{wxFrame::wxFrame
}{wxframeconstr
}\rtfsp
139 \membersection{wxFrame::CreateStatusBar
}\label{wxframecreatestatusbar
}
141 \func{virtual wxStatusBar*
}{CreateStatusBar
}{\param{int
}{ number =
1},
142 \param{long
}{ style =
0},
143 \param{wxWindowID
}{ id = -
1},
\param{const wxString\&
}{ name = "statusBar"
}}
145 Creates a status bar at the bottom of the frame.
147 \wxheading{Parameters
}
149 \docparam{number
}{The number of fields to create. Specify a
150 value greater than
1 to create a multi-field status bar.
}
152 \docparam{style
}{The status bar style. See
\helpref{wxStatusBar
}{wxstatusbar
} for a list
155 \docparam{id
}{The status bar window identifier. If -
1, an identifier will be chosen by
158 \docparam{name
}{The status bar window name.
}
160 \wxheading{Return value
}
162 A pointer to the the status bar if it was created successfully, NULL otherwise.
166 The width of the status bar is the whole width of the frame (adjusted automatically when
167 resizing), and the height and text size are chosen by the host windowing system.
169 By default, the status bar is an instance of wxStatusBar. To use a different class,
170 override
\helpref{wxFrame::OnCreateStatusBar
}{wxframeoncreatestatusbar
}.
172 Note that you can put controls and other windows on the status bar if you wish.
176 \helpref{wxFrame::SetStatusText
}{wxframesetstatustext
},
\rtfsp
177 \helpref{wxFrame::OnCreateStatusBar
}{wxframeoncreatestatusbar
},
\rtfsp
178 \helpref{wxFrame::GetStatusBar
}{wxframegetstatusbar
}
180 \membersection{wxFrame::CreateToolBar
}\label{wxframecreatetoolbar
}
182 \func{virtual wxToolBar*
}{CreateToolBar
}{\param{long
}{ style = wxNO
\_BORDER \pipe wxTB
\_HORIZONTAL},
183 \param{wxWindowID
}{ id = -
1},
\param{const wxString\&
}{ name = "toolBar"
}}
185 Creates a toolbar at the top or left of the frame.
187 \wxheading{Parameters
}
189 \docparam{style
}{The toolbar style. See
\helpref{wxToolBar
}{wxtoolbar
} for a list
192 \docparam{id
}{The toolbar window identifier. If -
1, an identifier will be chosen by
195 \docparam{name
}{The toolbar window name.
}
197 \wxheading{Return value
}
199 A pointer to the the toolbar if it was created successfully, NULL otherwise.
203 By default, the toolbar is an instance of wxToolBar (which is defined to be
204 a suitable toolbar class on each platform, such as wxToolBar95). To use a different class,
205 override
\helpref{wxFrame::OnCreateToolBar
}{wxframeoncreatetoolbar
}.
207 When a toolbar has been created with this function, or made known to the frame
208 with
\helpref{wxFrame::SetToolBar
}{wxframesettoolbar
}, the frame will manage the toolbar
209 position and adjust the return value from
\helpref{wxWindow::GetClientSize
}{wxwindowgetclientsize
} to
210 reflect the available space for application windows.
214 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\rtfsp
215 \helpref{wxFrame::OnCreateToolBar
}{wxframeoncreatetoolbar
},
\rtfsp
216 \helpref{wxFrame::SetToolBar
}{wxframesettoolbar
},
\rtfsp
217 \helpref{wxFrame::GetToolBar
}{wxframegettoolbar
}
219 \membersection{wxFrame::GetClientAreaOrigin
}\label{wxframegetclientareaorigin
}
221 \constfunc{wxPoint
}{GetClientAreaOrigin
}{\void}
223 Returns the origin of the frame client area (in client coordinates). It may be
224 different from (
0,
0) if the frame has a toolbar.
226 \membersection{wxFrame::GetMenuBar
}\label{wxframegetmenubar
}
228 \constfunc{wxMenuBar*
}{GetMenuBar
}{\void}
230 Returns a pointer to the menubar currently associated with the frame (if any).
234 \helpref{wxFrame::SetMenuBar
}{wxframesetmenubar
},
\helpref{wxMenuBar
}{wxmenubar
},
\helpref{wxMenu
}{wxmenu
}
236 \membersection{wxFrame::GetStatusBar
}\label{wxframegetstatusbar
}
238 \constfunc{wxStatusBar*
}{GetStatusBar
}{\void}
240 Returns a pointer to the status bar currently associated with the frame (if any).
244 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}
246 \membersection{wxFrame::GetTitle
}\label{wxframegettitle
}
248 \constfunc{wxString
}{GetTitle
}{\void}
250 Gets a string containing the frame title. See
\helpref{wxFrame::SetTitle
}{wxframesettitle
}.
252 \membersection{wxFrame::GetToolBar
}\label{wxframegettoolbar
}
254 \constfunc{wxToolBar*
}{GetToolBar
}{\void}
256 Returns a pointer to the toolbar currently associated with the frame (if any).
260 \helpref{wxFrame::CreateToolBar
}{wxframecreatetoolbar
},
\helpref{wxToolBar
}{wxtoolbar
},
\rtfsp
261 \helpref{wxFrame::SetToolBar
}{wxframesettoolbar
}
263 \membersection{wxFrame::Iconize
}\label{wxframeiconize
}
265 \func{void
}{Iconize
}{\param{bool
}{ iconize
}}
267 Iconizes or restores the frame. Windows only.
269 \wxheading{Parameters
}
271 \docparam{izonize
}{If TRUE, iconizes the frame; if FALSE, shows and restores it.
}
275 \helpref{wxFrame::IsIconized
}{wxframeisiconized
},
\helpref{wxFrame::Maximize
}{wxframemaximize
}.
277 \membersection{wxFrame::IsIconized
}\label{wxframeisiconized
}
279 \constfunc{bool
}{IsIconized
}{\void}
281 Returns TRUE if the frame is iconized. Windows only.
283 \membersection{wxFrame::IsMaximized
}\label{wxframeismaximized
}
285 \constfunc{bool
}{IsMaximized
}{\void}
287 Returns TRUE if the frame is maximized.
289 \membersection{wxFrame::Maximize
}\label{wxframemaximize
}
291 \func{void
}{Maximize
}{\param{bool
}{maximize
}}
293 Maximizes or restores the frame.
295 \wxheading{Parameters
}
297 \docparam{maximize
}{If TRUE, maximizes the frame, otherwise it restores it.
}
301 This function only works under Windows.
305 \helpref{wxFrame::Iconize
}{wxframeiconize
}
307 \membersection{wxFrame::OnActivate
}
309 \func{void
}{OnActivate
}{\param{wxActivateEvent\&
}{ event
}}
311 Called when a window is activated or deactivated (MS Windows
312 only). See also
\helpref{wxActivateEvent
}{wxactivateevent
}.
314 \membersection{wxFrame::OnCreateStatusBar
}\label{wxframeoncreatestatusbar
}
316 \func{virtual wxStatusBar*
}{OnCreateStatusBar
}{\param{int
}{number
},
317 \param{long
}{ style
},
318 \param{wxWindowID
}{ id
},
\param{const wxString\&
}{ name
}}
320 Virtual function called when a status bar is requested by
\helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
}.
322 \wxheading{Parameters
}
324 \docparam{number
}{The number of fields to create.
}
326 \docparam{style
}{The window style. See
\helpref{wxStatusBar
}{wxstatusbar
} for a list
329 \docparam{id
}{The window identifier. If -
1, an identifier will be chosen by
332 \docparam{name
}{The window name.
}
334 \wxheading{Return value
}
340 An application can override this function to return a different kind of status bar. The default
341 implementation returns an instance of
\helpref{wxStatusBar
}{wxstatusbar
}.
345 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}.
347 \membersection{wxFrame::OnCreateToolBar
}\label{wxframeoncreatetoolbar
}
349 \func{virtual wxToolBar*
}{OnCreateToolBar
}{\param{long
}{ style
},
350 \param{wxWindowID
}{ id
},
\param{const wxString\&
}{ name
}}
352 Virtual function called when a toolbar is requested by
\helpref{wxFrame::CreateToolBar
}{wxframecreatetoolbar
}.
354 \wxheading{Parameters
}
356 \docparam{style
}{The toolbar style. See
\helpref{wxToolBar
}{wxtoolbar
} for a list
359 \docparam{id
}{The toolbar window identifier. If -
1, an identifier will be chosen by
362 \docparam{name
}{The toolbar window name.
}
364 \wxheading{Return value
}
370 An application can override this function to return a different kind of toolbar. The default
371 implementation returns an instance of
\helpref{wxToolBar
}{wxtoolbar
}.
375 \helpref{wxFrame::CreateToolBar
}{wxframecreatetoolbar
},
\helpref{wxToolBar
}{wxtoolbar
}.
377 \membersection{wxFrame::OnMenuCommand
}\label{wxframeonmenucommand
}
379 \func{void
}{OnMenuCommand
}{\param{wxCommandEvent\&
}{ event
}}
381 See
\helpref{wxWindow::OnMenuCommand
}{wxwindowonmenucommand
}.
383 \membersection{wxFrame::OnMenuHighlight
}\label{wxframeonmenuhighlight
}
385 \func{void
}{OnMenuHighlight
}{\param{wxMenuEvent\&
}{ event
}}
387 See
\helpref{wxWindow::OnMenuHighlight
}{wxwindowonmenuhighlight
}.
389 \membersection{wxFrame::OnSize
}\label{wxframeonsize
}
391 \func{void
}{OnSize
}{\param{wxSizeEvent\&
}{event
}}
393 See
\helpref{wxWindow::OnSize
}{wxwindowonsize
}.
395 The default
{\bf wxFrame::OnSize
} implementation looks for a single subwindow,
396 and if one is found, resizes it to fit
397 inside the frame. Override this member if more complex behaviour
398 is required (for example, if there are several subwindows).
400 \membersection{wxFrame::SetIcon
}\label{wxframeseticon
}
402 \func{void
}{SetIcon
}{\param{const wxIcon\&
}{icon
}}
404 Sets the icon for this frame.
406 \wxheading{Parameters
}
408 \docparam{icon
}{The icon to associate with this frame.
}
412 The frame takes a `copy' of
{\it icon
}, but since it uses reference
413 counting, the copy is very quick. It is safe to delete
{\it icon
} after
414 calling this function.
416 Under Windows, instead of using
{\bf SetIcon
}, you can add the
417 following lines to your MS Windows resource file:
420 wxSTD_MDIPARENTFRAME ICON icon1.ico
421 wxSTD_MDICHILDFRAME ICON icon2.ico
422 wxSTD_FRAME ICON icon3.ico
425 where icon1.ico will be used for the MDI parent frame, icon2.ico
426 will be used for MDI child frames, and icon3.ico will be used for
429 If these icons are not supplied, and
{\bf SetIcon
} is not called either,
430 then the following defaults apply if you have included wx.rc.
433 wxDEFAULT_FRAME ICON std.ico
434 wxDEFAULT_MDIPARENTFRAME ICON mdi.ico
435 wxDEFAULT_MDICHILDFRAME ICON child.ico
438 You can replace std.ico, mdi.ico and child.ico with your own defaults
439 for all your wxWindows application. Currently they show the same icon.
441 {\it Note:
} a wxWindows application linked with subsystem equal to
4.0
442 (i.e. marked as a Windows
95 application) doesn't respond properly
443 to wxFrame::SetIcon. To work around this until a solution is found,
444 mark your program as a
3.5 application. This will also ensure
445 that Windows provides small icons for the application automatically.
447 See also
\helpref{wxIcon
}{wxicon
}.
449 \membersection{wxFrame::SetMenuBar
}\label{wxframesetmenubar
}
451 \func{void
}{SetMenuBar
}{\param{wxMenuBar*
}{menuBar
}}
453 Tells the frame to show the given menu bar.
455 \wxheading{Parameters
}
457 \docparam{menuBar
}{The menu bar to associate with the frame.
}
461 If the frame is destroyed, the
462 menu bar and its menus will be destroyed also, so do not delete the menu
463 bar explicitly (except by resetting the frame's menu bar to another
466 Under Windows, a call to
\helpref{wxFrame::OnSize
}{wxframeonsize
} is generated, so be sure to initialize
467 data members properly before calling
{\bf SetMenuBar
}.
469 Note that it is not possible to call this function twice for the same frame object.
473 \helpref{wxFrame::GetMenuBar
}{wxframegetmenubar
},
\helpref{wxMenuBar
}{wxmenubar
},
\helpref{wxMenu
}{wxmenu
}.
475 \membersection{wxFrame::SetStatusBar
}\label{wxframesetstatusbar
}
477 \func{void
}{SetStatusBar
}{\param{wxStatusBar*
}{ statusBar
}}
479 Associates a status bar with the frame.
483 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
},
\rtfsp
484 \helpref{wxFrame::GetStatusBar
}{wxframegetstatusbar
}
486 \membersection{wxFrame::SetStatusText
}\label{wxframesetstatustext
}
488 \func{virtual void
}{SetStatusText
}{\param{const wxString\&
}{ text
},
\param{int
}{ number =
0}}
490 Sets the status bar text and redraws the status bar.
492 \wxheading{Parameters
}
494 \docparam{text
}{The text for the status field.
}
496 \docparam{number
}{The status field (starting from zero).
}
500 Use an empty string to clear the status bar.
504 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}
506 \membersection{wxFrame::SetStatusWidths
}\label{wxframesetstatuswidths
}
508 \func{virtual void
}{SetStatusWidths
}{\param{int
}{ n
},
\param{int *
}{widths
}}
510 Sets the widths of the fields in the status bar.
512 \wxheading{Parameters
}
514 \wxheading{n
}{The number of fields in the status bar. It must be the
515 same used in
\helpref{CreateStatusBar
}{wxframecreatestatusbar
}.
}
517 \docparam{widths
}{Must contain an array of
{\it n
} integers, each of which is a status field width
518 in pixels. A value of -
1 indicates that the field is variable width; at least one
519 field must be -
1. You should delete this array after calling
{\bf SetStatusWidths
}.
}
523 The widths of the variable fields are calculated from the total width of all fields,
524 minus the sum of widths of the non-variable fields, divided by the number of
527 \pythonnote{Only a single parameter is required, a Python list of
530 \membersection{wxFrame::SetToolBar
}\label{wxframesettoolbar
}
532 \func{void
}{SetToolBar
}{\param{wxToolBar*
}{ toolBar
}}
534 Associates a toolbar with the frame.
538 \helpref{wxFrame::CreateToolBar
}{wxframecreatetoolbar
},
\helpref{wxToolBar
}{wxtoolbar
},
\rtfsp
539 \helpref{wxFrame::GetToolBar
}{wxframegettoolbar
}
541 \membersection{wxFrame::SetTitle
}\label{wxframesettitle
}
543 \func{virtual void
}{SetTitle
}{\param{const wxString\&
}{ title
}}
545 Sets the frame title.
547 \wxheading{Parameters
}
549 \docparam{title
}{The frame title.
}
553 \helpref{wxFrame::GetTitle
}{wxframegettitle
}
555 \membersection{wxFrame::ShowFullScreen
}\label{wxframeshowfullscreen
}
557 \func{bool
}{ShowFullScreen
}{\param{bool
}{ show
},
\param{long
}{ style = wxFULLSCREEN
\_ALL}}
559 Passing TRUE to
{\it shows
} shows the frame full-screen, and passing FALSE restores the frame
560 again.
{\it style
} is a bit list containing some or all of the following values, which
561 indicate what elements of the frame to hide in full-screen mode:
563 \begin{itemize
}\itemsep=
0pt
564 \item wxFULLSCREEN
\_NOMENUBAR
565 \item wxFULLSCREEN
\_NOTOOLBAR
566 \item wxFULLSCREEN
\_NOSTATUSBAR
567 \item wxFULLSCREEN
\_NOBORDER
568 \item wxFULLSCREEN
\_NOCAPTION
569 \item wxFULLSCREEN
\_ALL (all of the above)
572 This function only works on Windows and has not been tested with MDI frames.