docs/latex/wx/layalgor.tex

   1 \section{\class{wxLayoutAlgorithm}}\label{wxlayoutalgorithm}
   2
   3 wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames.
   4 It sends a wxCalculateLayoutEvent event
   5 to children of the frame, asking them for information about
   6 their size. For MDI parent frames, the algorithm allocates
   7 the remaining space to the MDI client window (which contains the MDI child frames).
   8 For SDI (normal) frames, a 'main' window is specified as taking up the
   9 remaining space.
  10
  11 Because the event system is used, this technique can be applied to any windows,
  12 which are not necessarily 'aware' of the layout classes (no virtual functions
  13 in wxWindow refer to wxLayoutAlgorithm or its events). However, you
  14 may wish to use \helpref{wxSashLayoutWindow}{wxsashlayoutwindow} for your subwindows
  15 since this class provides handlers for the required events, and accessors
  16 to specify the desired size of the window. The sash behaviour in the base class
  17 can be used, optionally, to make the windows user-resizable.
  18
  19 wxLayoutAlgorithm is typically used in IDE (integrated development environment) applications,
  20 where there are several resizable windows in addition to the MDI client window, or
  21 other primary editing window. Resizable windows might include toolbars, a project
  22 window, and a window for displaying error and warning messages.
  23
  24 When a window receives an OnCalculateLayout event, it should call SetRect in
  25 the given event object, to be the old supplied rectangle minus whatever space the
  26 window takes up. It should also set its own size accordingly.
  27 wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event
  28 which it sends to itself to determine the orientation, alignment and size of the window,
  29 which it gets from internal member variables set by the application.
  30
  31 The algorithm works by starting off with a rectangle equal to the whole frame client area.
  32 It iterates through the frame children, generating OnCalculateLayout events which subtract
  33 the window size and return the remaining rectangle for the next window to process. It
  34 is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches the full dimension
  35 of the frame client, according to the orientation it specifies. For example, a horizontal window
  36 will stretch the full width of the remaining portion of the frame client area.
  37 In the other orientation, the window will be fixed to whatever size was specified by
  38 OnQueryLayoutInfo. An alignment setting will make the window 'stick' to the left, top, right or
  39 bottom of the remaining client area. This scheme implies that order of window creation is important.
  40 Say you wish to have an extra toolbar at the top of the frame, a project window to the left of
  41 the MDI client window, and an output window above the status bar. You should therefore create
  42 the windows in this order: toolbar, output window, project window. This ensures that the toolbar and
  43 output window take up space at the top and bottom, and then the remaining height inbetween is used for
  44 the project window.
  45
  46 wxLayoutAlgorithm is quite independent of the way in which
  47 OnCalculateLayout chooses to interpret a window's size and alignment. Therefore you
  48 could implement a different window class with a new OnCalculateLayout event handler,
  49 that has a more sophisticated way of laying out the windows. It might allow
  50 specification of whether stretching occurs in the specified orientation, for example,
  51 rather than always assuming stretching. (This could, and probably should, be added to the existing
  52 implementation).
  53
  54 {\it Note:} wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an alternative
  55 way of specifying layouts for which the normal constraint system is unsuitable.
  56
  57 \wxheading{Derived from}
  58
  59 \helpref{wxObject}{wxobject}
  60
  61 \wxheading{Event handling}
  62
  63 The algorithm object does not respond to events, but itself generates the
  64 following events in order to calculate window sizes.
  65
  66 \twocolwidtha{7cm}%
  67 \begin{twocollist}\itemsep=0pt
  68 \twocolitem{{\bf EVT\_QUERY\_LAYOUT\_INFO(func)}}{Process a wxEVT\_QUERY\_LAYOUT\_INFO event,
  69 to get size, orientation and alignment from a window. See \helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}.}
  70 \twocolitem{{\bf EVT\_CALCULATE\_LAYOUT(func)}}{Process a wxEVT\_CALCULATE\_LAYOUT event,
  71 which asks the window to take a 'bite' out of a rectangle provided by the algorithm.
  72 See \helpref{wxCalculateLayoutEvent}{wxcalculatelayoutevent}.}
  73 \end{twocollist}
  74
  75 \wxheading{Data types}
  76
  77 {\small
  78 \begin{verbatim}
  79 enum wxLayoutOrientation {
  80     wxLAYOUT_HORIZONTAL,
  81     wxLAYOUT_VERTICAL
  82 };
  83
  84 enum wxLayoutAlignment {
  85     wxLAYOUT_NONE,
  86     wxLAYOUT_TOP,
  87     wxLAYOUT_LEFT,
  88     wxLAYOUT_RIGHT,
  89     wxLAYOUT_BOTTOM,
  90 };
  91 \end{verbatim}
  92 }
  93
  94 \wxheading{See also}
  95
  96 \helpref{wxSashEvent}{wxsashevent}, \helpref{wxSashLayoutWindow}{wxsashlayoutwindow}, \helpref{Event handling overview}{eventhandlingoverview}
  97
  98 \helpref{wxCalculateLayoutEvent}{wxcalculatelayoutevent},\rtfsp
  99 \helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent},\rtfsp
 100 \helpref{wxSashLayoutWindow}{wxsashlayoutwindow},\rtfsp
 101 \helpref{wxSashWindow}{wxsashwindow}
 102
 103 \latexignore{\rtfignore{\wxheading{Members}}}
 104
 105 \membersection{wxLayoutAlgorithm::wxLayoutAlgorithm}
 106
 107 \func{}{wxLayoutAlgorithm}{\void}
 108
 109 Default constructor.
 110
 111 \membersection{wxLayoutAlgorithm::\destruct{wxLayoutAlgorithm}}
 112
 113 \func{}{\destruct{wxLayoutAlgorithm}}{\void}
 114
 115 Destructor.
 116
 117 \membersection{wxLayoutAlgorithm::LayoutFrame}\label{wxlayoutalgorithmlayoutframe}
 118
 119 \constfunc{bool}{LayoutFrame}{\param{wxFrame* }{frame}, \param{wxWindow*}{ mainWindow = NULL}}
 120
 121 Lays out the children of a normal frame. {\it mainWindow} is set to occupy the remaining space.
 122
 123 This function simply calls \helpref{wxLayoutAlgorithm::LayoutWindow}{wxlayoutalgorithmlayoutwindow}.
 124
 125 \membersection{wxLayoutAlgorithm::LayoutMDIFrame}\label{wxlayoutalgorithmlayoutmdiframe}
 126
 127 \constfunc{bool}{LayoutMDIFrame}{\param{wxMDIParentFrame* }{frame}, \param{wxRect*}{ rect = NULL}}
 128
 129 Lays out the children of an MDI parent frame. If {\it rect} is non-NULL, the
 130 given rectangle will be used as a starting point instead of the frame's client area.
 131
 132 The MDI client window is set to occupy the remaining space.
 133
 134 \membersection{wxLayoutAlgorithm::LayoutWindow}\label{wxlayoutalgorithmlayoutwindow}
 135
 136 \constfunc{bool}{LayoutWindow}{\param{wxWindow* }{parent}, \param{wxWindow*}{ mainWindow = NULL}}
 137
 138 Lays out the children of a normal frame or other window.
 139
 140 {\it mainWindow} is set to occupy the remaining space.
 141