GG: GG::Layout Class Reference

GG

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

List of all members
GG::Layout Class Reference

`#include <Layout.h>`

Inheritance diagram for GG::Layout:

## Structors
| Layout (X x, Y y, X w, Y h, std::size_t rows, std::size_t columns, unsigned int border_margin=0, unsigned int cell_margin=INVALID_CELL_MARGIN)
| Layout ()

## Accessors
virtual Pt | MinUsableSize () const
std::size_t | Rows () const
std::size_t | Columns () const
Flags< Alignment > | ChildAlignment (const Wnd *wnd) const
unsigned int | BorderMargin () const
unsigned int | CellMargin () const
double | RowStretch (std::size_t row) const
double | ColumnStretch (std::size_t column) const
Y | MinimumRowHeight (std::size_t row) const
X | MinimumColumnWidth (std::size_t column) const
std::vector< std::vector < const Wnd * > > | Cells () const
std::vector< std::vector< Rect > > | CellRects () const
std::vector< std::vector< Rect > > | RelativeCellRects () const
bool | RenderOutline () const
Clr | OutlineColor () const

## Mutators
virtual void | StartingChildDragDrop (const Wnd *wnd, const Pt &offset)
virtual void | CancellingChildDragDrop (const std::vector< const Wnd * > &wnds)
virtual void | ChildrenDraggedAway (const std::vector< Wnd * > &wnds, const Wnd *destination)
virtual void | SizeMove (const Pt &ul, const Pt &lr)
virtual void | Render ()
void | Add (Wnd *wnd, std::size_t row, std::size_t column, Flags< Alignment > alignment=ALIGN_NONE)
void | Add (Wnd *wnd, std::size_t row, std::size_t column, std::size_t num_rows, std::size_t num_columns, Flags< Alignment > alignment=ALIGN_NONE)
void | Remove (Wnd *wnd)
void | DetachAndResetChildren ()
void | ResizeLayout (std::size_t rows, std::size_t columns)
void | SetChildAlignment (const Wnd *wnd, Flags< Alignment > alignment)
void | SetBorderMargin (unsigned int margin)
void | SetCellMargin (unsigned int margin)
void | SetRowStretch (std::size_t row, double stretch)
void | SetColumnStretch (std::size_t column, double stretch)
void | SetMinimumRowHeight (std::size_t row, Y height)
void | SetMinimumColumnWidth (std::size_t column, X width)
void | RenderOutline (bool render_outline)
void | SetOutlineColor (Clr color)
virtual void | MouseWheel (const Pt &pt, int move, Flags< ModKey > mod_keys)
virtual void | KeyPress (Key key, boost::uint32_t key_code_point, Flags< ModKey > mod_keys)
virtual void | KeyRelease (Key key, boost::uint32_t key_code_point, Flags< ModKey > mod_keys)

## Exceptions
| GG_ABSTRACT_EXCEPTION (Exception)
| GG_CONCRETE_EXCEPTION (InvalidMargin, GG::Layout, Exception)
| GG_CONCRETE_EXCEPTION (NoSuchChild, GG::Layout, Exception)
| GG_CONCRETE_EXCEPTION (FailedCalculationCheck, GG::Layout, Exception)
| GG_CONCRETE_EXCEPTION (AttemptedOverwrite, GG::Layout, Exception)

