don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / 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
12 A frame is a window whose size and position can (usually) be changed by the user.
13
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
16 a frame or dialog.
17
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.
21
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.
25
26
27 @section frame_defaultevent Default event processing
28
29 wxFrame processes the following events:
30
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.
37
38
39 @beginStyleTable
40 @style{wxDEFAULT_FRAME_STYLE}
41 Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER |
42 wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN.
43 @style{wxICONIZE}
44 Display the frame iconized (minimized). Windows only.
45 @style{wxCAPTION}
46 Puts a caption on the frame.
47 @style{wxMINIMIZE}
48 Identical to wxICONIZE. Windows only.
49 @style{wxMINIMIZE_BOX}
50 Displays a minimize box on the frame.
51 @style{wxMAXIMIZE}
52 Displays the frame maximized. Windows only.
53 @style{wxMAXIMIZE_BOX}
54 Displays a maximize box on the frame.
55 @style{wxCLOSE_BOX}
56 Displays a close box on the frame.
57 @style{wxSTAY_ON_TOP}
58 Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT.
59 @style{wxSYSTEM_MENU}
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.
80 @endStyleTable
81
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:
85
86 @code
87 wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxMAXIMIZE_BOX)
88 @endcode
89
90 See also the @ref overview_windowstyles.
91
92 @beginExtraStyleTable
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.
107 @endExtraStyleTable
108
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.
126 See wxMenuEvent.
127 @endEventTable
128
129 @library{wxcore}
130 @category{managedwnd}
131
132 @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
133 */
134 class wxFrame : public wxTopLevelWindow
135 {
136 public:
137 /**
138 Default constructor.
139 */
140 wxFrame();
141
142 /**
143 Constructor, creating the window.
144
145 @param parent
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.
148 @param id
149 The window identifier. It may take a value of -1 to indicate a default value.
150 @param title
151 The caption to be displayed on the frame's title bar.
152 @param pos
153 The window position. The value wxDefaultPosition indicates a default position,
154 chosen by either the windowing system or wxWidgets, depending on platform.
155 @param size
156 The window size. The value wxDefaultSize indicates a default size, chosen by
157 either the windowing system or wxWidgets, depending on platform.
158 @param style
159 The window style. See wxFrame class description.
160 @param name
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
163 individual windows.
164
165 @remarks For Motif, MWM (the Motif Window Manager) should be running for
166 any window styles to work (otherwise all styles take effect).
167
168 @see Create()
169 */
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);
176
177 /**
178 Destructor. Destroys all child windows and menu bar if present.
179
180 See @ref overview_windowdeletion for more info.
181 */
182 virtual ~wxFrame();
183
184 /**
185 Centres the frame on the display.
186
187 @param direction
188 The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
189 */
190 void Centre(int direction = wxBOTH);
191
192 /**
193 Used in two-step frame construction.
194 See wxFrame() for further details.
195 */
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);
201
202 /**
203 Creates a status bar at the bottom of the frame.
204
205 @param number
206 The number of fields to create. Specify a
207 value greater than 1 to create a multi-field status bar.
208 @param style
209 The status bar style. See wxStatusBar for a list of valid styles.
210 @param id
211 The status bar window identifier. If -1, an identifier will be chosen
212 by wxWidgets.
213 @param name
214 The status bar window name.
215
216 @return A pointer to the status bar if it was created successfully, @NULL
217 otherwise.
218
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.
222
223 @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
224 */
225 virtual wxStatusBar* CreateStatusBar(int number = 1, long style = wxSTB_DEFAULT_STYLE,
226 wxWindowID id = 0,
227 const wxString& name = wxStatusLineNameStr);
228
229 /**
230 Creates a toolbar at the top or left of the frame.
231
232 @param style
233 The toolbar style. See wxToolBar for a list of valid styles.
234 @param id
235 The toolbar window identifier. If -1, an identifier will be chosen
236 by wxWidgets.
237 @param name
238 The toolbar window name.
239
240 @return A pointer to the toolbar if it was created successfully, @NULL
241 otherwise.
242
243 @remarks
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
250 application windows.
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.
255
256 @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar()
257 */
258 virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
259 wxWindowID id = wxID_ANY,
260 const wxString& name = wxToolBarNameStr);
261
262 /**
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.
265 */
266 virtual wxPoint GetClientAreaOrigin() const;
267
268 /**
269 Returns a pointer to the menubar currently associated with the frame (if any).
270
271 @see SetMenuBar(), wxMenuBar, wxMenu
272 */
273 virtual wxMenuBar* GetMenuBar() const;
274
275 /**
276 Returns a pointer to the status bar currently associated with the frame
277 (if any).
278
279 @see CreateStatusBar(), wxStatusBar
280 */
281 virtual wxStatusBar* GetStatusBar() const;
282
283 /**
284 Returns the status bar pane used to display menu and toolbar help.
285
286 @see SetStatusBarPane()
287 */
288 int GetStatusBarPane() const;
289
290 /**
291 Returns a pointer to the toolbar currently associated with the frame (if any).
292
293 @see CreateToolBar(), wxToolBar, SetToolBar()
294 */
295 virtual wxToolBar* GetToolBar() const;
296
297 /**
298 Virtual function called when a status bar is requested by CreateStatusBar().
299
300 @param number
301 The number of fields to create.
302 @param style
303 The window style. See wxStatusBar for a list
304 of valid styles.
305 @param id
306 The window identifier. If -1, an identifier will be chosen by
307 wxWidgets.
308 @param name
309 The window name.
310
311 @return A status bar object.
312
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.
316
317 @see CreateStatusBar(), wxStatusBar.
318 */
319 virtual wxStatusBar* OnCreateStatusBar(int number, long style,
320 wxWindowID id,
321 const wxString& name);
322
323 /**
324 Virtual function called when a toolbar is requested by CreateToolBar().
325
326 @param style
327 The toolbar style. See wxToolBar for a list
328 of valid styles.
329 @param id
330 The toolbar window identifier. If -1, an identifier will be chosen by
331 wxWidgets.
332 @param name
333 The toolbar window name.
334
335 @return A toolbar object.
336
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.
340
341 @see CreateToolBar(), wxToolBar.
342 */
343 virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
344 const wxString& name);
345
346 /**
347 Simulate a menu command.
348
349 @param id
350 The identifier for a menu item.
351 */
352 bool ProcessCommand(int id);
353
354 /**
355 Tells the frame to show the given menu bar.
356
357 @param menuBar
358 The menu bar to associate with the frame.
359
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.
368
369 @see GetMenuBar(), wxMenuBar, wxMenu.
370 */
371 virtual void SetMenuBar(wxMenuBar* menuBar);
372
373 /**
374 Associates a status bar with the frame.
375
376 If @a statusBar is @NULL, then the status bar, if present, is detached from
377 the frame, but @e not deleted.
378
379 @see CreateStatusBar(), wxStatusBar, GetStatusBar()
380 */
381 virtual void SetStatusBar(wxStatusBar* statusBar);
382
383 /**
384 Set the status bar pane used to display menu and toolbar help.
385 Using -1 disables help display.
386 */
387 void SetStatusBarPane(int n);
388
389 /**
390 Sets the status bar text and redraws the status bar.
391
392 @param text
393 The text for the status field.
394 @param number
395 The status field (starting from zero).
396
397 @remarks Use an empty string to clear the status bar.
398
399 @see CreateStatusBar(), wxStatusBar
400 */
401 virtual void SetStatusText(const wxString& text, int number = 0);
402
403 /**
404 Sets the widths of the fields in the status bar.
405
406 @param n
407 The number of fields in the status bar. It must be the
408 same used in CreateStatusBar.
409 @param widths_field
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
413 SetStatusWidths().
414
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.
418 */
419 virtual void SetStatusWidths(int n, const int* widths_field);
420
421 /**
422 Associates a toolbar with the frame.
423 */
424 virtual void SetToolBar(wxToolBar* toolBar);
425 };
426