]> git.saurik.com Git - wxWidgets.git/blob - interface/frame.h
14b0e1d28de0b5fdb19c259424b15384c397c0aa
[wxWidgets.git] / interface / frame.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: frame.h
3 // Purpose: interface of wxFrame
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxFrame
11 @wxheader{frame.h}
12
13 A frame is a window whose size and position can (usually) be changed by the
14 user. It usually has thick borders and a title bar, and can optionally contain
15 a menu bar, toolbar and status bar. A frame can contain any window that is not
16 a frame or dialog.
17
18 A frame that has a status bar and toolbar created via the
19 CreateStatusBar/CreateToolBar functions manages these windows, and adjusts the
20 value returned by GetClientSize to reflect the remaining size available to
21 application windows.
22
23 @beginStyleTable
24 @style{wxDEFAULT_FRAME_STYLE}
25 Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER |
26 wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN.
27 @style{wxICONIZE}
28 Display the frame iconized (minimized). Windows only.
29 @style{wxCAPTION}
30 Puts a caption on the frame.
31 @style{wxMINIMIZE}
32 Identical to wxICONIZE. Windows only.
33 @style{wxMINIMIZE_BOX}
34 Displays a minimize box on the frame.
35 @style{wxMAXIMIZE}
36 Displays the frame maximized. Windows only.
37 @style{wxMAXIMIZE_BOX}
38 Displays a maximize box on the frame.
39 @style{wxCLOSE_BOX}
40 Displays a close box on the frame.
41 @style{wxSTAY_ON_TOP}
42 Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT.
43 @style{wxSYSTEM_MENU}
44 Displays a system menu.
45 @style{wxRESIZE_BORDER}
46 Displays a resizeable border around the window.
47 @style{wxFRAME_TOOL_WINDOW}
48 Causes a frame with a small titlebar to be created; the frame does
49 not appear in the taskbar under Windows or GTK+.
50 @style{wxFRAME_NO_TASKBAR}
51 Creates an otherwise normal frame but it does not appear in the
52 taskbar under Windows or GTK+ (note that it will minimize to the
53 desktop window under Windows which may seem strange to the users
54 and thus it might be better to use this style only without
55 wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if GTK+
56 is at least version 2.2 and the window manager supports
57 _NET_WM_STATE_SKIP_TASKBAR hint. Has no effect under other
58 platforms.
59 @style{wxFRAME_FLOAT_ON_PARENT}
60 The frame will always be on top of its parent (unlike
61 wxSTAY_ON_TOP). A frame created with this style must have a
62 non-@NULL parent.
63 @style{wxFRAME_EX_CONTEXTHELP}
64 Under Windows, puts a query button on the caption. When pressed,
65 Windows will go into a context-sensitive help mode and wxWidgets
66 will send a wxEVT_HELP event if the user clicked on an application
67 window. Note that this is an extended style and must be set by
68 calling SetExtraStyle before Create is called (two-step
69 construction). You cannot use this style together with
70 wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use
71 wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the
72 frames having this style (the dialogs don't have a minimize or a
73 maximize box by default)
74 @style{wxFRAME_SHAPED}
75 Windows with this style are allowed to have their shape changed
76 with the SetShape method.
77 @style{wxFRAME_EX_METAL}
78 On Mac OS X, frames with this style will be shown with a metallic
79 look. This is an extra style.
80 @endStyleTable
81
82 @library{wxcore}
83 @category{managedwnd}
84
85 @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
86 */
87 class wxFrame : public wxTopLevelWindow
88 {
89 public:
90 //@{
91 /**
92 Constructor, creating the window.
93
94 @param parent
95 The window parent. This may be @NULL. If it is non-@NULL, the frame will
96 always be displayed on top of the parent window on Windows.
97 @param id
98 The window identifier. It may take a value of -1 to indicate a default
99 value.
100 @param title
101 The caption to be displayed on the frame's title bar.
102 @param pos
103 The window position. The value wxDefaultPosition indicates a default position,
104 chosen by
105 either the windowing system or wxWidgets, depending on platform.
106 @param size
107 The window size. The value wxDefaultSize indicates a default size, chosen by
108 either the windowing system or wxWidgets, depending on platform.
109 @param style
110 The window style. See wxFrame.
111 @param name
112 The name of the window. This parameter is used to associate a name with the
113 item,
114 allowing the application user to set Motif resource values for
115 individual windows.
116
117 @remarks For Motif, MWM (the Motif Window Manager) should be running for
118 any window styles to work (otherwise all styles take
119 effect).
120
121 @see Create()
122 */
123 wxFrame();
124 wxFrame(wxWindow* parent, wxWindowID id,
125 const wxString& title,
126 const wxPoint& pos = wxDefaultPosition,
127 const wxSize& size = wxDefaultSize,
128 long style = wxDEFAULT_FRAME_STYLE,
129 const wxString& name = "frame");
130 //@}
131
132 /**
133 Destructor. Destroys all child windows and menu bar if present.
134 */
135 ~wxFrame();
136
137 /**
138 Centres the frame on the display.
139
140 @param direction
141 The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
142 */
143 void Centre(int direction = wxBOTH);
144
145 /**
146 Used in two-step frame construction. See wxFrame()
147 for further details.
148 */
149 bool Create(wxWindow* parent, wxWindowID id,
150 const wxString& title,
151 const wxPoint& pos = wxDefaultPosition,
152 const wxSize& size = wxDefaultSize,
153 long style = wxDEFAULT_FRAME_STYLE,
154 const wxString& name = "frame");
155
156 /**
157 Creates a status bar at the bottom of the frame.
158
159 @param number
160 The number of fields to create. Specify a
161 value greater than 1 to create a multi-field status bar.
162 @param style
163 The status bar style. See wxStatusBar for a list
164 of valid styles.
165 @param id
166 The status bar window identifier. If -1, an identifier will be chosen by
167 wxWidgets.
168 @param name
169 The status bar window name.
170
171 @returns A pointer to the status bar if it was created successfully, @NULL
172 otherwise.
173
174 @remarks The width of the status bar is the whole width of the frame
175 (adjusted automatically when resizing), and the height
176 and text size are chosen by the host windowing system.
177
178 @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
179 */
180 virtual wxStatusBar* CreateStatusBar(int number = 1,
181 long style = 0,
182 wxWindowID id = -1,
183 const wxString& name = "statusBar");
184
185 /**
186 Creates a toolbar at the top or left of the frame.
187
188 @param style
189 The toolbar style. See wxToolBar for a list
190 of valid styles.
191 @param id
192 The toolbar window identifier. If -1, an identifier will be chosen by
193 wxWidgets.
194 @param name
195 The toolbar window name.
196
197 @returns A pointer to the toolbar if it was created successfully, @NULL
198 otherwise.
199
200 @remarks By default, the toolbar is an instance of wxToolBar (which is
201 defined to be a suitable toolbar class on each
202 platform, such as wxToolBar95). To use a different
203 class, override OnCreateToolBar().
204
205 @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(),
206 GetToolBar()
207 */
208 virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
209 wxWindowID id = -1,
210 const wxString& name = "toolBar");
211
212 /**
213 Returns the origin of the frame client area (in client coordinates). It may be
214 different from (0, 0) if the frame has a toolbar.
215 */
216 wxPoint GetClientAreaOrigin() const;
217
218 /**
219 Returns a pointer to the menubar currently associated with the frame (if any).
220
221 @see SetMenuBar(), wxMenuBar, wxMenu
222 */
223 wxMenuBar* GetMenuBar() const;
224
225 /**
226 Returns a pointer to the status bar currently associated with the frame (if
227 any).
228
229 @see CreateStatusBar(), wxStatusBar
230 */
231 wxStatusBar* GetStatusBar() const;
232
233 /**
234 Returns the status bar pane used to display menu and toolbar help.
235
236 @see SetStatusBarPane()
237 */
238 int GetStatusBarPane();
239
240 /**
241 Returns a pointer to the toolbar currently associated with the frame (if any).
242
243 @see CreateToolBar(), wxToolBar, SetToolBar()
244 */
245 wxToolBar* GetToolBar() const;
246
247 /**
248 Virtual function called when a status bar is requested by CreateStatusBar().
249
250 @param number
251 The number of fields to create.
252 @param style
253 The window style. See wxStatusBar for a list
254 of valid styles.
255 @param id
256 The window identifier. If -1, an identifier will be chosen by
257 wxWidgets.
258 @param name
259 The window name.
260
261 @returns A status bar object.
262
263 @remarks An application can override this function to return a different
264 kind of status bar. The default implementation returns
265 an instance of wxStatusBar.
266
267 @see CreateStatusBar(), wxStatusBar.
268 */
269 virtual wxStatusBar* OnCreateStatusBar(int number, long style,
270 wxWindowID id,
271 const wxString& name);
272
273 /**
274 Virtual function called when a toolbar is requested by CreateToolBar().
275
276 @param style
277 The toolbar style. See wxToolBar for a list
278 of valid styles.
279 @param id
280 The toolbar window identifier. If -1, an identifier will be chosen by
281 wxWidgets.
282 @param name
283 The toolbar window name.
284
285 @returns A toolbar object.
286
287 @remarks An application can override this function to return a different
288 kind of toolbar. The default implementation returns an
289 instance of wxToolBar.
290
291 @see CreateToolBar(), wxToolBar.
292 */
293 virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
294 const wxString& name);
295
296 /**
297 Simulate a menu command.
298
299 @param id
300 The identifier for a menu item.
301 */
302 void ProcessCommand(int id);
303
304 /**
305 This function sends a dummy @ref overview_wxsizeevent "size event" to the frame
306 forcing it to reevaluate its children positions. It is sometimes useful to call
307 this function after adding or deleting a children after the frame creation or
308 if a child size changes.
309 Note that if the frame is using either sizers or constraints for the children
310 layout, it is enough to call wxWindow::Layout directly and
311 this function should not be used in this case.
312 */
313 void SendSizeEvent();
314
315 /**
316 Tells the frame to show the given menu bar.
317
318 @param menuBar
319 The menu bar to associate with the frame.
320
321 @remarks If the frame is destroyed, the menu bar and its menus will be
322 destroyed also, so do not delete the menu bar
323 explicitly (except by resetting the frame's menu bar to
324 another frame or @NULL).
325
326 @see GetMenuBar(), wxMenuBar, wxMenu.
327 */
328 void SetMenuBar(wxMenuBar* menuBar);
329
330 /**
331 Associates a status bar with the frame.
332
333 @see CreateStatusBar(), wxStatusBar, GetStatusBar()
334 */
335 void SetStatusBar(wxStatusBar* statusBar);
336
337 /**
338 Set the status bar pane used to display menu and toolbar help.
339 Using -1 disables help display.
340 */
341 void SetStatusBarPane(int n);
342
343 /**
344 Sets the status bar text and redraws the status bar.
345
346 @param text
347 The text for the status field.
348 @param number
349 The status field (starting from zero).
350
351 @remarks Use an empty string to clear the status bar.
352
353 @see CreateStatusBar(), wxStatusBar
354 */
355 virtual void SetStatusText(const wxString& text, int number = 0);
356
357 /**
358 Sets the widths of the fields in the status bar.
359
360 @param n
361 The number of fields in the status bar. It must be the
362 same used in CreateStatusBar.
363 @param widths
364 Must contain an array of n integers, each of which is a status field width
365 in pixels. A value of -1 indicates that the field is variable width; at
366 least one
367 field must be -1. You should delete this array after calling
368 SetStatusWidths.
369
370 @remarks The widths of the variable fields are calculated from the total
371 width of all fields, minus the sum of widths of the
372 non-variable fields, divided by the number of variable
373 fields.
374 */
375 virtual void SetStatusWidths(int n, int* widths);
376
377 /**
378 Associates a toolbar with the frame.
379 */
380 void SetToolBar(wxToolBar* toolBar);
381 };
382