A way to place Panel objects dynamically with a priority mechanism to allow panels to be resized and moved more automatically to support panels changing in importance on a user interface. More...

#include <PriorityGridLayout.hpp>

Collaboration diagram for duds::ui::graphics::PriorityGridLayout:

[legend]

Classes
struct	PanelStatus
	Internal data structure used to store a Panel, its configuration, and current layout status. More...

struct	RowData
	Internal data structure used by layout() to store information on each row that is only needed to place all the panels. More...

Public Member Functions
bool	add (const PanelSptr &panel, const GridLayoutConfig &config, unsigned int pri)
	Adds a panel in an unused priority spot, or fail to add if the spot is already used. More...

bool	add (const PanelSptr &panel, const GridSizeStep &config, unsigned int pri)
	Adds a panel in an unused priority spot, or fail to add if the spot is already used. More...

unsigned int	add (const PanelSptr &panel, const GridLayoutConfig &config)
	Adds a panel to the next lowest priority spot. More...

unsigned int	add (const PanelSptr &panel, const GridSizeStep &config)
	Adds a panel to the next lowest priority spot. More...

void	addOrReplace (const PanelSptr &panel, const GridLayoutConfig &config, unsigned int pri)
	Adds a panel or replaces an existing panel at the given priority spot. More...

void	addOrReplace (const PanelSptr &panel, const GridSizeStep &config, unsigned int pri)
	Adds a panel or replaces an existing panel at the given priority spot. More...

int	layout ()
	Places all panels into general positions. More...

ImageDimensions	layoutDimensions (unsigned int pri) const
	Returns the dimensions assigned to the panel at priority pri by layout(), or { 0, 0 }. More...

ImageLocation	layoutLocation (unsigned int pri) const
	Returns the location assigned to the panel at priority pri by layout(), or { 0, 0 }. More...

bool	layoutPosition (ImageDimensions &dim, ImageLocation &loc, unsigned int pri) const
	Provides the dimensions and location assigned to the panel at priority pri by layout() More...

void	maxRowHeight (int row, std::int16_t height)
	Sets the maximum height of a row. More...

std::int16_t	maxRowHeight (int row) const
	Returns the maximum height of a row. More...

GridLayoutConfig &	panelConfig (unsigned int pri)
	Returns the layout configuration for the specified panel. More...

const GridLayoutConfig &	panelConfig (unsigned int pri) const
	Returns the layout configuration for the specified panel. More...

void	remove (unsigned int pri)
	Removes the panel in the given priority spot. More...

void	remove (const PanelSptr &panel)
	Removes the given panel if it is present. More...

void	render (BppImage *dest)
	Renders all visible panels to the provided image. More...

void	render (BppImage &dest)
	Renders all visible panels to the provided image. More...

void	render (const BppImageSptr &dest)
	Renders all visible panels to the provided image. More...

void	renderFill (const ImageDimensions &dim)
	Changes the area filled by the layout. More...

const ImageDimensions &	renderFill () const
	Returns the area filled by the layout. More...

void	renderOffset (const ImageLocation &off)
	Change the upper left corner of the destination image that will receive the panel images rendered through the layout. More...

const ImageLocation &	renderOffset () const
	Returns the upper left corner of the destination image that will receive the panel images rendered through the layout. More...

Private Types
typedef std::map< unsigned int, PanelStatus >	GridConfig
	The type that maps panel priorities to panel data. More...

typedef std::vector< RowData >	RowVec
	Type used inside layout() to store data on all the rows. More...

Static Private Member Functions
static bool	minRows (RowVec &rv, int ms)
	Ensures a minimum number of rows in rv, and returns true if at least that many rows already existed. More...

static unsigned int	panelAt (RowVec &rv, const GridLocation &gl) noexcept
	Returns the priority key for the panel at the given location, or zero if there is no panel. More...

Private Attributes
GridConfig	configs
	The mapping of Panel objects by priority key. More...

ImageDimensions	fill
	The area to fill in the destination image. More...

ImageLocation	offset = { 0, 0 }
	The upper right location of the destination image where the topmost row and leftmost column will be placed. More...

std::vector< std::int16_t >	rowMaxHeight
	Maximum heights for rows. More...

Detailed Description

A way to place Panel objects dynamically with a priority mechanism to allow panels to be resized and moved more automatically to support panels changing in importance on a user interface.

