GG: GG::Layout Class Reference

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::CLICKABLE 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 = 14. 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.

Constructor & Destructor Documentation

GG::Layout::Layout	(	int	x,
		int	y,
		int	w,
		int	h,
		int	rows,
		int	columns,
		int	border_margin = `0`,
		int	cell_margin = `-1`
	)

ctor.

Exceptions:

GG::Layout::InvalidMargin

Throws if border_margin is negative.

GG::Layout::Layout ( ) [protected]

default 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 RenderableMinSize() 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.

int GG::Layout::Rows ( ) const

returns the number of rows in the layout

int GG::Layout::Columns ( ) const

returns the number of columns in the layout

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

returns the aligment of child wnd.

Exceptions:

GG::Layout::NoSuchChild

Throws if no such child exists.

int GG::Layout::BorderMargin ( ) const

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

int GG::Layout::CellMargin ( ) const

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

double GG::Layout::RowStretch ( int row ) const

returns the stretch factor for row row. Note that row is not range-checked.

double GG::Layout::ColumnStretch ( int column ) const

returns the stretch factor for column column. Note that column is not range-checked.

int GG::Layout::MinimumRowHeight ( int row ) const

returns the minimum height allowed for row row. Note that row is not range-checked.

int GG::Layout::MinimumColumnWidth ( int column ) const

returns the minimum height allowed for column column. Note that column is not range-checked.

std::vector<std::vector<const Wnd*> > GG::Layout::Cells ( ) const

returns a matrix of the Wnds that can be found in each cell

std::vector<std::vector<Rect> > GG::Layout::CellRects ( ) const

returns a matrix of rectangles in screen space that cover the cells in which child Wnds are placed

std::vector<std::vector<Rect> > GG::Layout::RelativeCellRects ( ) const

returns a matrix of rectangles in layout client space that cover the cells in which child Wnds are placed

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::list< 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 Accept()s some but not all Wnds, this function will be called on those Wnds not accepted. Note that 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::list< 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.

The accepting window retains ownership, so this function must not delete the children. Note that 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.

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

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,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

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.

Reimplemented from GG::Wnd.

virtual void GG::Layout::KeyRelease	(	Key	key,
		Flags< ModKey >	mod_keys
	)			`[virtual]`

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.

Reimplemented from GG::Wnd.

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

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

Note that row and column must not be negative, though this is not checked.

Exceptions:

GG::Layout::AttemptedOverwrite

Throws if there is already a Wnd in the given cell.

void GG::Layout::Add	(	Wnd *	wnd,
		int	row,
		int	column,
		int	num_rows,
		int	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 row, and column must be nonnegative and 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	(	int	rows,
		int	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	(	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 ( int margin )

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

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

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

void GG::Layout::SetRowStretch	(	int	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	(	int	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	(	int	row,
		int	height
	)

sets the minimum height of row row to height.

Note that row is not range-checked.

void GG::Layout::SetMinimumColumnWidth	(	int	column,
		int	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.

virtual void GG::Layout::DefineAttributes ( WndEditor * editor ) [virtual]

provides the attributes of this object that are appropriate for a user to edit in a WndEditor; see WndEditor for details.

Reimplemented from GG::Wnd.

GG::Layout::GG_ABSTRACT_EXCEPTION ( Exception )

The base class for Layout exceptions.

Reimplemented from GG::Wnd.

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.


Structors
	Layout (int x, int y, int w, int h, int rows, int columns, int border_margin=0, int cell_margin=-1)
Accessors
virtual Pt	MinUsableSize () const
int	Rows () const
int	Columns () const
Flags< Alignment >	ChildAlignment (Wnd *wnd) const
int	BorderMargin () const
int	CellMargin () const
double	RowStretch (int row) const
double	ColumnStretch (int column) const
int	MinimumRowHeight (int row) const
int	MinimumColumnWidth (int 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::list< Wnd * > &wnds)
virtual void	ChildrenDraggedAway (const std::list< Wnd * > &wnds, const Wnd *destination)
virtual void	SizeMove (const Pt &ul, const Pt &lr)
virtual void	Render ()
virtual void	MouseWheel (const Pt &pt, int move, Flags< ModKey > mod_keys)
virtual void	KeyPress (Key key, Flags< ModKey > mod_keys)
virtual void	KeyRelease (Key key, Flags< ModKey > mod_keys)
void	Add (Wnd *wnd, int row, int column, Flags< Alignment > alignment=ALIGN_NONE)
void	Add (Wnd *wnd, int row, int column, int num_rows, int num_columns, Flags< Alignment > alignment=ALIGN_NONE)
void	Remove (Wnd *wnd)
void	DetachAndResetChildren ()
void	ResizeLayout (int rows, int columns)
void	SetChildAlignment (Wnd *wnd, Flags< Alignment > alignment)
void	SetBorderMargin (int margin)
void	SetCellMargin (int margin)
void	SetRowStretch (int row, double stretch)
void	SetColumnStretch (int column, double stretch)
void	SetMinimumRowHeight (int row, int height)
void	SetMinimumColumnWidth (int column, int width)
void	RenderOutline (bool render_outline)
void	SetOutlineColor (Clr color)
virtual void	DefineAttributes (WndEditor *editor)
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)
Structors
	Layout ()
Friends
class	Wnd
struct	SetMarginAction

GG::Layout Class Reference

Structors

Accessors

Mutators

Exceptions

Structors

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation