1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxFrame
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 A frame is a window whose size and position can (usually) be changed by the user.
14 It usually has thick borders and a title bar, and can optionally contain a
15 menu bar, toolbar and status bar. A frame can contain any window that is not
18 A frame that has a status bar and toolbar, created via the CreateStatusBar() and
19 CreateToolBar() functions, manages these windows and adjusts the value returned
20 by GetClientSize() to reflect the remaining size available to application windows.
22 @remarks An application should normally define an wxCloseEvent handler for the
23 frame to respond to system close events, for example so that related
24 data and subwindows can be cleaned up.
27 @section frame_defaultevent Default event processing
29 wxFrame processes the following events:
31 @li @c wxEVT_SIZE: if the frame has exactly one child window, not counting the
32 status and toolbar, this child is resized to take the entire frame client area.
33 If two or more windows are present, they should be laid out explicitly either
34 by manually handling @c wxEVT_SIZE or using sizers;
35 @li @c wxEVT_MENU_HIGHLIGHT: the default implementation displays the help string
36 associated with the selected item in the first pane of the status bar, if there is one.
40 @style{wxDEFAULT_FRAME_STYLE}
41 Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER |
42 wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN.
44 Display the frame iconized (minimized). Windows only.
46 Puts a caption on the frame.
48 Identical to wxICONIZE. Windows only.
49 @style{wxMINIMIZE_BOX}
50 Displays a minimize box on the frame.
52 Displays the frame maximized. Windows only.
53 @style{wxMAXIMIZE_BOX}
54 Displays a maximize box on the frame.
56 Displays a close box on the frame.
58 Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT.
60 Displays a system menu.
61 @style{wxRESIZE_BORDER}
62 Displays a resizeable border around the window.
63 @style{wxFRAME_TOOL_WINDOW}
64 Causes a frame with a small titlebar to be created; the frame does
65 not appear in the taskbar under Windows or GTK+.
66 @style{wxFRAME_NO_TASKBAR}
67 Creates an otherwise normal frame but it does not appear in the
68 taskbar under Windows or GTK+ (note that it will minimize to the
69 desktop window under Windows which may seem strange to the users
70 and thus it might be better to use this style only without
71 wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if GTK+
72 is at least version 2.2 and the window manager supports
73 _NET_WM_STATE_SKIP_TASKBAR hint. Has no effect under other platforms.
74 @style{wxFRAME_FLOAT_ON_PARENT}
75 The frame will always be on top of its parent (unlike wxSTAY_ON_TOP).
76 A frame created with this style must have a non-@NULL parent.
77 @style{wxFRAME_SHAPED}
78 Windows with this style are allowed to have their shape changed
79 with the SetShape() method.
82 The default frame style is for normal, resizeable frames.
83 To create a frame which can not be resized by user, you may use the following
84 combination of styles:
87 wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxMAXIMIZE_BOX)
90 See also the @ref overview_windowstyles.
93 @style{wxFRAME_EX_CONTEXTHELP}
94 Under Windows, puts a query button on the caption. When pressed,
95 Windows will go into a context-sensitive help mode and wxWidgets
96 will send a wxEVT_HELP event if the user clicked on an application
97 window. Note that this is an extended style and must be set by
98 calling SetExtraStyle before Create is called (two-step
99 construction). You cannot use this style together with
100 wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use
101 wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the
102 frames having this style (the dialogs don't have a minimize or a
103 maximize box by default)
104 @style{wxFRAME_EX_METAL}
105 On Mac OS X, frames with this style will be shown with a metallic
106 look. This is an extra style.
109 @beginEventEmissionTable
110 @event{EVT_CLOSE(func)}
111 The frame is being closed by the user or programmatically (see wxWindow::Close).
112 The user may generate this event clicking the close button
113 (typically the 'X' on the top-right of the title bar) if it's present
114 (see the @c wxCLOSE_BOX style). See wxCloseEvent.
115 @event{EVT_ICONIZE(func)}
116 Process a @c wxEVT_ICONIZE event. See wxIconizeEvent.
117 @event{EVT_MENU_OPEN(func)}
118 A menu is about to be opened. See wxMenuEvent.
119 @event{EVT_MENU_CLOSE(func)}
120 A menu has been just closed. See wxMenuEvent.
121 @event{EVT_MENU_HIGHLIGHT(id, func)}
122 The menu item with the specified id has been highlighted: used to show
123 help prompts in the status bar by wxFrame. See wxMenuEvent.
124 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
125 A menu item has been highlighted, i.e. the currently selected menu item has changed.
130 @category{managedwnd}
132 @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
134 class wxFrame
: public wxTopLevelWindow
143 Constructor, creating the window.
146 The window parent. This may be @NULL. If it is non-@NULL, the frame will
147 always be displayed on top of the parent window on Windows.
149 The window identifier. It may take a value of -1 to indicate a default value.
151 The caption to be displayed on the frame's title bar.
153 The window position. The value wxDefaultPosition indicates a default position,
154 chosen by either the windowing system or wxWidgets, depending on platform.
156 The window size. The value wxDefaultSize indicates a default size, chosen by
157 either the windowing system or wxWidgets, depending on platform.
159 The window style. See wxFrame class description.
161 The name of the window. This parameter is used to associate a name with
162 the item, allowing the application user to set Motif resource values for
165 @remarks For Motif, MWM (the Motif Window Manager) should be running for
166 any window styles to work (otherwise all styles take effect).
170 wxFrame(wxWindow
* parent
, wxWindowID id
,
171 const wxString
& title
,
172 const wxPoint
& pos
= wxDefaultPosition
,
173 const wxSize
& size
= wxDefaultSize
,
174 long style
= wxDEFAULT_FRAME_STYLE
,
175 const wxString
& name
= wxFrameNameStr
);
178 Destructor. Destroys all child windows and menu bar if present.
180 See @ref overview_windowdeletion for more info.
185 Centres the frame on the display.
188 The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
190 void Centre(int direction
= wxBOTH
);
193 Used in two-step frame construction.
194 See wxFrame() for further details.
196 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& title
,
197 const wxPoint
& pos
= wxDefaultPosition
,
198 const wxSize
& size
= wxDefaultSize
,
199 long style
= wxDEFAULT_FRAME_STYLE
,
200 const wxString
& name
= wxFrameNameStr
);
203 Creates a status bar at the bottom of the frame.
206 The number of fields to create. Specify a
207 value greater than 1 to create a multi-field status bar.
209 The status bar style. See wxStatusBar for a list of valid styles.
211 The status bar window identifier. If -1, an identifier will be chosen
214 The status bar window name.
216 @return A pointer to the status bar if it was created successfully, @NULL
219 @remarks The width of the status bar is the whole width of the frame
220 (adjusted automatically when resizing), and the height
221 and text size are chosen by the host windowing system.
223 @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
225 virtual wxStatusBar
* CreateStatusBar(int number
= 1, long style
= wxSTB_DEFAULT_STYLE
,
227 const wxString
& name
= wxStatusLineNameStr
);
230 Creates a toolbar at the top or left of the frame.
233 The toolbar style. See wxToolBar for a list of valid styles.
235 The toolbar window identifier. If -1, an identifier will be chosen
238 The toolbar window name.
240 @return A pointer to the toolbar if it was created successfully, @NULL
244 By default, the toolbar is an instance of wxToolBar.
245 To use a different class, override OnCreateToolBar().
246 When a toolbar has been created with this function, or made
247 known to the frame with wxFrame::SetToolBar(), the frame will
248 manage the toolbar position and adjust the return value from
249 wxWindow::GetClientSize() to reflect the available space for
251 Under Pocket PC, you should always use this function for creating
252 the toolbar to be managed by the frame, so that wxWidgets can
253 use a combined menubar and toolbar.
254 Where you manage your own toolbars, create a wxToolBar as usual.
256 @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
258 virtual wxToolBar
* CreateToolBar(long style
= wxBORDER_NONE
| wxTB_HORIZONTAL
,
259 wxWindowID id
= wxID_ANY
,
260 const wxString
& name
= wxToolBarNameStr
);
263 Returns the origin of the frame client area (in client coordinates).
264 It may be different from (0, 0) if the frame has a toolbar.
266 virtual wxPoint
GetClientAreaOrigin() const;
269 Returns a pointer to the menubar currently associated with the frame (if any).
271 @see SetMenuBar(), wxMenuBar, wxMenu
273 virtual wxMenuBar
* GetMenuBar() const;
276 Returns a pointer to the status bar currently associated with the frame
279 @see CreateStatusBar(), wxStatusBar
281 virtual wxStatusBar
* GetStatusBar() const;
284 Returns the status bar pane used to display menu and toolbar help.
286 @see SetStatusBarPane()
288 int GetStatusBarPane() const;
291 Returns a pointer to the toolbar currently associated with the frame (if any).
293 @see CreateToolBar(), wxToolBar, SetToolBar()
295 virtual wxToolBar
* GetToolBar() const;
298 Virtual function called when a status bar is requested by CreateStatusBar().
301 The number of fields to create.
303 The window style. See wxStatusBar for a list
306 The window identifier. If -1, an identifier will be chosen by
311 @return A status bar object.
313 @remarks An application can override this function to return a different
314 kind of status bar. The default implementation returns
315 an instance of wxStatusBar.
317 @see CreateStatusBar(), wxStatusBar.
319 virtual wxStatusBar
* OnCreateStatusBar(int number
, long style
,
321 const wxString
& name
);
324 Virtual function called when a toolbar is requested by CreateToolBar().
327 The toolbar style. See wxToolBar for a list
330 The toolbar window identifier. If -1, an identifier will be chosen by
333 The toolbar window name.
335 @return A toolbar object.
337 @remarks An application can override this function to return a different
338 kind of toolbar. The default implementation returns an
339 instance of wxToolBar.
341 @see CreateToolBar(), wxToolBar.
343 virtual wxToolBar
* OnCreateToolBar(long style
, wxWindowID id
,
344 const wxString
& name
);
347 Simulate a menu command.
350 The identifier for a menu item.
352 bool ProcessCommand(int id
);
355 Tells the frame to show the given menu bar.
358 The menu bar to associate with the frame.
360 @remarks If the frame is destroyed, the menu bar and its menus will be
361 destroyed also, so do not delete the menu bar
362 explicitly (except by resetting the frame's menu bar to
363 another frame or @NULL).
364 Under Windows, a size event is generated, so be sure to
365 initialize data members properly before calling SetMenuBar().
366 Note that on some platforms, it is not possible to call this
367 function twice for the same frame object.
369 @see GetMenuBar(), wxMenuBar, wxMenu.
371 virtual void SetMenuBar(wxMenuBar
* menuBar
);
374 Associates a status bar with the frame.
376 If @a statusBar is @NULL, then the status bar, if present, is detached from
377 the frame, but @e not deleted.
379 @see CreateStatusBar(), wxStatusBar, GetStatusBar()
381 virtual void SetStatusBar(wxStatusBar
* statusBar
);
384 Set the status bar pane used to display menu and toolbar help.
385 Using -1 disables help display.
387 void SetStatusBarPane(int n
);
390 Sets the status bar text and redraws the status bar.
393 The text for the status field.
395 The status field (starting from zero).
397 @remarks Use an empty string to clear the status bar.
399 @see CreateStatusBar(), wxStatusBar
401 virtual void SetStatusText(const wxString
& text
, int number
= 0);
404 Sets the widths of the fields in the status bar.
407 The number of fields in the status bar. It must be the
408 same used in CreateStatusBar.
410 Must contain an array of n integers, each of which is a status field width
411 in pixels. A value of -1 indicates that the field is variable width; at
412 least one field must be -1. You should delete this array after calling
415 @remarks The widths of the variable fields are calculated from the total
416 width of all fields, minus the sum of widths of the
417 non-variable fields, divided by the number of variable fields.
419 virtual void SetStatusWidths(int n
, const int* widths_field
);
422 Associates a toolbar with the frame.
424 virtual void SetToolBar(wxToolBar
* toolBar
);