interface/laywin.h

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