]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/laywin.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / laywin.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: laywin.h
3 // Purpose: interface of wxLayoutAlgorithm
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9 Enumeration used by wxLayoutAlgorithm.
10 */
11 enum wxLayoutOrientation
12 {
13 wxLAYOUT_HORIZONTAL,
14 wxLAYOUT_VERTICAL
15 };
16
17 /**
18 Enumeration used by wxLayoutAlgorithm.
19 */
20 enum wxLayoutAlignment
21 {
22 wxLAYOUT_NONE,
23 wxLAYOUT_TOP,
24 wxLAYOUT_LEFT,
25 wxLAYOUT_RIGHT,
26 wxLAYOUT_BOTTOM
27 };
28
29 /**
30 @class wxLayoutAlgorithm
31
32 wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames.
33 It sends a wxCalculateLayoutEvent event to children of the frame, asking them
34 for information about their size. For MDI parent frames, the algorithm allocates
35 the remaining space to the MDI client window (which contains the MDI child frames).
36
37 For SDI (normal) frames, a 'main' window is specified as taking up the
38 remaining space.
39
40 Because the event system is used, this technique can be applied to any windows,
41 which are not necessarily 'aware' of the layout classes (no virtual functions
42 in wxWindow refer to wxLayoutAlgorithm or its events).
43 However, you may wish to use wxSashLayoutWindow for your subwindows since this
44 class provides handlers for the required events, and accessors to specify the
45 desired size of the window. The sash behaviour in the base class can be used,
46 optionally, to make the windows user-resizable.
47
48 wxLayoutAlgorithm is typically used in IDE (integrated development environment)
49 applications, where there are several resizable windows in addition to the MDI
50 client window, or other primary editing window. Resizable windows might include
51 toolbars, a project window, and a window for displaying error and warning messages.
52
53 When a window receives an OnCalculateLayout event, it should call SetRect in
54 the given event object, to be the old supplied rectangle minus whatever space
55 the window takes up. It should also set its own size accordingly.
56 wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event
57 which it sends to itself to determine the orientation, alignment and size of
58 the window, which it gets from internal member variables set by the application.
59
60 The algorithm works by starting off with a rectangle equal to the whole frame
61 client area. It iterates through the frame children, generating
62 wxLayoutAlgorithm::OnCalculateLayout events which subtract the window size and
63 return the remaining rectangle for the next window to process.
64 It is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches
65 the full dimension of the frame client, according to the orientation it specifies.
66 For example, a horizontal window will stretch the full width of the remaining
67 portion of the frame client area.
68 In the other orientation, the window will be fixed to whatever size was
69 specified by wxLayoutAlgorithm::OnQueryLayoutInfo. An alignment setting will
70 make the window 'stick' to the left, top, right or bottom of the remaining
71 client area. This scheme implies that order of window creation is important.
72 Say you wish to have an extra toolbar at the top of the frame, a project window
73 to the left of the MDI client window, and an output window above the status bar.
74 You should therefore create the windows in this order: toolbar, output window,
75 project window. This ensures that the toolbar and output window take up space
76 at the top and bottom, and then the remaining height in-between is used for
77 the project window.
78
79 wxLayoutAlgorithm is quite independent of the way in which
80 wxLayoutAlgorithm::OnCalculateLayout chooses to interpret a window's size and
81 alignment. Therefore you could implement a different window class with a new
82 wxLayoutAlgorithm::OnCalculateLayout event handler, that has a more sophisticated
83 way of laying out the windows. It might allow specification of whether stretching
84 occurs in the specified orientation, for example, rather than always assuming
85 stretching.
86 (This could, and probably should, be added to the existing implementation).
87
88 @note wxLayoutAlgorithm has nothing to do with wxLayoutConstraints.
89 It is an alternative way of specifying layouts for which the normal
90 constraint system is unsuitable.
91
92 @beginEventEmissionTable{wxQueryLayoutInfoEvent,wxCalculateLayoutEvent}
93 @event{EVT_QUERY_LAYOUT_INFO(func)}
94 Process a @c wxEVT_QUERY_LAYOUT_INFO event, to get size, orientation and
95 alignment from a window. See wxQueryLayoutInfoEvent.
96 @event{EVT_CALCULATE_LAYOUT(func)}
97 Process a @c wxEVT_CALCULATE_LAYOUT event, which asks the window to take a
98 'bite' out of a rectangle provided by the algorithm. See wxCalculateLayoutEvent.
99 @endEventTable
100
101 Note that the algorithm object does not respond to events, but itself generates the
102 previous events in order to calculate window sizes.
103
104
105 @library{wxadv}
106 @category{winlayout}
107
108 @see wxSashEvent, wxSashLayoutWindow, @ref overview_events
109 */
110 class wxLayoutAlgorithm : public wxObject
111 {
112 public:
113 /**
114 Default constructor.
115 */
116 wxLayoutAlgorithm();
117
118 /**
119 Destructor.
120 */
121 virtual ~wxLayoutAlgorithm();
122
123 /**
124 Lays out the children of a normal frame. @a mainWindow is set to occupy the
125 remaining space. This function simply calls LayoutWindow().
126 */
127 bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL);
128
129 /**
130 Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the
131 given rectangle will be used as a starting point instead of the frame's client
132 area. The MDI client window is set to occupy the remaining space.
133 */
134 bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL);
135
136 /**
137 Lays out the children of a normal frame or other window.
138
139 @a mainWindow is set to occupy the remaining space. If this is not specified,
140 then the last window that responds to a calculate layout event in query mode will
141 get the remaining space (that is, a non-query OnCalculateLayout event will
142 not be sent to this window and the window will be set to the remaining size).
143 */
144 bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL);
145 };
146
147
148
149 /**
150 @class wxSashLayoutWindow
151
152 wxSashLayoutWindow responds to OnCalculateLayout events generated by wxLayoutAlgorithm.
153 It allows the application to use simple accessors to specify how the window
154 should be laid out, rather than having to respond to events.
155
156 The fact that the class derives from wxSashWindow allows sashes to be used if
157 required, to allow the windows to be user-resizable.
158
159 The documentation for wxLayoutAlgorithm explains the purpose of this class in
160 more detail.
161
162 For the window styles see wxSashWindow.
163
164 This class handles the EVT_QUERY_LAYOUT_INFO and EVT_CALCULATE_LAYOUT events
165 for you. However, if you use sashes, see wxSashWindow for relevant event information.
166 See also wxLayoutAlgorithm for information about the layout events.
167
168 @library{wxadv}
169 @category{miscwnd}
170
171 @see wxLayoutAlgorithm, wxSashWindow, @ref overview_events
172 */
173 class wxSashLayoutWindow : public wxSashWindow
174 {
175 public:
176 /**
177 Default ctor.
178 */
179 wxSashLayoutWindow();
180
181 /**
182 Constructs a sash layout window, which can be a child of a frame, dialog or any
183 other non-control window.
184
185 @param parent
186 Pointer to a parent window.
187 @param id
188 Window identifier. If -1, will automatically create an identifier.
189 @param pos
190 Window position. wxDefaultPosition is (-1, -1) which indicates that
191 wxSashLayoutWindows should generate a default position for the window.
192 If using the wxSashLayoutWindow class directly, supply an actual position.
193 @param size
194 Window size. wxDefaultSize is (-1, -1) which indicates that
195 wxSashLayoutWindows should generate a default size for the window.
196 @param style
197 Window style. For window styles, please see wxSashLayoutWindow.
198 @param name
199 Window name.
200 */
201 wxSashLayoutWindow(wxWindow* parent, wxWindowID id,
202 const wxPoint& pos = wxDefaultPosition,
203 const wxSize& size = wxDefaultSize,
204 long style = wxCLIP_CHILDREN | wxSW_3D,
205 const wxString& name = "layoutWindow");
206
207 /**
208 Initializes a sash layout window, which can be a child of a frame, dialog or
209 any other non-control window.
210
211 @param parent
212 Pointer to a parent window.
213 @param id
214 Window identifier. If -1, will automatically create an identifier.
215 @param pos
216 Window position. wxDefaultPosition is (-1, -1) which indicates that
217 wxSashLayoutWindows should generate a default position for the window.
218 If using the wxSashLayoutWindow class directly, supply an actual position.
219 @param size
220 Window size. wxDefaultSize is (-1, -1) which indicates that
221 wxSashLayoutWindows should generate a default size for the window.
222 @param style
223 Window style. For window styles, please see wxSashLayoutWindow.
224 @param name
225 Window name.
226 */
227 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
228 const wxPoint& pos = wxDefaultPosition,
229 const wxSize& size = wxDefaultSize,
230 long style = wxCLIP_CHILDREN | wxSW_3D,
231 const wxString& name = "layoutWindow");
232
233 /**
234 Returns the alignment of the window: one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
235 wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
236 */
237 wxLayoutAlignment GetAlignment() const;
238
239 /**
240 Returns the orientation of the window: one of wxLAYOUT_HORIZONTAL,
241 wxLAYOUT_VERTICAL.
242 */
243 wxLayoutOrientation GetOrientation() const;
244
245 /**
246 The default handler for the event that is generated by wxLayoutAlgorithm.
247 The implementation of this function calls wxCalculateLayoutEvent::SetRect
248 to shrink the provided size according to how much space this window takes up.
249 For further details, see wxLayoutAlgorithm and wxCalculateLayoutEvent.
250 */
251 void OnCalculateLayout(wxCalculateLayoutEvent& event);
252
253 /**
254 The default handler for the event that is generated by OnCalculateLayout to get
255 size, alignment and orientation information for the window.
256 The implementation of this function uses member variables as set by accessors
257 called by the application.
258
259 For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent.
260 */
261 void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event);
262
263 /**
264 Sets the alignment of the window (which edge of the available parent client
265 area the window is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
266 wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
267 */
268 void SetAlignment(wxLayoutAlignment alignment);
269
270 /**
271 Sets the default dimensions of the window. The dimension other than the
272 orientation will be fixed to this value, and the orientation dimension
273 will be ignored and the window stretched to fit the available space.
274 */
275 void SetDefaultSize(const wxSize& size);
276
277 /**
278 Sets the orientation of the window (the direction the window will stretch in,
279 to fill the available parent client area). @a orientation is one of
280 wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
281 */
282 void SetOrientation(wxLayoutOrientation orientation);
283 };
284
285
286
287 /**
288 @class wxQueryLayoutInfoEvent
289
290 This event is sent when wxLayoutAlgorithm wishes to get the size, orientation
291 and alignment of a window. More precisely, the event is sent by the
292 OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm.
293
294 @beginEventTable{wxQueryLayoutInfoEvent}
295 @event{EVT_QUERY_LAYOUT_INFO(func)}
296 Process a @c wxEVT_QUERY_LAYOUT_INFO event, to get size, orientation and alignment
297 from a window.
298 @endEventTable
299
300 @library{wxadv}
301 @category{events}
302
303 @see wxCalculateLayoutEvent, wxSashLayoutWindow, wxLayoutAlgorithm.
304 */
305 class wxQueryLayoutInfoEvent : public wxEvent
306 {
307 public:
308 /**
309 Constructor.
310 */
311 wxQueryLayoutInfoEvent(wxWindowID id = 0);
312
313 /**
314 Specifies the alignment of the window (which side of the remaining parent
315 client area the window sticks to).
316 One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
317 */
318 wxLayoutAlignment GetAlignment() const;
319
320 /**
321 Returns the flags associated with this event. Not currently used.
322 */
323 int GetFlags() const;
324
325 /**
326 Returns the orientation that the event handler specified to the event object.
327 May be one of wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
328 */
329 wxLayoutOrientation GetOrientation() const;
330
331 /**
332 Returns the requested length of the window in the direction of the window
333 orientation. This information is not yet used.
334 */
335 int GetRequestedLength() const;
336
337 /**
338 Returns the size that the event handler specified to the event object as being
339 the requested size of the window.
340 */
341 wxSize GetSize() const;
342
343 /**
344 Call this to specify the alignment of the window (which side of the remaining
345 parent client area the window sticks to).
346 May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
347 */
348 void SetAlignment(wxLayoutAlignment alignment);
349
350 /**
351 Sets the flags associated with this event. Not currently used.
352 */
353 void SetFlags(int flags);
354
355 /**
356 Call this to specify the orientation of the window.
357 May be one of wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
358 */
359 void SetOrientation(wxLayoutOrientation orientation);
360
361 /**
362 Sets the requested length of the window in the direction of the window
363 orientation. This information is not yet used.
364 */
365 void SetRequestedLength(int length);
366
367 /**
368 Call this to let the calling code know what the size of the window is.
369 */
370 void SetSize(const wxSize& size);
371 };
372
373
374 wxEventType wxEVT_QUERY_LAYOUT_INFO;
375
376
377 /**
378 @class wxCalculateLayoutEvent
379
380 This event is sent by wxLayoutAlgorithm to calculate the amount of the
381 remaining client area that the window should occupy.
382
383 @beginEventTable{wxCalculateLayoutEvent}
384 @event{EVT_CALCULATE_LAYOUT(func)}
385 Process a @c wxEVT_CALCULATE_LAYOUT event, which asks the window to take a
386 'bite' out of a rectangle provided by the algorithm.
387 @endEventTable
388
389 @library{wxadv}
390 @category{events}
391
392 @see wxQueryLayoutInfoEvent, wxSashLayoutWindow, wxLayoutAlgorithm.
393 */
394 class wxCalculateLayoutEvent : public wxEvent
395 {
396 public:
397 /**
398 Constructor.
399 */
400 wxCalculateLayoutEvent(wxWindowID id = 0);
401
402 /**
403 Returns the flags associated with this event. Not currently used.
404 */
405 int GetFlags() const;
406
407 /**
408 Before the event handler is entered, returns the remaining parent client area
409 that the window could occupy.
410
411 When the event handler returns, this should contain the remaining parent
412 client rectangle, after the event handler has subtracted the area that its
413 window occupies.
414 */
415 wxRect GetRect() const;
416
417 /**
418 Sets the flags associated with this event. Not currently used.
419 */
420 void SetFlags(int flags);
421
422 /**
423 Call this to specify the new remaining parent client area, after the space
424 occupied by the window has been subtracted.
425 */
426 void SetRect(const wxRect& rect);
427 };
428
429 wxEventType wxEVT_CALCULATE_LAYOUT;
430