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