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
  95 */
  96 class wxLayoutAlgorithm : public wxObject
  97 {
  98 public:
  99     /**
 100         Default constructor.
 101     */
 102     wxLayoutAlgorithm();
 103
 104     /**
 105         Destructor.
 106     */
 107     ~wxLayoutAlgorithm();
 108
 109     /**
 110         Lays out the children of a normal frame. @a mainWindow is set to occupy the
 111         remaining space.
 112         This function simply calls LayoutWindow().
 113     */
 114     bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL);
 115
 116     /**
 117         Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the
 118         given rectangle will be used as a starting point instead of the frame's client
 119         area.
 120         The MDI client window is set to occupy the remaining space.
 121     */
 122     bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL);
 123
 124     /**
 125         Lays out the children of a normal frame or other window.
 126         @a mainWindow is set to occupy the remaining space. If this is not specified,
 127         then
 128         the last window that responds to a calculate layout event in query mode will
 129         get the remaining space
 130         (that is, a non-query OnCalculateLayout event will not be sent to this window
 131         and the window will be set
 132         to the remaining size).
 133     */
 134     bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL);
 135 };
 136
 137
 138 /**
 139     @class wxSashLayoutWindow
 140     @wxheader{laywin.h}
 141
 142     wxSashLayoutWindow responds to OnCalculateLayout events generated
 143     by wxLayoutAlgorithm. It allows the
 144     application to use simple accessors to specify how the window should be
 145     laid out, rather than having to respond to events. The fact that
 146     the class derives from wxSashWindow allows sashes to be used if required,
 147     to allow the windows to be user-resizable.
 148
 149     The documentation for wxLayoutAlgorithm explains
 150     the purpose of this class in more detail.
 151
 152     @library{wxadv}
 153     @category{miscwnd}
 154
 155     @seealso
 156     wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview
 157 */
 158 class wxSashLayoutWindow : public wxSashWindow
 159 {
 160 public:
 161     //@{
 162     /**
 163         Constructs a sash layout window, which can be a child of a frame, dialog or any
 164         other non-control window.
 165
 166         @param parent
 167             Pointer to a parent window.
 168         @param id
 169             Window identifier. If -1, will automatically create an identifier.
 170         @param pos
 171             Window position. wxDefaultPosition is (-1, -1) which indicates that
 172         wxSashLayoutWindows
 173             should generate a default position for the window. If using the
 174         wxSashLayoutWindow class directly, supply
 175             an actual position.
 176         @param size
 177             Window size. wxDefaultSize is (-1, -1) which indicates that
 178         wxSashLayoutWindows
 179             should generate a default size for the window.
 180         @param style
 181             Window style. For window styles, please see wxSashLayoutWindow.
 182         @param name
 183             Window name.
 184     */
 185     wxSashLayoutWindow();
 186     wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id,
 187                        const wxPoint& pos = wxDefaultPosition,
 188                        const wxSize& size = wxDefaultSize,
 189                        long style = wxCLIP_CHILDREN | wxSW_3D,
 190                        const wxString& name = "layoutWindow");
 191     //@}
 192
 193     /**
 194         Initializes a sash layout window, which can be a child of a frame, dialog or
 195         any other non-control window.
 196
 197         @param parent
 198             Pointer to a parent window.
 199         @param id
 200             Window identifier. If -1, will automatically create an identifier.
 201         @param pos
 202             Window position. wxDefaultPosition is (-1, -1) which indicates that
 203         wxSashLayoutWindows
 204             should generate a default position for the window. If using the
 205         wxSashLayoutWindow class directly, supply
 206             an actual position.
 207         @param size
 208             Window size. wxDefaultSize is (-1, -1) which indicates that
 209         wxSashLayoutWindows
 210             should generate a default size for the window.
 211         @param style
 212             Window style. For window styles, please see wxSashLayoutWindow.
 213         @param name
 214             Window name.
 215     */
 216     bool Create(wxSashLayoutWindow* parent, wxWindowID id,
 217                 const wxPoint& pos = wxDefaultPosition,
 218                 const wxSize& size = wxDefaultSize,
 219                 long style = wxCLIP_CHILDREN | wxSW_3D,
 220                 const wxString& name = "layoutWindow");
 221
 222     /**
 223         Returns the alignment of the window: one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
 224         wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
 225     */
 226     wxLayoutAlignment GetAlignment();
 227
 228     /**
 229         Returns the orientation of the window: one of wxLAYOUT_HORIZONTAL,
 230         wxLAYOUT_VERTICAL.
 231     */
 232     wxLayoutOrientation GetOrientation();
 233
 234     /**
 235         The default handler for the event that is generated by wxLayoutAlgorithm. The
 236         implementation
 237         of this function calls wxCalculateLayoutEvent::SetRect to shrink the provided
 238         size according to
 239         how much space this window takes up. For further details,
 240         see wxLayoutAlgorithm and wxCalculateLayoutEvent.
 241     */
 242     void OnCalculateLayout(wxCalculateLayoutEvent& event);
 243
 244     /**
 245         The default handler for the event that is generated by OnCalculateLayout to get
 246         size, alignment and orientation information for the window. The implementation
 247         of this function uses member variables as set by accessors called by the
 248         application.
 249         For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent.
 250     */
 251     void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event);
 252
 253     /**
 254         Sets the alignment of the window (which edge of the available parent client
 255         area the window
 256         is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
 257         wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
 258     */
 259     void SetAlignment(wxLayoutAlignment alignment);
 260
 261     /**
 262         Sets the default dimensions of the window. The dimension other than the
 263         orientation will be fixed to this
 264         value, and the orientation dimension will be ignored and the window stretched
 265         to fit the available space.
 266     */
 267     void SetDefaultSize(const wxSize& size);
 268
 269     /**
 270         Sets the orientation of the window (the direction the window will stretch in,
 271         to fill the available
 272         parent client area). @a orientation is one of wxLAYOUT_HORIZONTAL,
 273         wxLAYOUT_VERTICAL.
 274     */
 275     void SetOrientation(wxLayoutOrientation orientation);
 276 };
 277
 278
 279 /**
 280     @class wxQueryLayoutInfoEvent
 281     @wxheader{laywin.h}
 282
 283     This event is sent when wxLayoutAlgorithm wishes to get
 284     the size, orientation and alignment of a window. More precisely, the event is
 285     sent
 286     by the OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm.
 287
 288     @library{wxadv}
 289     @category{events}
 290
 291     @seealso
 292     wxCalculateLayoutEvent, wxSashLayoutWindow, wxLayoutAlgorithm.
 293 */
 294 class wxQueryLayoutInfoEvent : public wxEvent
 295 {
 296 public:
 297     /**
 298         Constructor.
 299     */
 300     wxQueryLayoutInfoEvent(wxWindowID id = 0);
 301
 302     /**
 303         Specifies the alignment of the window (which side of the remaining parent
 304         client area
 305         the window sticks to). One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT,
 306         wxLAYOUT_BOTTOM.
 307     */
 308     void GetAlignment();
 309
 310     /**
 311         Returns the flags associated with this event. Not currently used.
 312     */
 313     int GetFlags();
 314
 315     /**
 316         Returns the orientation that the event handler specified to the event object.
 317         May be one of wxLAYOUT_HORIZONTAL,
 318         wxLAYOUT_VERTICAL.
 319     */
 320     wxLayoutOrientation GetOrientation();
 321
 322     /**
 323         Returns the requested length of the window in the direction of the window
 324         orientation. This information
 325         is not yet used.
 326     */
 327     int GetRequestedLength();
 328
 329     /**
 330         Returns the size that the event handler specified to the event object as being
 331         the requested size of the window.
 332     */
 333     wxSize GetSize();
 334
 335     /**
 336         Call this to specify the alignment of the window (which side of the remaining
 337         parent client area
 338         the window sticks to). May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
 339         wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
 340     */
 341     void SetAlignment(wxLayoutAlignment alignment);
 342
 343     /**
 344         Sets the flags associated with this event. Not currently used.
 345     */
 346     void SetFlags(int flags);
 347
 348     /**
 349         Call this to specify the orientation of the window. May be one of
 350         wxLAYOUT_HORIZONTAL,
 351         wxLAYOUT_VERTICAL.
 352     */
 353     void SetOrientation(wxLayoutOrientation orientation);
 354
 355     /**
 356         Sets the requested length of the window in the direction of the window
 357         orientation. This information
 358         is not yet used.
 359     */
 360     void SetRequestedLength(int length);
 361
 362     /**
 363         Call this to let the calling code know what the size of the window is.
 364     */
 365     void SetSize(const wxSize& size);
 366 };
 367
 368
 369 /**
 370     @class wxCalculateLayoutEvent
 371     @wxheader{laywin.h}
 372
 373     This event is sent by wxLayoutAlgorithm to
 374     calculate the amount of the remaining client area that the window should
 375     occupy.
 376
 377     @library{wxadv}
 378     @category{events}
 379
 380     @seealso
 381     wxQueryLayoutInfoEvent, wxSashLayoutWindow, wxLayoutAlgorithm.
 382 */
 383 class wxCalculateLayoutEvent : public wxEvent
 384 {
 385 public:
 386     /**
 387         Constructor.
 388     */
 389     wxCalculateLayoutEvent(wxWindowID id = 0);
 390
 391     /**
 392         Returns the flags associated with this event. Not currently used.
 393     */
 394     int GetFlags();
 395
 396     /**
 397         Before the event handler is entered, returns the remaining parent client area
 398         that the window
 399         could occupy. When the event handler returns, this should contain the remaining
 400         parent client rectangle,
 401         after the event handler has subtracted the area that its window occupies.
 402     */
 403     wxRect GetRect();
 404
 405     /**
 406         Sets the flags associated with this event. Not currently used.
 407     */
 408     void SetFlags(int flags);
 409
 410     /**
 411         Call this to specify the new remaining parent client area, after the space
 412         occupied by the
 413         window has been subtracted.
 414     */
 415     void SetRect(const wxRect& rect);
 416 };