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