Panels are added with a priority key. This key is a positive integer where lower values represent a higher priority. The panels are placed in the layout in order of their priority. Lower priority panels might not be given their first choice of location and size, and might not even be placed at all.

Each panel's configuration includes a series of size-steps in GridLayoutConfig::sizes. These size-steps include a grid location that places the panel relative to other panels, and its minimum size.

The grid location includes a row and column. The layout organizes the panels first by row and then by column. There is no attempt to make the columns between rows line up; the column location only affects where a panel will be with respect to other panels in the same row. All panels in the same row will have available to them the same height. Any unused grid locations do not take up space in the final result.

Only one panel will be placed into a given grid location. If a panel has a size-step that requests a location used by a higher priority panel, then the next size-step will be tried. If a size-step requests a minimum size that cannot be fullfilled with the remaining space, the next size-step will be tried. Any size-steps flagged as hidden will be skipped. If no size-step can be used to place a panel, the panel will not be rendered. The index of the size-step selected during layout is passed to Panel::render() during rendering so that the rendering code can use it as a hint for how the panel should be rendered.

After panels are added, removed, their configurations changed, or the fill dimensions (renderFill()) are changed, layout() must be called prior to calling render() again. None of these operations are thread-safe.

To render, a destination image must be provided. The panel images will be written into the destination. The area of the destination used by the layout is defined by an offset location (renderOffset()) and a fill dimension (renderFill()). Each panel will provide its image when its Panel::render() function is called. If the image does not cover the whole area allocated to the panel, the unused area in the destination image will remain unchanged.

Author: Jeff Jackowski

Definition at line 65 of file PriorityGridLayout.hpp.

Member Typedef Documentation

◆ GridConfig

typedef std::map<unsigned int, PanelStatus> duds::ui::graphics::PriorityGridLayout::GridConfig

private

The type that maps panel priorities to panel data.

Definition at line 120 of file PriorityGridLayout.hpp.

◆ RowVec

typedef std::vector<RowData> duds::ui::graphics::PriorityGridLayout::RowVec

private

Type used inside layout() to store data on all the rows.

Definition at line 170 of file PriorityGridLayout.hpp.

Member Function Documentation

◆ add() [1/4]

bool duds::ui::graphics::PriorityGridLayout::add	(	const PanelSptr &	panel,
		const GridLayoutConfig &	config,
		unsigned int	pri
	)

Adds a panel in an unused priority spot, or fail to add if the spot is already used.

Parameters

panel	The panel to add.
config	The layout configuration used to place the panel.
pri	The unique priority for the panel. It must be positive.

Returns: True if the panel was added. False if there already is a panel with priority pri.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

LayoutPriorityInvalidError	The provided priority value is zero.
object	Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 70 of file PriorityGridLayout.cpp.

Referenced by renderFill().

◆ add() [2/4]

bool duds::ui::graphics::PriorityGridLayout::add	(	const PanelSptr &	panel,
		const GridSizeStep &	config,
		unsigned int	pri
	)

Adds a panel in an unused priority spot, or fail to add if the spot is already used.

Parameters

panel	The panel to add.
config	A size-stpe layout configuration used to place the panel. A GridLayoutConfig object will be created based on the size-step.
pri	The unique priority for the panel. It must be positive.

Returns: True if the panel was added. False if there already is a panel with priority pri.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

LayoutPriorityInvalidError	The provided priority value is zero.
object	Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 92 of file PriorityGridLayout.cpp.

◆ add() [3/4]

unsigned int duds::ui::graphics::PriorityGridLayout::add	(	const PanelSptr &	panel,
		const GridLayoutConfig &	config
	)

Adds a panel to the next lowest priority spot.

Parameters

panel	The panel to add.
config	The layout configuration used to place the panel.

Returns: The unique priority assigned to the panel.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

object Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 114 of file PriorityGridLayout.cpp.

◆ add() [4/4]

unsigned int duds::ui::graphics::PriorityGridLayout::add	(	const PanelSptr &	panel,
		const GridSizeStep &	config
	)

Adds a panel to the next lowest priority spot.

Parameters

panel	The panel to add.
config	A size-stpe layout configuration used to place the panel. A GridLayoutConfig object will be created based on the size-step.

Returns: The unique priority assigned to the panel.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

object Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 129 of file PriorityGridLayout.cpp.

◆ addOrReplace() [1/2]

void duds::ui::graphics::PriorityGridLayout::addOrReplace	(	const PanelSptr &	panel,
		const GridLayoutConfig &	config,
		unsigned int	pri
	)

Adds a panel or replaces an existing panel at the given priority spot.

Parameters

panel	The panel to add.
config	The layout configuration used to place the panel.
pri	The unique priority for the panel. It must be positive.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

LayoutPriorityInvalidError	The provided priority value is zero.
object	Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 144 of file PriorityGridLayout.cpp.

Referenced by add(), and renderFill().

◆ addOrReplace() [2/2]

void duds::ui::graphics::PriorityGridLayout::addOrReplace	(	const PanelSptr &	panel,
		const GridSizeStep &	config,
		unsigned int	pri
	)

Adds a panel or replaces an existing panel at the given priority spot.

Parameters

panel	The panel to add.
config	A size-stpe layout configuration used to place the panel. A GridLayoutConfig object will be created based on the size-step.
pri	The unique priority for the panel. It must be positive.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

LayoutPriorityInvalidError	The provided priority value is zero.
object	Anything thrown by Panel::added() of panel. If this occurs, the panel will not be added.

Definition at line 161 of file PriorityGridLayout.cpp.

◆ layout()

int duds::ui::graphics::PriorityGridLayout::layout ( )

Places all panels into general positions.

After any changes to layout configurations, this function must be called prior to render().

Returns: The number of panels that have been allocated space on the grid layout.

Definition at line 216 of file PriorityGridLayout.cpp.

Referenced by renderFill().

◆ layoutDimensions()

ImageDimensions duds::ui::graphics::PriorityGridLayout::layoutDimensions ( unsigned int pri ) const

Returns the dimensions assigned to the panel at priority pri by layout(), or { 0, 0 }.

Parameters

pri	The unique priority for the panel.

Definition at line 503 of file PriorityGridLayout.cpp.

Referenced by render().

◆ layoutLocation()

ImageLocation duds::ui::graphics::PriorityGridLayout::layoutLocation ( unsigned int pri ) const

Returns the location assigned to the panel at priority pri by layout(), or { 0, 0 }.

Parameters

pri	The unique priority for the panel.

Definition at line 511 of file PriorityGridLayout.cpp.

Referenced by render().

◆ layoutPosition()

bool duds::ui::graphics::PriorityGridLayout::layoutPosition	(	ImageDimensions &	dim,
		ImageLocation &	loc,
		unsigned int	pri
	)		const

Provides the dimensions and location assigned to the panel at priority pri by layout()

Parameters

dim	The destination for the assigned panel dimensions.
loc	The destination for the assigned panel location.
pri	The unique priority for the panel.

Returns: True if the layout data was found and copied, or false and no data was changed.

Definition at line 519 of file PriorityGridLayout.cpp.

Referenced by render().

◆ maxRowHeight() [1/2]

void duds::ui::graphics::PriorityGridLayout::maxRowHeight	(	int	row,
		std::int16_t	height
	)

Sets the maximum height of a row.

Note: The values are stored in a std::vector. To minimize how many times the vector is reallocated, start with the row in the bottom position.

Parameters

row	The row to change. Zero is the topmost row.
height	The maximum height for the row. There is always a maximum height, so removing the restriction is done by making the restriction huge, like 0x7FFF.

Postcondition: layout() must be called before the next call to render().

Definition at line 56 of file PriorityGridLayout.cpp.

Referenced by layout(), and renderFill().

◆ maxRowHeight() [2/2]

std::int16_t duds::ui::graphics::PriorityGridLayout::maxRowHeight ( int row ) const

Returns the maximum height of a row.

There is always a maximum height. If one has not been specified, the returned value will be 0x7FFF.

Parameters

row	The row to query. Zero is the topmost row.

Definition at line 63 of file PriorityGridLayout.cpp.

◆ minRows()

bool duds::ui::graphics::PriorityGridLayout::minRows	(	RowVec &	rv,
		int	ms
	)

staticprivate

Ensures a minimum number of rows in rv, and returns true if at least that many rows already existed.

Parameters

rv	The vector of rows.
ms	The minimum number of rows.

Returns: True if the minimum already existed, false if the vector rv was expanded.

