]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/frame.h
take const address objects in wxSocketClient::Connect() and wxSocketBase::SetLocal()
[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 wxframe_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 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 | wxRESIZE_BOX | 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 @library{wxcore}
110 @category{managedwnd}
111
112 @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog
113 */
114 class wxFrame : public wxTopLevelWindow
115 {
116 public:
117 //@{
118 /**
119 Constructor, creating the window.
120
121 @param parent
122 The window parent. This may be @NULL. If it is non-@NULL, the frame will
123 always be displayed on top of the parent window on Windows.
124 @param id
125 The window identifier. It may take a value of -1 to indicate a default
126 value.
127 @param title
128 The caption to be displayed on the frame's title bar.
129 @param pos
130 The window position. The value wxDefaultPosition indicates a default position,
131 chosen by
132 either the windowing system or wxWidgets, depending on platform.
133 @param size
134 The window size. The value wxDefaultSize indicates a default size, chosen by
135 either the windowing system or wxWidgets, depending on platform.
136 @param style
137 The window style. See wxFrame.
138 @param name
139 The name of the window. This parameter is used to associate a name with the
140 item,
141 allowing the application user to set Motif resource values for
142 individual windows.
143
144 @remarks For Motif, MWM (the Motif Window Manager) should be running for
145 any window styles to work (otherwise all styles take
146 effect).
147
148 @see Create()
149 */
150 wxFrame();
151 wxFrame(wxWindow* parent, wxWindowID id,
152 const wxString& title,
153 const wxPoint& pos = wxDefaultPosition,
154 const wxSize& size = wxDefaultSize,
155 long style = wxDEFAULT_FRAME_STYLE,
156 const wxString& name = "frame");
157 //@}
158
159 /**
160 Destructor. Destroys all child windows and menu bar if present.
161 */
162 ~wxFrame();
163
164 /**
165 Centres the frame on the display.
166
167 @param direction
168 The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH.
169 */
170 void Centre(int direction = wxBOTH);
171
172 /**
173 Used in two-step frame construction. See wxFrame()
174 for further details.
175 */
176 bool Create(wxWindow* parent, wxWindowID id,
177 const wxString& title,
178 const wxPoint& pos = wxDefaultPosition,
179 const wxSize& size = wxDefaultSize,
180 long style = wxDEFAULT_FRAME_STYLE,
181 const wxString& name = "frame");
182
183 /**
184 Creates a status bar at the bottom of the frame.
185
186 @param number
187 The number of fields to create. Specify a
188 value greater than 1 to create a multi-field status bar.
189 @param style
190 The status bar style. See wxStatusBar for a list
191 of valid styles.
192 @param id
193 The status bar window identifier. If -1, an identifier will be chosen by
194 wxWidgets.
195 @param name
196 The status bar window name.
197
198 @return A pointer to the status bar if it was created successfully, @NULL
199 otherwise.
200
201 @remarks The width of the status bar is the whole width of the frame
202 (adjusted automatically when resizing), and the height
203 and text size are chosen by the host windowing system.
204
205 @see SetStatusText(), OnCreateStatusBar(), GetStatusBar()
206 */
207 virtual wxStatusBar* CreateStatusBar(int number = 1,
208 long style = 0,
209 wxWindowID id = -1,
210 const wxString& name = "statusBar");
211
212 /**
213 Creates a toolbar at the top or left of the frame.
214
215 @param style
216 The toolbar style. See wxToolBar for a list
217 of valid styles.
218 @param id
219 The toolbar window identifier. If -1, an identifier will be chosen by
220 wxWidgets.
221 @param name
222 The toolbar window name.
223
224 @return A pointer to the toolbar if it was created successfully, @NULL
225 otherwise.
226
227 @remarks By default, the toolbar is an instance of wxToolBar (which is
228 defined to be a suitable toolbar class on each
229 platform, such as wxToolBar95). To use a different
230 class, override OnCreateToolBar().
231
232 @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(),
233 GetToolBar()
234 */
235 virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL,
236 wxWindowID id = -1,
237 const wxString& name = "toolBar");
238
239 /**
240 Returns the origin of the frame client area (in client coordinates). It may be
241 different from (0, 0) if the frame has a toolbar.
242 */
243 wxPoint GetClientAreaOrigin() const;
244
245 /**
246 Returns a pointer to the menubar currently associated with the frame (if any).
247
248 @see SetMenuBar(), wxMenuBar, wxMenu
249 */
250 wxMenuBar* GetMenuBar() const;
251
252 /**
253 Returns a pointer to the status bar currently associated with the frame (if
254 any).
255
256 @see CreateStatusBar(), wxStatusBar
257 */
258 wxStatusBar* GetStatusBar() const;
259
260 /**
261 Returns the status bar pane used to display menu and toolbar help.
262
263 @see SetStatusBarPane()
264 */
265 int GetStatusBarPane();
266
267 /**
268 Returns a pointer to the toolbar currently associated with the frame (if any).
269
270 @see CreateToolBar(), wxToolBar, SetToolBar()
271 */
272 wxToolBar* GetToolBar() const;
273
274 /**
275 Virtual function called when a status bar is requested by CreateStatusBar().
276
277 @param number
278 The number of fields to create.
279 @param style
280 The window style. See wxStatusBar for a list
281 of valid styles.
282 @param id
283 The window identifier. If -1, an identifier will be chosen by
284 wxWidgets.
285 @param name
286 The window name.
287
288 @return A status bar object.
289
290 @remarks An application can override this function to return a different
291 kind of status bar. The default implementation returns
292 an instance of wxStatusBar.
293
294 @see CreateStatusBar(), wxStatusBar.
295 */
296 virtual wxStatusBar* OnCreateStatusBar(int number, long style,
297 wxWindowID id,
298 const wxString& name);
299
300 /**
301 Virtual function called when a toolbar is requested by CreateToolBar().
302
303 @param style
304 The toolbar style. See wxToolBar for a list
305 of valid styles.
306 @param id
307 The toolbar window identifier. If -1, an identifier will be chosen by
308 wxWidgets.
309 @param name
310 The toolbar window name.
311
312 @return A toolbar object.
313
314 @remarks An application can override this function to return a different
315 kind of toolbar. The default implementation returns an
316 instance of wxToolBar.
317
318 @see CreateToolBar(), wxToolBar.
319 */
320 virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id,
321 const wxString& name);
322
323 /**
324 Simulate a menu command.
325
326 @param id
327 The identifier for a menu item.
328 */
329 void ProcessCommand(int id);
330
331 /**
332 This function sends a dummy @ref overview_wxsizeevent "size event" to the frame
333 forcing it to reevaluate its children positions. It is sometimes useful to call
334 this function after adding or deleting a children after the frame creation or
335 if a child size changes.
336 Note that if the frame is using either sizers or constraints for the children
337 layout, it is enough to call wxWindow::Layout directly and
338 this function should not be used in this case.
339 */
340 void SendSizeEvent();
341
342 /**
343 Tells the frame to show the given menu bar.
344
345 @param menuBar
346 The menu bar to associate with the frame.
347
348 @remarks If the frame is destroyed, the menu bar and its menus will be
349 destroyed also, so do not delete the menu bar
350 explicitly (except by resetting the frame's menu bar to
351 another frame or @NULL).
352
353 @see GetMenuBar(), wxMenuBar, wxMenu.
354 */
355 void SetMenuBar(wxMenuBar* menuBar);
356
357 /**
358 Associates a status bar with the frame.
359
360 @see CreateStatusBar(), wxStatusBar, GetStatusBar()
361 */
362 void SetStatusBar(wxStatusBar* statusBar);
363
364 /**
365 Set the status bar pane used to display menu and toolbar help.
366 Using -1 disables help display.
367 */
368 void SetStatusBarPane(int n);
369
370 /**
371 Sets the status bar text and redraws the status bar.
372
373 @param text
374 The text for the status field.
375 @param number
376 The status field (starting from zero).
377
378 @remarks Use an empty string to clear the status bar.
379
380 @see CreateStatusBar(), wxStatusBar
381 */
382 virtual void SetStatusText(const wxString& text, int number = 0);
383
384 /**
385 Sets the widths of the fields in the status bar.
386
387 @param n
388 The number of fields in the status bar. It must be the
389 same used in CreateStatusBar.
390 @param widths
391 Must contain an array of n integers, each of which is a status field width
392 in pixels. A value of -1 indicates that the field is variable width; at
393 least one
394 field must be -1. You should delete this array after calling
395 SetStatusWidths.
396
397 @remarks The widths of the variable fields are calculated from the total
398 width of all fields, minus the sum of widths of the
399 non-variable fields, divided by the number of variable
400 fields.
401 */
402 virtual void SetStatusWidths(int n, int* widths);
403
404 /**
405 Associates a toolbar with the frame.
406 */
407 void SetToolBar(wxToolBar* toolBar);
408 };
409