1 \section{\class{wxFrame
}}\label{wxframe
}
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.
7 \wxheading{Derived from
}
9 \helpref{wxWindow
}{wxwindow
}\\
10 \helpref{wxEvtHandler
}{wxevthandler
}\\
11 \helpref{wxObject
}{wxobject
}
13 \wxheading{Window styles
}
16 \begin{twocollist
}\itemsep=
0pt
17 \twocolitem{\windowstyle{wxICONIZE
}}{Display the frame iconized (minimized) (Windows only).
}
18 \twocolitem{\windowstyle{wxCAPTION
}}{Puts a caption on the frame.
}
19 \twocolitem{\windowstyle{wxDEFAULT
\_FRAME\_STYLE}}{Defined as
{\bf wxMINIMIZE
\_BOX \pipe wxMAXIMIZE
\_BOX \pipe wxTHICK
\_FRAME \pipe wxSYSTEM
\_MENU \pipe wxCAPTION
}.
}
20 \twocolitem{\windowstyle{wxMINIMIZE
}}{Identical to
{\bf wxICONIZE
}.
}
21 \twocolitem{\windowstyle{wxMINIMIZE
\_BOX}}{Displays a minimize box on the frame (Windows and Motif only).
}
22 \twocolitem{\windowstyle{wxMAXIMIZE
}}{Displays the frame maximized (Windows only).
}
23 \twocolitem{\windowstyle{wxMAXIMIZE
\_BOX}}{Displays a maximize box on the frame (Windows and Motif only).
}
24 \twocolitem{\windowstyle{wxSTAY
\_ON\_TOP}}{Stay on top of other windows (Windows only).
}
25 \twocolitem{\windowstyle{wxSYSTEM
\_MENU}}{Displays a system menu (Windows and Motif only).
}
26 \twocolitem{\windowstyle{wxTHICK
\_FRAME}}{Displays a thick frame around the window (Windows and Motif only).
}
27 \twocolitem{\windowstyle{wxRESIZE
\_BORDER}}{Displays a resizeable border around the window (Motif only).
}
30 See also
\helpref{window styles overview
}{windowstyles
}.
34 An application should normally define an
\helpref{OnCloseWindow
}{wxwindowonclosewindow
} handler for the
35 frame to respond to system close events, for example so that related data and subwindows can be cleaned up.
39 \helpref{wxMDIParentFrame
}{wxmdiparentframe
},
\helpref{wxMDIChildFrame
}{wxmdichildframe
},
\rtfsp
40 \helpref{wxMiniFrame
}{wxminiframe
},
\helpref{wxDialog
}{wxdialog
}
42 \latexignore{\rtfignore{\wxheading{Members
}}}
44 \membersection{wxFrame::wxFrame
}\label{wxframeconstr
}
46 \func{}{wxFrame
}{\void}
50 \func{}{wxFrame
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
51 \param{const wxString\&
}{title
},
\param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\rtfsp
52 \param{const wxSize\&
}{ size = wxDefaultSize
},
\param{long
}{ style = wxDEFAULT
\_FRAME\_STYLE},
\rtfsp
53 \param{const wxString\&
}{name = ``frame"
}}
55 Constructor, creating the window.
57 \wxheading{Parameters
}
59 \docparam{parent
}{The window parent. This may be NULL. If it is non-NULL, the frame will
60 always be displayed on top of the parent window on Windows.
}
62 \docparam{id
}{The window identifier. It may take a value of -
1 to indicate a default value.
}
64 \docparam{title
}{The caption to be displayed on the frame's title bar.
}
66 \docparam{pos
}{The window position. A value of (-
1, -
1) indicates a default position, chosen by
67 either the windowing system or wxWindows, depending on platform.
}
69 \docparam{size
}{The window size. A value of (-
1, -
1) indicates a default size, chosen by
70 either the windowing system or wxWindows, depending on platform.
}
72 \docparam{style
}{The window style. See
\helpref{wxFrame
}{wxframe
}.
}
74 \docparam{name
}{The name of the window. This parameter is used to associate a name with the item,
75 allowing the application user to set Motif resource values for
80 For Motif, MWM (the Motif Window Manager) should be running for any window styles to work
81 (otherwise all styles take effect).
85 \helpref{wxFrame::Create
}{wxframecreate
}
87 \membersection{wxFrame::
\destruct{wxFrame
}}
89 \func{void
}{\destruct{wxFrame
}}{\void}
91 Destructor. Destroys all child windows and menu bar if present.
93 \membersection{wxFrame::Centre
}\label{wxframecentre
}
95 \func{void
}{Centre
}{\param{int
}{ direction = wxBOTH
}}
97 Centres the frame on the display.
99 \wxheading{Parameters
}
101 \docparam{direction
}{The parameter may be
{\tt wxHORIZONTAL
},
{\tt wxVERTICAL
} or
{\tt wxBOTH
}.
}
103 \membersection{wxFrame::Command
}\label{wxframecommand
}
105 \func{void
}{Command
}{\param{int
}{id
}}
107 Simulate a menu command.
109 \wxheading{Parameters
}
111 \docparam{id
}{The identifier for a menu item.
}
113 \membersection{wxFrame::Create
}\label{wxframecreate
}
115 \func{bool
}{Create
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
116 \param{const wxString\&
}{title
},
\param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\rtfsp
117 \param{const wxSize\&
}{ size = wxDefaultSize
},
\param{long
}{ style = wxDEFAULT
\_FRAME\_STYLE},
\rtfsp
118 \param{const wxString\&
}{name = ``frame"
}}
120 Used in two-step frame construction. See
\helpref{wxFrame::wxFrame
}{wxframeconstr
}\rtfsp
123 \membersection{wxFrame::CreateStatusBar
}\label{wxframecreatestatusbar
}
125 \func{virtual bool
}{CreateStatusBar
}{\param{int
}{ number =
1}}
127 Creates a status bar at the bottom of the frame.
129 \wxheading{Parameters
}
131 \docparam{number
}{The number of fields to create. Specify a
132 value greater than
1 to create a multi-field status bar.
}
134 \wxheading{Return value
}
136 TRUE if the status bar was created successfully.
140 The width of the status bar is the whole width of the frame (adjusted automatically when
141 resizing), and the height and text size are chosen by the host windowing system.
143 By default, the status bar is an instance of wxStatusBar. To use a different class,
144 override
\helpref{wxFrame::OnCreateStatusBar
}{wxframeoncreatestatusbar
}.
146 Note that you can put controls and other windows on the status bar if you wish.
150 \helpref{wxFrame::SetStatusText
}{wxframesetstatustext
},
\rtfsp
151 \helpref{wxFrame::OnCreateStatusBar
}{wxframeoncreatestatusbar
},
\rtfsp
152 \helpref{wxFrame::GetStatusBar
}{wxframegetstatusbar
}
154 \membersection{wxFrame::GetMenuBar
}\label{wxframegetmenubar
}
156 \constfunc{wxMenuBar*
}{GetMenuBar
}{\void}
158 Returns a pointer to the menubar currently associated with the frame (if any).
162 \helpref{wxFrame::SetMenuBar
}{wxframesetmenubar
},
\helpref{wxMenuBar
}{wxmenubar
},
\helpref{wxMenu
}{wxmenu
}
164 \membersection{wxFrame::GetStatusBar
}\label{wxframegetstatusbar
}
166 \func{wxStatusBar*
}{GetStatusBar
}{\void}
168 Returns a pointer to the status bar currently associated with the frame (if any).
172 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}
174 \membersection{wxFrame::GetTitle
}\label{wxframegettitle
}
176 \func{wxString\&
}{GetTitle
}{\void}
178 Gets a temporary pointer to the frame title. See
179 \helpref{wxFrame::SetTitle
}{wxframesettitle
}.
181 \membersection{wxFrame::Iconize
}\label{wxframeiconize
}
183 \func{void
}{Iconize
}{\param{const bool
}{ iconize
}}
185 Iconizes or restores the frame.
187 \wxheading{Parameters
}
189 \docparam{izonize
}{If TRUE, iconizes the frame; if FALSE, shows and restores it.
}
193 \helpref{wxFrame::IsIconized
}{wxframeisiconized
},
\helpref{wxFrame::Maximize
}{wxframemaximize
}.
195 \membersection{wxFrame::IsIconized
}\label{wxframeisiconized
}
197 \func{bool
}{IsIconized
}{\void}
199 Returns TRUE if the frame is iconized.
201 \membersection{wxFrame::LoadAccelerators
}\label{wxframeloadaccelerators
}
203 \func{void
}{LoadAccelerators
}{\param{const wxString\&
}{table
}}
205 Loads a keyboard accelerator table for this frame.
207 \wxheading{Parameters
}
209 \docparam{table
}{Accelerator table to load.
}
211 \wxheading{Return value
}
213 TRUE if the operation was successful, FALSE otherwise.
217 Accelerator tables map keystrokes onto control and menu identifiers, so the
218 programmer does not have to explicitly program this correspondence.
220 See the hello demo (
{\tt hello.cpp
} and
{\tt hello.rc
}) for
221 an example of accelerator usage. This is a fragment from
{\tt hello.rc
}:
224 #define HELLO_LOAD_FILE
111
226 menus_accel ACCELERATORS
229 "^L", HELLO_LOAD_FILE
234 This function only works under Windows.
236 % huh? If you call LoadAccelerators, you need to override wxFrame::OnActivate to do nothing.
238 \membersection{wxFrame::Maximize
}\label{wxframemaximize
}
240 \func{void
}{Maximize
}{\param{const bool
}{maximize
}}
242 Maximizes or restores the frame.
244 \wxheading{Parameters
}
246 \docparam{maximize
}{If TRUE, maximizes the frame, otherwise it restores it
}.
250 This function only works under Windows.
254 \helpref{wxFrame::Iconize
}{wxframeiconize
}
256 \membersection{wxFrame::OnActivate
}
258 \func{void
}{OnActivate
}{\param{bool
}{ active
}}
260 Called when a window is activated or deactivated (MS Windows
261 only). If the window is being activated,
{\it active
} is TRUE, else it
264 If you call wxFrame::LoadAccelerators, you need to override this function e.g.
267 void OnActivate(bool)
{};
270 \membersection{wxFrame::OnCreateStatusBar
}\label{wxframeoncreatestatusbar
}
272 \func{virtual wxStatusBar*
}{OnCreateStatusBar
}{\param{int
}{number
}}
274 Virtual function called when a status bar is requested by
\helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
}.
276 \wxheading{Parameters
}
278 \docparam{number
}{The number of fields to create.
}
280 \wxheading{Return value
}
286 An application can override this function to return a different kind of status bar. The default
287 implementation returns an instance of
\helpref{wxStatusBar
}{wxstatusbar
}.
291 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}.
293 \membersection{wxFrame::OnMenuCommand
}\label{wxframeonmenucommand
}
295 \func{void
}{OnMenuCommand
}{\param{wxCommandEvent\&
}{ event
}}
297 See
\helpref{wxWindow::OnMenuCommand
}{wxwindowonmenucommand
}.
299 \membersection{wxFrame::OnMenuHighlight
}\label{wxframeonmenuhighlight
}
301 \func{void
}{OnMenuHighlight
}{\param{wxMenuEvent\&
}{ event
}}
303 See
\helpref{wxWindow::OnMenuHighlight
}{wxwindowonmenuhighlight
}.
305 \membersection{wxFrame::OnSize
}\label{wxframeonsize
}
307 \func{void
}{OnSize
}{\param{wxSizeEvent\&
}{event
}}
309 See
\helpref{wxWindow::OnSize
}{wxwindowonsize
}.
311 The default
{\bf wxFrame::OnSize
} implementation looks for a single subwindow,
312 and if one is found, resizes it to fit
313 inside the frame. Override this member if more complex behaviour
314 is required (for example, if there are several subwindows).
316 \membersection{wxFrame::SetIcon
}\label{wxframeseticon
}
318 \func{void
}{SetIcon
}{\param{const wxIcon\&
}{icon
}}
320 Sets the icon for this frame.
322 \wxheading{Parameters
}
324 \docparam{icon
}{The icon to associate with this frame.
}
328 The frame takes a `copy' of
{\it icon
}, but since it uses reference
329 counting, the copy is very quick. It is safe to delete
{\it icon
} after
330 calling this function.
332 Under Windows, instead of using
{\bf SetIcon
}, you can add the
333 following lines to your MS Windows resource file:
336 wxSTD_MDIPARENTFRAME ICON icon1.ico
337 wxSTD_MDICHILDFRAME ICON icon2.ico
338 wxSTD_FRAME ICON icon3.ico
341 where icon1.ico will be used for the MDI parent frame, icon2.ico
342 will be used for MDI child frames, and icon3.ico will be used for
345 If these icons are not supplied, and
{\bf SetIcon
} is not called either,
346 then the following defaults apply if you have included wx.rc.
349 wxDEFAULT_FRAME ICON std.ico
350 wxDEFAULT_MDIPARENTFRAME ICON mdi.ico
351 wxDEFAULT_MDICHILDFRAME ICON child.ico
354 You can replace std.ico, mdi.ico and child.ico with your own defaults
355 for all your wxWindows application. Currently they show the same icon.
357 {\it Note:
} a wxWindows application linked with subsystem equal to
4.0
358 (i.e. marked as a Windows
95 application) doesn't respond properly
359 to wxFrame::SetIcon. To work around this until a solution is found,
360 mark your program as a
3.5 application. This will also ensure
361 that Windows provides small icons for the application automatically.
363 See also
\helpref{wxIcon
}{wxicon
}.
365 \membersection{wxFrame::SetMenuBar
}\label{wxframesetmenubar
}
367 \func{void
}{SetMenuBar
}{\param{wxMenuBar*
}{menuBar
}}
369 Tells the frame to show the given menu bar.
371 \wxheading{Parameters
}
373 \docparam{menuBar
}{The menu bar to associate with the frame.
}
377 If the frame is destroyed, the
378 menu bar and its menus will be destroyed also, so do not delete the menu
379 bar explicitly (except by resetting the frame's menu bar to another
382 Under Windows, a call to
\helpref{wxFrame::OnSize
}{wxframeonsize
} is generated, so be sure to initialize
383 data members properly before calling
{\bf SetMenuBar
}.
385 Note that it is not possible to call this function twice for the same frame object.
389 \helpref{wxFrame::GetMenuBar
}{wxframegetmenubar
},
\helpref{wxMenuBar
}{wxmenubar
},
\helpref{wxMenu
}{wxmenu
}.
391 \membersection{wxFrame::SetStatusText
}\label{wxframesetstatustext
}
393 \func{virtual void
}{SetStatusText
}{\param{const wxString\&
}{ text
},
\param{int
}{ number =
0}}
395 Sets the status bar text and redraws the status bar.
397 \wxheading{Parameters
}
399 \docparam{text
}{The text for the status field.
}
401 \docparam{number
}{The status field (starting from zero).
}
405 Use an empty string to clear the status bar.
409 \helpref{wxFrame::CreateStatusBar
}{wxframecreatestatusbar
},
\helpref{wxStatusBar
}{wxstatusbar
}
411 \membersection{wxFrame::SetStatusWidths
}\label{wxframesetstatuswidths
}
413 \func{virtual void
}{SetStatusWidths
}{\param{int
}{ n
},
\param{int *
}{widths
}}
415 Sets the widths of the fields in the status bar.
417 \wxheading{Parameters
}
419 \wxheading{n
}{The number of fields in the status bar. It must be the
420 same used in
\helpref{CreateStatusBar
}{wxframecreatestatusbar
}.
}
422 \docparam{widths
}{Must contain an array of
{\it n
} integers, each of which is a status field width
423 in pixels. A value of -
1 indicates that the field is variable width; at least one
424 field must be -
1. You should delete this array after calling
{\bf SetStatusWidths
}.
}
428 The widths of the variable fields are calculated from the total width of all fields,
429 minus the sum of widths of the non-variable fields, divided by the number of
432 \membersection{wxFrame::SetTitle
}\label{wxframesettitle
}
434 \func{virtual void
}{SetTitle
}{\param{const wxString\&
}{ title
}}
436 Sets the frame title.
438 \wxheading{Parameters
}
440 \docparam{title
}{The frame title.
}
444 \helpref{wxFrame::GetTitle
}{wxframegettitle
}