interface/wx/laywin.h

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