interface revisions

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56490 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/laywin.h

@@ -6,90 +6,107 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Enumeration used by wxLayoutAlgorithm.
+*/
+enum wxLayoutOrientation
+{
+    wxLAYOUT_HORIZONTAL,
+    wxLAYOUT_VERTICAL
+};
+
+/**
+    Enumeration used by wxLayoutAlgorithm.
+*/
+enum wxLayoutAlignment
+{
+    wxLAYOUT_NONE,
+    wxLAYOUT_TOP,
+    wxLAYOUT_LEFT,
+    wxLAYOUT_RIGHT,
+    wxLAYOUT_BOTTOM
+};
+
 /**
     @class wxLayoutAlgorithm
 
     wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames.
-    It sends a wxCalculateLayoutEvent event
+    It sends a wxCalculateLayoutEvent event to children of the frame, asking them
-    to children of the frame, asking them for information about
+    for information about their size. For MDI parent frames, the algorithm allocates
-    their size. For MDI parent frames, the algorithm allocates
+    the remaining space to the MDI client window (which contains the MDI child frames).
-    the remaining space to the MDI client window (which contains the MDI child
+
-    frames).
     For SDI (normal) frames, a 'main' window is specified as taking up the
     remaining space.
 
     Because the event system is used, this technique can be applied to any windows,
     which are not necessarily 'aware' of the layout classes (no virtual functions
-    in wxWindow refer to wxLayoutAlgorithm or its events). However, you
+    in wxWindow refer to wxLayoutAlgorithm or its events).
-    may wish to use wxSashLayoutWindow for your subwindows
+    However, you may wish to use wxSashLayoutWindow for your subwindows since this
-    since this class provides handlers for the required events, and accessors
+    class provides handlers for the required events, and accessors to specify the
-    to specify the desired size of the window. The sash behaviour in the base class
+    desired size of the window. The sash behaviour in the base class can be used,
-    can be used, optionally, to make the windows user-resizable.
+    optionally, to make the windows user-resizable.
 
     wxLayoutAlgorithm is typically used in IDE (integrated development environment)
-    applications,
+    applications, where there are several resizable windows in addition to the MDI
-    where there are several resizable windows in addition to the MDI client window,
+    client window, or other primary editing window. Resizable windows might include
-    or
+    toolbars, a project window, and a window for displaying error and warning messages.
-    other primary editing window. Resizable windows might include toolbars, a
-    project
-    window, and a window for displaying error and warning messages.
 
     When a window receives an OnCalculateLayout event, it should call SetRect in
     the given event object, to be the old supplied rectangle minus whatever space
-    the
+    the window takes up. It should also set its own size accordingly.
-    window takes up. It should also set its own size accordingly.
     wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event
     which it sends to itself to determine the orientation, alignment and size of
-    the window,
+    the window, which it gets from internal member variables set by the application.
-    which it gets from internal member variables set by the application.
 
     The algorithm works by starting off with a rectangle equal to the whole frame
-    client area.
+    client area. It iterates through the frame children, generating
-    It iterates through the frame children, generating OnCalculateLayout events
+    wxLayoutAlgorithm::OnCalculateLayout events which subtract the window size and
-    which subtract
+    return the remaining rectangle for the next window to process.
-    the window size and return the remaining rectangle for the next window to
+    It is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches
-    process. It
+    the full dimension of the frame client, according to the orientation it specifies.
-    is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches
+    For example, a horizontal window will stretch the full width of the remaining
-    the full dimension
+    portion of the frame client area.
-    of the frame client, according to the orientation it specifies. For example, a
-    horizontal window
-    will stretch the full width of the remaining portion of the frame client area.
     In the other orientation, the window will be fixed to whatever size was
-    specified by
+    specified by wxLayoutAlgorithm::OnQueryLayoutInfo. An alignment setting will
-    OnQueryLayoutInfo. An alignment setting will make the window 'stick' to the
+    make the window 'stick' to the left, top, right or bottom of the remaining
-    left, top, right or
+    client area. This scheme implies that order of window creation is important.
-    bottom of the remaining client area. This scheme implies that order of window
-    creation is important.
     Say you wish to have an extra toolbar at the top of the frame, a project window
-    to the left of
+    to the left of the MDI client window, and an output window above the status bar.
-    the MDI client window, and an output window above the status bar. You should
+    You should therefore create the windows in this order: toolbar, output window,
-    therefore create
+    project window. This ensures that the toolbar and output window take up space
-    the windows in this order: toolbar, output window, project window. This ensures
+    at the top and bottom, and then the remaining height in-between is used for
-    that the toolbar and
-    output window take up space at the top and bottom, and then the remaining
-    height in-between is used for
     the project window.
 
     wxLayoutAlgorithm is quite independent of the way in which
-    OnCalculateLayout chooses to interpret a window's size and alignment. Therefore
+    wxLayoutAlgorithm::OnCalculateLayout chooses to interpret a window's size and
-    you
+    alignment. Therefore you could implement a different window class with a new
-    could implement a different window class with a new OnCalculateLayout event
+    wxLayoutAlgorithm::OnCalculateLayout event handler, that has a more sophisticated
-    handler,
+    way of laying out the windows. It might allow specification of whether stretching
-    that has a more sophisticated way of laying out the windows. It might allow
+    occurs in the specified orientation, for example, rather than always assuming
-    specification of whether stretching occurs in the specified orientation, for
+    stretching.
-    example,
+    (This could, and probably should, be added to the existing implementation).
-    rather than always assuming stretching. (This could, and probably should, be
+
-    added to the existing
+    @note wxLayoutAlgorithm has nothing to do with wxLayoutConstraints.
-    implementation).
+          It is an alternative way of specifying layouts for which the normal
+          constraint system is unsuitable.
+
+    @beginEventTable{wxQueryLayoutInfoEvent,wxCalculateLayoutEvent}
+    @event{EVT_QUERY_LAYOUT_INFO(func)}
+        Process a wxEVT_QUERY_LAYOUT_INFO event, to get size, orientation and
+        alignment from a window. See wxQueryLayoutInfoEvent.
+    @event{EVT_CALCULATE_LAYOUT(func)}
+        Process a wxEVT_CALCULATE_LAYOUT event, which asks the window to take a
+        'bite' out of a rectangle provided by the algorithm. See wxCalculateLayoutEvent.
+    @endEventTable
+
+    Note that the algorithm object does not respond to events, but itself generates the
+    previous events in order to calculate window sizes.
 
-    @e Note: wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an
-    alternative
-    way of specifying layouts for which the normal constraint system is unsuitable.
 
     @library{wxadv}
     @category{winlayout}
 
-    @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview
+    @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandling
 */
 class wxLayoutAlgorithm : public wxObject
 {
@@ -106,28 +123,24 @@ public:
 
     /**
         Lays out the children of a normal frame. @a mainWindow is set to occupy the
-        remaining space.
+        remaining space. This function simply calls LayoutWindow().
-        This function simply calls LayoutWindow().
     */
     bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL);
 
     /**
         Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the
         given rectangle will be used as a starting point instead of the frame's client
-        area.
+        area. The MDI client window is set to occupy the remaining space.
-        The MDI client window is set to occupy the remaining space.
     */
     bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL);
 
     /**
         Lays out the children of a normal frame or other window.
+
         @a mainWindow is set to occupy the remaining space. If this is not specified,
-        then
+        then the last window that responds to a calculate layout event in query mode will
-        the last window that responds to a calculate layout event in query mode will
+        get the remaining space (that is, a non-query OnCalculateLayout event will
-        get the remaining space
+        not be sent to this window and the window will be set to the remaining size).
-        (that is, a non-query OnCalculateLayout event will not be sent to this window
-        and the window will be set
-        to the remaining size).
     */
     bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL);
 };
