interface/laywin.h

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