Definition at line 29 of file PriorityGridLayout.cpp.

Referenced by panelAt().

◆ panelAt()

unsigned int duds::ui::graphics::PriorityGridLayout::panelAt	(	RowVec &	rv,
		const GridLocation &	gl
	)

staticprivatenoexcept

Returns the priority key for the panel at the given location, or zero if there is no panel.

Parameters

rv	The vector of row information.
gl	The location to check.

Definition at line 37 of file PriorityGridLayout.cpp.

Referenced by layout().

◆ panelConfig() [1/2]

GridLayoutConfig & duds::ui::graphics::PriorityGridLayout::panelConfig ( unsigned int pri )

Returns the layout configuration for the specified panel.

The configuration may be modified, but not in a thread-safe manner. If modifications are made, layout() must be called prior to rendering again.

Parameters

pri	The unique priority for the panel.

Returns: The panel's layout configuration. Do not modify this while layout() or render() are running on this object on another thread.

Postcondition: If the configuration is altered, layout() must be called before the next call to render().

Exceptions

PanelNotFoundError There is no panel at the given priority.

Definition at line 200 of file PriorityGridLayout.cpp.

Referenced by duds::ui::graphics::SingleLayoutPanel::panelConfig(), and renderFill().

◆ panelConfig() [2/2]

const GridLayoutConfig & duds::ui::graphics::PriorityGridLayout::panelConfig ( unsigned int pri ) const

Returns the layout configuration for the specified panel.

Parameters

pri	The unique priority for the panel.

Exceptions

PanelNotFoundError There is no panel at the given priority.

Definition at line 208 of file PriorityGridLayout.cpp.

◆ remove() [1/2]

void duds::ui::graphics::PriorityGridLayout::remove ( unsigned int pri )

Removes the panel in the given priority spot.

Parameters

pri	The priority of the panel to remove.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

object Anything thrown by Panel::removing() of the panel being removed. If this occurs, the panel will not be removed.

Definition at line 178 of file PriorityGridLayout.cpp.

◆ remove() [2/2]

void duds::ui::graphics::PriorityGridLayout::remove ( const PanelSptr & panel )

Removes the given panel if it is present.

If the panel has been added multiple times, only the highest priority entry will be removed. This requires searching for the panel, so this function is slower than remove(unsigned int).

Parameters

panel The panel to remove.

Postcondition: layout() must be called before the next call to render() if no exception is thrown.

Exceptions

object Anything thrown by Panel::removing() of the panel being removed. If this occurs, the panel will not be removed.

Definition at line 186 of file PriorityGridLayout.cpp.

◆ render() [1/3]

void duds::ui::graphics::PriorityGridLayout::render ( BppImage * dest )

Renders all visible panels to the provided image.

If a panel does not use all the area allocated to it, the corresponding unused area of dest will remain unchanged.

Parameters

dest	The destination image. The area defined by renderFill(), starting at renderOffset(), may be overwritten with images from the panels. The rest of the image will not be changed.

Exceptions

ImageBoundsError	The destination image isn't large enough to hold the layout. The layout size is renderFill(), starting at the location renderOffset().
PanelImageTooLargeError	A panel provided an image larger than the dimensions it was allocated by the layout. If this is thrown, the destination image may be altered by other panels, but not all of the panels will be rendered. This could be changed by obtaining all panel images first and then rendering them if no exceptions are thrown.

Definition at line 425 of file PriorityGridLayout.cpp.

Referenced by render(), and renderFill().

◆ render() [2/3]

void duds::ui::graphics::PriorityGridLayout::render ( BppImage & dest )

inline

Renders all visible panels to the provided image.

If a panel does not use all the area allocated to it, the corresponding unused area of dest will remain unchanged.

Parameters

dest	The destination image. The area defined by renderFill(), starting at renderOffset(), may be overwritten with images from the panels. The rest of the image will not be changed.

Exceptions

ImageBoundsError	The destination image isn't large enough to hold the layout. The layout size is renderFill(), starting at the location renderOffset().
PanelImageTooLargeError	A panel provided an image larger than the dimensions it was allocated by the layout. If this is thrown, the destination image may be altered by other panels, but not all of the panels will be rendered. This could be changed by obtaining all panel images first and then rendering them if no exceptions are thrown.