## Additional Inherited Members
Public Types inherited from GG::Wnd
enum | ChildClippingMode { DontClip, ClipToClient, ClipToWindow, ClipToClientAndWindowSeparately }
typedef std::map< const Wnd *, bool >::iterator | DropsAcceptableIter
Public Member Functions inherited from GG::Wnd
virtual | ~Wnd ()
bool | Interactive () const
bool | RepeatButtonDown () const
bool | Dragable () const
bool | Resizable () const
bool | OnTop () const
bool | Modal () const
ChildClippingMode | GetChildClippingMode () const
bool | NonClientChild () const
bool | Visible () const
const std::string & | Name () const
const std::string & | DragDropDataType () const
virtual void | DropsAcceptable (DropsAcceptableIter first, DropsAcceptableIter last, const Pt &pt) const
Pt | UpperLeft () const
Pt | LowerRight () const
Pt | RelativeUpperLeft () const
Pt | RelativeLowerRight () const
X | Width () const
Y | Height () const
int | ZOrder () const
Pt | Size () const
Pt | MinSize () const
Pt | MaxSize () const
virtual Pt | ClientUpperLeft () const
virtual Pt | ClientLowerRight () const
Pt | ClientSize () const
X | ClientWidth () const
Y | ClientHeight () const
Pt | ScreenToWindow (const Pt &pt) const
Pt | ScreenToClient (const Pt &pt) const
virtual bool | InWindow (const Pt &pt) const
virtual bool | InClient (const Pt &pt) const
const std::list< Wnd * > & | Children () const
Wnd * | Parent () const
Wnd * | RootParent () const
Layout * | GetLayout () const
Layout * | ContainingLayout () const
const std::vector < BrowseInfoMode > & | BrowseModes () const
const std::string & | BrowseInfoText (std::size_t mode) const
const boost::shared_ptr < StyleFactory > & | GetStyleFactory () const
virtual WndRegion | WindowRegion (const Pt &pt) const
void | SetDragDropDataType (const std::string &data_type)
virtual void | AcceptDrops (const std::vector< Wnd * > &wnds, const Pt &pt)
void | SetName (const std::string &name)
void | Hide (bool children=true)
void | Show (bool children=true)
virtual void | ModalInit ()
void | SetChildClippingMode (ChildClippingMode mode)
void | NonClientChild (bool b)
void | MoveTo (const Pt &pt)
void | OffsetMove (const Pt &pt)
void | Resize (const Pt &sz)
void | SetMinSize (const Pt &sz)
void | SetMaxSize (const Pt &sz)
void | AttachChild (Wnd *wnd)
void | MoveChildUp (Wnd *wnd)
void | MoveChildDown (Wnd *wnd)
void | DetachChild (Wnd *wnd)
void | DetachChildren ()
void | DeleteChild (Wnd *wnd)
void | DeleteChildren ()
void | InstallEventFilter (Wnd *wnd)
void | RemoveEventFilter (Wnd *wnd)
void | HorizontalLayout ()
void | VerticalLayout ()
void | GridLayout ()
void | SetLayout (Layout *layout)
void | RemoveLayout ()
Layout * | DetachLayout ()
void | SetLayoutBorderMargin (unsigned int margin)
void | SetLayoutCellMargin (unsigned int margin)
virtual bool | Run ()
void | EndRun ()
void | SetBrowseModeTime (unsigned int time, std::size_t mode=0)
void | SetBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &wnd, std::size_t mode=0)
void | ClearBrowseInfoWnd (std::size_t mode=0)
void | SetBrowseText (const std::string &text, std::size_t mode=0)
void | SetBrowseModes (const std::vector< BrowseInfoMode > &modes)
void | SetStyleFactory (const boost::shared_ptr< StyleFactory > &factory)
| GG_ABSTRACT_EXCEPTION (Exception)
| GG_CONCRETE_EXCEPTION (BadLayout, GG::Wnd, Exception)
Static Public Member Functions inherited from GG::Wnd
static unsigned int | DefaultBrowseTime ()
static void | SetDefaultBrowseTime (unsigned int time)
static const boost::shared_ptr < BrowseInfoWnd > & | DefaultBrowseInfoWnd ()
static void | SetDefaultBrowseInfoWnd (const boost::shared_ptr< BrowseInfoWnd > &browse_info_wnd)
Protected Types inherited from GG::Wnd
enum | DragDropRenderingState { NOT_DRAGGED, IN_PLACE_COPY, DRAGGED_OVER_UNACCEPTING_DROP_TARGET, DRAGGED_OVER_ACCEPTING_DROP_TARGET }
Protected Member Functions inherited from GG::Wnd
| Wnd ()
| Wnd (X x, Y y, X w, Y h, Flags< WndFlag > flags=INTERACTIVE|DRAGABLE)
DragDropRenderingState | GetDragDropRenderingState () const
virtual void | LButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | LDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void | LButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | LClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | LDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void | MButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | RButtonDown (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | RDrag (const Pt &pt, const Pt &move, Flags< ModKey > mod_keys)
virtual void | RButtonUp (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | RClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | RDoubleClick (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MouseEnter (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MouseHere (const Pt &pt, Flags< ModKey > mod_keys)
virtual void | MouseLeave ()
virtual void | DragDropEnter (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void | DragDropHere (const Pt &pt, const std::map< Wnd *, Pt > &drag_drop_wnds, Flags< ModKey > mod_keys)
virtual void | DragDropLeave ()
virtual void | GainingFocus ()
virtual void | LosingFocus ()
virtual void | TimerFiring (unsigned int ticks, Timer *timer)
virtual bool | EventFilter (Wnd *w, const WndEvent &event)
void | HandleEvent (const WndEvent &event)
void | ForwardEventToParent ()
void | BeginClipping ()
void | EndClipping ()
void | BeginNonclientClipping ()
void | EndNonclientClipping ()
Protected Attributes inherited from GG::Wnd
bool | m_done

## Detailed Description

An invisible Wnd subclass that arranges its child Wnds.

A Layout consists of a grid of cells. A cell may have at most one Wnd covering it, but need not contain a Wnd at all. A Wnd may cover any rectangular region of cells, though they will commonly only cover one. The cells are arranged into rows and columns. Most attributes of the layout are set for an entire row or column, but alignment is set for each child in the layout separately. Rows and columns have two attributes: "stretch", and "min" (minimum row width/minimum column height). Stretch indicates a propotional factor by which each row/column is stretched when the layout is resized. For example, if the sum of the row stretch factors is 5, a row with a stretch of 2 will gain 2/5 of the increased space if the layout grows vertically, or lose 2/5 of the decreased space if the layout shrinks vertically. Note that this means that rows with a stretch of 0 will not change size at all. The exception to this is when all rows have a stretch of 0, in which case all the rows grow and shrink evenly. Obviously, this applies to columns as well. The min sets a lower bound on the height of a row or the width of a column. By default, no alignment value is set for a child in the layout. If one is set, the child is not grown and shrunk when the layout is resized, if this is possible. Aligned children just sit there in the place they are aligned to. If the layout becomes too small, aligned windows will be shrunk as necessary and if possible. Note that the MinSize() and MaxSize() of a child will affect how much it can be stretched when the layout is resized.

Layouts are best used to arrange the children of another window, such as arranging the controls of a dialog box. When used this way, the Layout becomes the sole child of its parent, and contains the parent's children as its own. This scheme allows Layouts to be easily nested, since all Layouts are Wnd-derived. Like a Control, a Layout will forward all MouseWheel(), Key*(), and dragged-child notification calls to its parent. Clicks fall through as well, since Layouts are not constructed with the Wnd::INTERACTIVE flag.

There are two attributes that affect the spacing of all the layout's child windows: border margin and cell margin. Border margin is the space left around the entire layout, between the outer edges of the children in the layout and the layout's outer edges. Cell margin is the space left between individual Wnds in the layout, but does not add to the margin around the outside of the layout.

A note about how layout minimum sizes are determined:
The border margin adds to the minimum size of the layout. Further, the cell margin will have an effect on the minimum size of a cell, even an empty one, if it is greater than the row or column minimum for that cell. So an empty layout with 5 columns, a border margin of 3, and a cell margin of 2 will have a minumum width of 14. This is determined as follows: 5 columns means 4 cell margins between the columns, so 4 * 2 = 8. The border margin is added to both sides, which means the total minimum width is 8 + 2 * 3 =

1. Also, the minimum size of each child in the layout will affect the minimum sizes of the rows and columns it covers. If a child covers more than one row/column, its minimum size is distributed over the rows/columns it covers, proportional to the stretch factor for each row/column. Finally, the min values and stretch factors must both be satisfied simultaneously. For example, if the row mins are set to be [1 2 3] and the row stretch factors are set to be [1 2 3], the minimum width will be 6 (neglecting the margins). However, if the mins were instead set to be [4 2 3], the stretch factors would lead to effective minimums of [4 8 12] to maintain proportionality, making the minimum width 24.

See Also
  The Wnd documentation has further information about layouts attached to Wnds.

Definition at line 103 of file Layout.h.

## Constructor & Destructor Documentation

GG::Layout::Layout | ( | X | x,
|  | Y | y,
|  | X | w,
|  | Y | h,
|  | std::size_t | rows,
|  | std::size_t | columns,
|  | unsigned int | border_margin = `0`,
|  | unsigned int | cell_margin = `INVALID_CELL_MARGIN`
| ) |  |

Ctor.

## Member Function Documentation

virtual Pt GG::Layout::MinUsableSize | ( |  | ) | const
| virtual

Returns the size of the minimum bounding box that can enclose the Wnd and still show all of its elements, plus enough room for interaction with those elements (if applicable). For example, a TextControl's MinUsableSize() is just the area of its text, and a Scroll's MinUsableSize() is the combined sizes of its up-button, down-button, and tab (plus a bit of room in which to drag the tab).

Reimplemented from GG::Wnd.

Flags<Alignment> GG::Layout::ChildAlignment | ( | const Wnd * | wnd | ) | const

returns the aligment of child wnd.

Exceptions

  GG::Layout::NoSuchChild | Throws if no such child exists.

bool GG::Layout::RenderOutline | ( |  | ) | const

Returns true iff this layout will render an outline of itself; this is sometimes useful for debugging purposes

Clr GG::Layout::OutlineColor | ( |  | ) | const

Returns the outline color used to render this layout (this is only used if RenderOutline() returns true). This is sometimes useful for debugging purposes.

virtual void GG::Layout::StartingChildDragDrop | ( | const Wnd * | wnd,
|  | const Pt & | offset
| ) |  |
| virtual

Indicates to the Wnd that a child Wnd wnd is being dragged in a drag-and-drop operation, which gives it the opportunity to add other associated drag-and-drop Wnds (see GUI::RegisterDragDropWnd()). offset indicates the position of the mouse relative to wnd's UpperLeft().

Reimplemented from GG::Wnd.

virtual void GG::Layout::CancellingChildDragDrop | ( | const std::vector< const Wnd * > & | wnds | ) |
| virtual

Handles the cancellation of the dragging of one or more child windows, whose dragging was established by the most recent call to StartingChildDragDrop(). Note that even if an accepting Wnd accepts some but not all Wnds via DropsAcceptable(), this function will be called on those Wnds not accepted.

Note
  CancellingChildDragDrop() and ChildrenDraggedAway() are always called in that order, and are always called at the end of any drag-and-drop sequence performed on a child of this Wnd, whether the drag-and-drop is successful or not.

Reimplemented from GG::Wnd.

virtual void GG::Layout::ChildrenDraggedAway | ( | const std::vector< Wnd * > & | wnds,
|  | const Wnd * | destination
| ) |  |
| virtual

Handles the removal of one or more child windows that have been dropped onto another window which has accepted them as drops via DropsAcceptable(). The accepting window retains ownership, so this function must not delete the children.

Note
  CancellingChildDragDrop() and ChildrenDraggedAway() are always called in that order, and are always called at the end of any drag-and-drop sequence performed on a child of this Wnd, whether the drag-and-drop is successful or not.

Reimplemented from GG::Wnd.

virtual void GG::Layout::SizeMove | ( | const Pt & | ul,
|  | const Pt & | lr
| ) |  |
| virtual

Resizes and/or moves window to new upper-left and lower right boundaries.

Reimplemented from GG::Wnd.

virtual void GG::Layout::Render | ( |  | ) |
| virtual

Draws this Wnd. Note that Wnds being dragged for a drag-and-drop operation are rendered twice – once in-place as normal, once in the location of the drag operation, attached to the cursor. Such Wnds may wish to render themselves differently in those two cases. To determine which render is being performed, they can call GUI::GetGUI()->RenderingDragDropWnds().

Reimplemented from GG::Wnd.

void GG::Layout::Add | ( | Wnd * | wnd,
|  | std::size_t | row,
|  | std::size_t | column,
|  | Flags< Alignment > | alignment = `ALIGN_NONE`
| ) |  |

Inserts w into the layout in the indicated cell, expanding the layout grid as necessary.

Exceptions

  GG::Layout::AttemptedOverwrite | Throws if there is already a Wnd in the given cell.

void GG::Layout::Add | ( | Wnd * | wnd,
|  | std::size_t | row,
|  | std::size_t | column,
|  | std::size_t | num_rows,
|  | std::size_t | num_columns,
|  | Flags< Alignment > | alignment = `ALIGN_NONE`
| ) |  |

Inserts w into the layout, covering the indicated cell(s), expanding the layout grid as necessary. The num_rows and num_columns indicate how many rows and columns w covers, respectively. So Add(foo, 1, 2, 2, 3) covers cells (1, 2) through (2, 4), inclusive. Note that num_rows and num_columns must be positive, though this is not checked.

Exceptions

  GG::Layout::AttemptedOverwrite | Throws if there is already a Wnd in one of the given cells.

void GG::Layout::Remove | ( | Wnd * | wnd | ) |

Removes w from the layout, recalculating the layout as needed. Note that this causes the layout to relinquish responsibility for wnd's memory management.

void GG::Layout::DetachAndResetChildren | ( |  | ) |

Resets children to their original sizes and detaches them, so that a removed Layout can leave the Wnds it lays out in their original configuration when it is no longer useful.

void GG::Layout::ResizeLayout | ( | std::size_t | rows,
|  | std::size_t | columns
| ) |  |

Resizes the layout to be rows by columns. If the layout shrinks, any contained windows are deleted. Each of rows and columns must be greater than 0, though this is not checked.

void GG::Layout::SetChildAlignment | ( | const Wnd * | wnd,
|  | Flags< Alignment > | alignment
| ) |  |

Sets the aligment of child wnd to alignment. If no such child exists, no action is taken.

void GG::Layout::SetBorderMargin | ( | unsigned int | margin | ) |

Sets the number of pixels that the layout will leave between its edges and the windows it contains

void GG::Layout::SetCellMargin | ( | unsigned int | margin | ) |

Sets the number of pixels the layout leaves between the edges of windows in adjacent cells

void GG::Layout::SetRowStretch | ( | std::size_t | row,
|  | double | stretch
| ) |  |

Sets the amount of stretching, relative to other rows, that row will do when the layout is resized. 0.0 indicates that the row's size will not change unless all rows have 0.0 stretch as well. Note that row is not range-checked.

void GG::Layout::SetColumnStretch | ( | std::size_t | column,
|  | double | stretch
| ) |  |

Sets the amount of stretching, relative to other columns, that column will do when the layout is resized. 0.0 indicates that the column's size will not change unless all columns have 0.0 stretch as well. Note that column is not range-checked.

void GG::Layout::SetMinimumRowHeight | ( | std::size_t | row,
|  | Y | height
| ) |  |

Sets the minimum height of row row to height. Note that row is not range-checked.

void GG::Layout::SetMinimumColumnWidth | ( | std::size_t | column,
|  | X | width
| ) |  |

Sets the minimum width of column column to width. Note that column is not range-checked.

void GG::Layout::RenderOutline | ( | bool | render_outline | ) |

Set this to true if this layout should render an outline of itself; this is sometimes useful for debugging purposes

void GG::Layout::SetOutlineColor | ( | Clr | color | ) |

Sets the outline color used to render this layout (this is only used if RenderOutline() returns true). This is sometimes useful for debugging purposes.

GG::Layout::GG_ABSTRACT_EXCEPTION | ( | Exception |  | ) |

The base class for Layout exceptions.

GG::Layout::GG_CONCRETE_EXCEPTION | ( | InvalidMargin | ,
|  | GG::Layout | ,
|  | Exception |
| ) |  |

Thrown when a negative margin is provided.

GG::Layout::GG_CONCRETE_EXCEPTION | ( | NoSuchChild | ,
|  | GG::Layout | ,
|  | Exception |
| ) |  |

Thrown when a property of a nonexistent child is requested.

GG::Layout::GG_CONCRETE_EXCEPTION | ( | FailedCalculationCheck | ,
|  | GG::Layout | ,
|  | Exception |
| ) |  |

Thrown when an internal check of calculations made by the layout algorithm fails.

GG::Layout::GG_CONCRETE_EXCEPTION | ( | AttemptedOverwrite | ,
|  | GG::Layout | ,
|  | Exception |
| ) |  |

Thrown when an attempt is made to place a Wnd in a nonempty layout cell.

virtual void GG::Layout::MouseWheel | ( | const Pt & | pt,
|  | int | move,
|  | Flags< ModKey > | mod_keys
| ) |  |
| protectedvirtual

Respond to movement of the mouse wheel (move > 0 indicates the wheel is rolled up, < 0 indicates down)

Reimplemented from GG::Wnd.

virtual void GG::Layout::KeyPress | ( | Key | key,
|  | boost::uint32_t | key_code_point,
|  | Flags< ModKey > | mod_keys
| ) |  |
| protectedvirtual

Respond to down-keystrokes (focus window only). A window may receive KeyPress() messages passed up to it from its children. For instance, Control-derived classes pass KeyPress() messages to their Parent() windows by default.

Note
  Though mouse clicks consist of a press and a release, all Control classes by default respond immediately to KeyPress(), not KeyRelease(); in fact, by default no Wnd class does anything at all on a KeyRelease event.
  key_code_point will be zero if Unicode support is unavailable.

Reimplemented from GG::Wnd.

virtual void GG::Layout::KeyRelease | ( | Key | key,
|  | boost::uint32_t | key_code_point,
|  | Flags< ModKey > | mod_keys
| ) |  |
| protectedvirtual

Respond to up-keystrokes (focus window only). A window may receive KeyRelease() messages passed up to it from its children. For instance, Control-derived classes pass KeyRelease() messages to their Parent() windows by default.

Note
  key_code_point will be zero if Unicode support is unavailable.

Reimplemented from GG::Wnd.

The documentation for this class was generated from the following file:

- Layout.h