@@ -137,25 +150,35 @@ public:
 /**
     @class wxSashLayoutWindow
 
-    wxSashLayoutWindow responds to OnCalculateLayout events generated
+    wxSashLayoutWindow responds to OnCalculateLayout events generated by wxLayoutAlgorithm.
-    by wxLayoutAlgorithm. It allows the
+    It allows the  application to use simple accessors to specify how the window
-    application to use simple accessors to specify how the window should be
+    should be laid out, rather than having to respond to events.
-    laid out, rather than having to respond to events. The fact that
-    the class derives from wxSashWindow allows sashes to be used if required,
-    to allow the windows to be user-resizable.
 
-    The documentation for wxLayoutAlgorithm explains
+    The fact that the class derives from wxSashWindow allows sashes to be used if
-    the purpose of this class in more detail.
+    required, to allow the windows to be user-resizable.
+
+    The documentation for wxLayoutAlgorithm explains the purpose of this class in
+    more detail.
+
+    For the window styles see wxSashWindow.
+
+    This class handles the EVT_QUERY_LAYOUT_INFO and EVT_CALCULATE_LAYOUT events
+    for you. However, if you use sashes, see wxSashWindow for relevant event information.
+    See also wxLayoutAlgorithm for information about the layout events.
 
     @library{wxadv}
     @category{miscwnd}
 
-    @see wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview
+    @see wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandling
 */
 class wxSashLayoutWindow : public wxSashWindow
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxSashLayoutWindow();
+
     /**
         Constructs a sash layout window, which can be a child of a frame, dialog or any
         other non-control window.
@@ -166,26 +189,21 @@ public:
             Window identifier. If -1, will automatically create an identifier.
         @param pos
             Window position. wxDefaultPosition is (-1, -1) which indicates that
-        wxSashLayoutWindows
+            wxSashLayoutWindows should generate a default position for the window.
-            should generate a default position for the window. If using the
+            If using the wxSashLayoutWindow class directly, supply an actual position.
-        wxSashLayoutWindow class directly, supply
-            an actual position.
         @param size
             Window size. wxDefaultSize is (-1, -1) which indicates that
-        wxSashLayoutWindows
+            wxSashLayoutWindows should generate a default size for the window.
-            should generate a default size for the window.
         @param style
             Window style. For window styles, please see wxSashLayoutWindow.
         @param name
             Window name.
     */