Definition at line 421 of file PriorityGridLayout.hpp.

◆ render() [3/3]

void duds::ui::graphics::PriorityGridLayout::render ( const BppImageSptr & dest )

inline

Renders all visible panels to the provided image.

If a panel does not use all the area allocated to it, the corresponding unused area of dest will remain unchanged.

Parameters

dest	The destination image. The area defined by renderFill(), starting at renderOffset(), may be overwritten with images from the panels. The rest of the image will not be changed.

Exceptions

ImageBoundsError	The destination image isn't large enough to hold the layout. The layout size is renderFill(), starting at the location renderOffset().
PanelImageTooLargeError	A panel provided an image larger than the dimensions it was allocated by the layout. If this is thrown, the destination image may be altered by other panels, but not all of the panels will be rendered. This could be changed by obtaining all panel images first and then rendering them if no exceptions are thrown.

Definition at line 427 of file PriorityGridLayout.hpp.

◆ renderFill() [1/2]

void duds::ui::graphics::PriorityGridLayout::renderFill ( const ImageDimensions & dim )

inline

Changes the area filled by the layout.

Parameters

dim	The dimensions of the layout area.

Postcondition: layout() must be called before the next call to render().

Definition at line 221 of file PriorityGridLayout.hpp.

◆ renderFill() [2/2]

const ImageDimensions& duds::ui::graphics::PriorityGridLayout::renderFill ( ) const

inline

Returns the area filled by the layout.

Definition at line 227 of file PriorityGridLayout.hpp.

◆ renderOffset() [1/2]

void duds::ui::graphics::PriorityGridLayout::renderOffset ( const ImageLocation & off )

inline

Change the upper left corner of the destination image that will receive the panel images rendered through the layout.

Parameters

off	The new offset.

Definition at line 206 of file PriorityGridLayout.hpp.

◆ renderOffset() [2/2]

const ImageLocation& duds::ui::graphics::PriorityGridLayout::renderOffset ( ) const

inline

Returns the upper left corner of the destination image that will receive the panel images rendered through the layout.

Definition at line 213 of file PriorityGridLayout.hpp.

Member Data Documentation

◆ configs

GridConfig duds::ui::graphics::PriorityGridLayout::configs

private

The mapping of Panel objects by priority key.

The priority must be positive; zero is used to denote the absence of a panel.

Definition at line 125 of file PriorityGridLayout.hpp.

Referenced by add(), addOrReplace(), layout(), layoutDimensions(), layoutLocation(), layoutPosition(), panelConfig(), remove(), and render().

◆ fill

ImageDimensions duds::ui::graphics::PriorityGridLayout::fill

private

The area to fill in the destination image.

Definition at line 183 of file PriorityGridLayout.hpp.

Referenced by layout(), render(), and renderFill().

◆ offset

ImageLocation duds::ui::graphics::PriorityGridLayout::offset = { 0, 0 }

private

The upper right location of the destination image where the topmost row and leftmost column will be placed.

Definition at line 179 of file PriorityGridLayout.hpp.

Referenced by render(), and renderOffset().

◆ rowMaxHeight

std::vector<std::int16_t> duds::ui::graphics::PriorityGridLayout::rowMaxHeight

private

Maximum heights for rows.

Definition at line 174 of file PriorityGridLayout.hpp.

Referenced by layout(), and maxRowHeight().

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

Classes

Public Member Functions

Private Types

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ GridConfig

◆ RowVec

Member Function Documentation

◆ add() [1/4]

◆ add() [2/4]

◆ add() [3/4]

◆ add() [4/4]

◆ addOrReplace() [1/2]

◆ addOrReplace() [2/2]

◆ layout()

◆ layoutDimensions()

◆ layoutLocation()

◆ layoutPosition()

◆ maxRowHeight() [1/2]

◆ maxRowHeight() [2/2]

◆ minRows()

◆ panelAt()

◆ panelConfig() [1/2]

◆ panelConfig() [2/2]

◆ remove() [1/2]

◆ remove() [2/2]

◆ render() [1/3]

◆ render() [2/3]

◆ render() [3/3]

◆ renderFill() [1/2]

◆ renderFill() [2/2]

◆ renderOffset() [1/2]

◆ renderOffset() [2/2]

Member Data Documentation

◆ configs

◆ fill

◆ offset

◆ rowMaxHeight