-    wxSashLayoutWindow();
     wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id,
                        const wxPoint& pos = wxDefaultPosition,
                        const wxSize& size = wxDefaultSize,
                        long style = wxCLIP_CHILDREN | wxSW_3D,
                        const wxString& name = "layoutWindow");
-    //@}
 
     /**
         Initializes a sash layout window, which can be a child of a frame, dialog or
@@ -197,14 +215,11 @@ public:
             Window identifier. If -1, will automatically create an identifier.
         @param pos
             Window position. wxDefaultPosition is (-1, -1) which indicates that
-        wxSashLayoutWindows
+            wxSashLayoutWindows should generate a default position for the window.
-            should generate a default position for the window. If using the
+            If using the wxSashLayoutWindow class directly, supply an actual position.
-        wxSashLayoutWindow class directly, supply
-            an actual position.
         @param size
             Window size. wxDefaultSize is (-1, -1) which indicates that
-        wxSashLayoutWindows
+            wxSashLayoutWindows should generate a default size for the window.
-            should generate a default size for the window.
         @param style
             Window style. For window styles, please see wxSashLayoutWindow.
         @param name
@@ -229,45 +244,41 @@ public:
     wxLayoutOrientation GetOrientation() const;
 
     /**
-        The default handler for the event that is generated by wxLayoutAlgorithm. The
+        The default handler for the event that is generated by wxLayoutAlgorithm.
-        implementation
+        The implementation of this function calls wxCalculateLayoutEvent::SetRect
-        of this function calls wxCalculateLayoutEvent::SetRect to shrink the provided
+        to shrink the provided size according to how much space this window takes up.
-        size according to
+        For further details, see wxLayoutAlgorithm and wxCalculateLayoutEvent.
-        how much space this window takes up. For further details,
-        see wxLayoutAlgorithm and wxCalculateLayoutEvent.
     */
     void OnCalculateLayout(wxCalculateLayoutEvent& event);
 
     /**
         The default handler for the event that is generated by OnCalculateLayout to get
-        size, alignment and orientation information for the window. The implementation
+        size, alignment and orientation information for the window.
-        of this function uses member variables as set by accessors called by the
+        The implementation of this function uses member variables as set by accessors
-        application.
+        called by the application.
+
         For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent.
     */
     void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event);
 
     /**
         Sets the alignment of the window (which edge of the available parent client
-        area the window
+        area the window is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
-        is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
         wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
     */
     void SetAlignment(wxLayoutAlignment alignment);
 
     /**
         Sets the default dimensions of the window. The dimension other than the
-        orientation will be fixed to this
+        orientation will be fixed to this value, and the orientation dimension
-        value, and the orientation dimension will be ignored and the window stretched
+        will be ignored and the window stretched to fit the available space.
-        to fit the available space.
     */
     void SetDefaultSize(const wxSize& size);
 
     /**
         Sets the orientation of the window (the direction the window will stretch in,
-        to fill the available
+        to fill the available parent client area). @a orientation is one of
-        parent client area). @a orientation is one of wxLAYOUT_HORIZONTAL,
+        wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
-        wxLAYOUT_VERTICAL.
     */
     void SetOrientation(wxLayoutOrientation orientation);
 };
@@ -277,10 +288,15 @@ public:
 /**
     @class wxQueryLayoutInfoEvent
 
-    This event is sent when wxLayoutAlgorithm wishes to get
+    This event is sent when wxLayoutAlgorithm wishes to get the size, orientation
-    the size, orientation and alignment of a window. More precisely, the event is
+    and alignment of a window. More precisely, the event is sent by the
-    sent
+    OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm.
-    by the OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm.
+
+    @beginEventTable{wxQueryLayoutInfoEvent}
+    @event{EVT_QUERY_LAYOUT_INFO(func)}
+        Process a wxEVT_QUERY_LAYOUT_INFO event, to get size, orientation and alignment
+        from a window.
+    @endEventTable
 
     @library{wxadv}
     @category{events}
@@ -297,9 +313,8 @@ public:
 
     /**
         Specifies the alignment of the window (which side of the remaining parent
-        client area
+        client area the window sticks to).
-        the window sticks to). One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT,
+        One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
-        wxLAYOUT_BOTTOM.
     */
     void GetAlignment() const;
 
@@ -310,15 +325,13 @@ public:
 
     /**
         Returns the orientation that the event handler specified to the event object.
-        May be one of wxLAYOUT_HORIZONTAL,
+        May be one of wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
-        wxLAYOUT_VERTICAL.
     */
     wxLayoutOrientation GetOrientation() const;
 
     /**
         Returns the requested length of the window in the direction of the window
-        orientation. This information
+        orientation. This information is not yet used.
-        is not yet used.
     */
     int GetRequestedLength() const;
 
@@ -330,9 +343,8 @@ public:
 
     /**
         Call this to specify the alignment of the window (which side of the remaining
-        parent client area
+        parent client area the window sticks to).
-        the window sticks to). May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT,
+        May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
-        wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM.
     */
     void SetAlignment(wxLayoutAlignment alignment);
 
@@ -342,16 +354,14 @@ public:
     void SetFlags(int flags);
 
     /**
-        Call this to specify the orientation of the window. May be one of
+        Call this to specify the orientation of the window.
-        wxLAYOUT_HORIZONTAL,
+        May be one of wxLAYOUT_HORIZONTAL, wxLAYOUT_VERTICAL.
-        wxLAYOUT_VERTICAL.
     */
     void SetOrientation(wxLayoutOrientation orientation);
 
     /**
         Sets the requested length of the window in the direction of the window
-        orientation. This information
+        orientation. This information is not yet used.
-        is not yet used.
     */
     void SetRequestedLength(int length);
 
@@ -366,9 +376,14 @@ public:
 /**
     @class wxCalculateLayoutEvent
 
-    This event is sent by wxLayoutAlgorithm to
+    This event is sent by wxLayoutAlgorithm to calculate the amount of the
-    calculate the amount of the remaining client area that the window should
+    remaining client area that the window should occupy.
-    occupy.
+
+    @beginEventTable{wxCalculateLayoutEvent}
+    @event{EVT_CALCULATE_LAYOUT(func)}
+        Process a wxEVT_CALCULATE_LAYOUT event, which asks the window to take a
+        'bite' out of a rectangle provided by the algorithm.
+    @endEventTable
 
     @library{wxadv}
     @category{events}
@@ -390,10 +405,11 @@ public:
 
     /**
         Before the event handler is entered, returns the remaining parent client area
-        that the window
+        that the window could occupy.
-        could occupy. When the event handler returns, this should contain the remaining
+
-        parent client rectangle,
+        When the event handler returns, this should contain the remaining parent
-        after the event handler has subtracted the area that its window occupies.
+        client rectangle, after the event handler has subtracted the area that its
+        window occupies.
     */
     wxRect GetRect() const;
 
@@ -404,8 +420,7 @@ public:
 
     /**
         Call this to specify the new remaining parent client area, after the space
-        occupied by the
+        occupied by the window has been subtracted.
-        window has been subtracted.
     */
     void SetRect(const wxRect& rect);
 };