#include <ImFusion/GUI/DisplayAutoLayouter.h>

This class facilitates the layouting of Views inside a Display by encapsulating logic to generate layouts for dynamic view configurations based on a customizable set of layouting algorithms. More...

Inheritance diagram for DisplayAutoLayouter:

Detailed Description

This class facilitates the layouting of Views inside a Display by encapsulating logic to generate layouts for dynamic view configurations based on a customizable set of layouting algorithms.

The DisplayAutoLayouter is an optional building block that operates on the Display instance passed during construction to automatically create an appropriate DisplayLayout for it. You do not need to register Views with DisplayAutoLayouter since it will query Display::views() when needed. However, you can configure the visibility of individual Views, an optional ordering, and select the used layouting algorithm. Furthermore, you can specify additional settings for the layouting algorithm such as an optional maximizedView(), focusedView(), and lastViewInTopRow().

DisplayAutoLayouter will automatically apply the resulting DisplayLayoutConfig to the target Display passed during construction and call DisplayLayout::layout(). You can subscribe to the signalLayoutingPerformed to be notified whenever this happens.

This class comes with a set of predefined layouting algorithms that you can access through the Mode enumeration. Furthermore, you can create custom algorithms by implementing the LayoutAlgorithm interface and registering it through addLayoutAlgorithm().

The Feature enumeration enables a LayoutAlgorithm to indicate whether or not it supports a feature of the DisplayAutoLayouter. They do not have a direct impact on the functionality but allow consumers of this class (such as the ViewLayoutWidget) to implement custom logic based on the selected/available layouting algorithms.

Note: DisplayAutoLayouter has no way of automatically getting notified if the target display's set of views has changed. You must call resetLayout() manually to trigger the layouting process in which it will query the updated list of views.

See also: Display, DisplayLayout, DisplayLayoutConfig

Classes
class	LayoutAlgorithm
	Interface to derive from to define custom display layout algorithms. More...

struct	LayoutInfo
	Record of information passed to LayoutFunction::createLayout(). More...

Public Types
enum class	Mode { Auto = 0 , Rows = 1 , FocusPlusStack = 2 , FocusPlusRows = 3 , Custom = 100 }
	Enumeration of predefined layouting algorithms. More...

enum class	Feature { None = 0 , Supports2DView = 1 , SupportsMPRViews = 2 , Supports3DView = 4 , SupportsAlgorithmViews = 8 , SupportsFocus = 16 , SupportsTopBottomRow = 32 , SupportsAllViews = Supports2DView \| SupportsMPRViews \| Supports3DView \| SupportsAlgorithmViews }
	Enumeration of layouting features that a LayoutAlgorithm may support. More...

Public Member Functions
	DisplayAutoLayouter (DisplayBase &targetDisplay)

const DisplayLayoutConfig &	resetLayout ()
	Recompute the view layout with the currently configured settings and apply it to `targetDisplay()->layout()`.

const DisplayLayoutConfig &	lastLayoutConfig () const
	Returns the DisplayLayoutConfig generated by the last call to resetLayout().

void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.

void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.

Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.

void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().

void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.

	Configurable (const Configurable &rhs)

	Configurable (Configurable &&rhs) noexcept

Configurable &	operator= (const Configurable &)

Configurable &	operator= (Configurable &&) noexcept

Public Attributes
Signal< Mode >	signalModeChanged
	Emitted whenever the currentMode() has changed.

Signal	signalLayoutingPerformed
	Emitted whenever the views have been re-layouted and `targetDisplay()->layout()` was changed.

Signal< const View *, bool >	signalViewHiddenChanged
	Emitted whenever the hidden-state for a registered view was changed.

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Specify the list of views to be layouted, their visibility, and their order
bool	isViewHidden (const View *view) const
	Returns whether view should be hidden in the generated DisplayLayout.

void	setViewHidden (const View *view, bool value)
	Sets whether view should be hidden in the generated DisplayLayout.

void	setViewsHidden (const std::vector< const View * > &views, bool value)
	Sets whether the given set of views should be hidden in the generated DisplayLayout.

std::vector< const View * >	visibleViews () const
	Returns all views of the targetDisplay() that are configured as not hidden considering the optional viewOrder() if it was set.

void	setViewOrder (std::optional< std::vector< const View * > > viewOrder)
	Set an optional custom view order to be used by the display layout.

const std::optional< std::vector< const View * > > &	viewOrder () const
	Returns the optional custom order of the views shown in the display layout.

void	swapViewOrder (const View view1, const View view2)
	Swaps the position of the two given views in the display layout.

Configure optional settings passed to the layouting algorithm if applicable.
const View *	maximizedView () const
	Returns the optional view that should be shown alone in a maximized fashion.

void	setMaximizedView (const View *value)
	Sets an optional view that should be shown alone in a maximized fashion.

const View *	focusedView () const
	Returns the view that is in focus if supported by the current layout mode.

void	setFocusedView (const View *value)
	Sets the view that is in focus if supported by the current layout mode.

const GUI::View *	lastViewInTopRow () const
	Returns a pointer to last view to be shown in top row in cases where views shall not be distributed evenly.

void	moveViewToTopRow (const View *view)
	Moves the given view to the top row for display layouts that support LayoutFeatures::FeaturesTopBottomRow.

void	moveViewToBottomRow (const View *view)
	Moves the given view to the bottom row for display layouts that support LayoutFeatures::FeaturesTopBottomRow.

Select the layouting algorithm/mode and add/remove custom algorithms.
Mode	currentMode () const
	Returns the current view layout mode.

void	setCurrentMode (Mode value)
	Sets the current view layout mode.

const LayoutAlgorithm &	currentLayoutAlgorithm () const
	Returns the currently active layouting algorithm.

Mode	addLayoutAlgorithm (std::unique_ptr< LayoutAlgorithm > algorithm)
	Registers a new custom layouting algorithm and returns the custom Mode (`>= Mode::Custom`) under which it was registered.

void	removeLayoutAlgorithm (Mode mode)
	Removes a layouting algorithm that was previously registered under the given mode.

LayoutAlgorithm *	layoutAlgorithm (Mode mode) const
	Returns the layouting algorithm that was registered for the given mode or `nullptr` if no such algorithm is found.

Additional Inherited Members
Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Member Enumeration Documentation

◆ Mode

enum class Mode

strong

Enumeration of predefined layouting algorithms.

Enumerator
Auto	Automatically chooses one between Rows or FocusPlusStack mode based on the visible views.
Rows	Arranges all views in a grid-like fashion with up to 2 rows.
FocusPlusStack	Shows a large focus view and vertically stacks all other views to the right.
FocusPlusRows	Shows a large focus view and uses the Rows layout on the right for the other views.
Custom	First enum value to be used for custom algorithms registered through addLayoutAlgorithm().

◆ Feature

enum class Feature

strong

Enumeration of layouting features that a LayoutAlgorithm may support.

Enumerator
Supports2DView	supports show/hide 2D view
SupportsMPRViews	supports show/hide MPR views
Supports3DView	supports show/hide 3D view
SupportsAlgorithmViews	supports show/hide algorithm views
SupportsFocus	supports a view being focused e.g. larger or more prominent than the rest
SupportsTopBottomRow	supports a view being move to top/bottom row

Member Function Documentation

◆ isViewHidden()

bool isViewHidden ( const View * view ) const

Returns whether view should be hidden in the generated DisplayLayout.

Note

The naming of this function was chosen carefully to express the visibility logic of DisplayAutoLayouter. The "hidden" state of a view serves only as input to the layouting algorithm. Marking a view as hidden means that it will never be considered during layouting and thus never be visible. However, a view that is not marked hidden may still not appear in the resulting currentLayout():

The LayoutFunction may choose to display a view even if it is supposed to be hidden.
Setting a maximizedView() will hide all other views even they are set visible.
Only views that are part of targetDisplay() will be considered.

◆ setViewHidden()

void setViewHidden	(	const View *	view,
		bool	value )

Sets whether view should be hidden in the generated DisplayLayout.

Note

The naming of this function was chosen carefully to express the visibility logic of DisplayAutoLayouter. The "hidden" state of a view serves only as input to the layouting algorithm. Marking a view as hidden means that it will never be considered during layouting and thus never be visible. However, a view that is not marked hidden may still not appear in the resulting currentLayout():

The LayoutFunction may choose to display a view even if it is supposed to be hidden.
Setting a maximizedView() will hide all other views even they are set visible.
Only views that are part of targetDisplay() will be considered.

◆ setViewsHidden()

void setViewsHidden	(	const std::vector< const View * > &	views,
		bool	value )

Sets whether the given set of views should be hidden in the generated DisplayLayout.

Note

The naming of this function was chosen carefully to express the visibility logic of DisplayAutoLayouter. The "hidden" state of a view serves only as input to the layouting algorithm. Marking a view as hidden means that it will never be considered during layouting and thus never be visible. However, a view that is not marked hidden may still not appear in the resulting currentLayout():

The LayoutFunction may choose to display a view even if it is supposed to be hidden.
Setting a maximizedView() will hide all other views even they are set visible.
Only views that are part of targetDisplay() will be considered.

◆ setViewOrder()

void setViewOrder ( std::optional< std::vector< const View * > > viewOrder )

Set an optional custom view order to be used by the display layout.

If configured, visibleViews() will consider the order in addition to viewVisibility() when filtering the views of targetDisplay(). Missing views will be appended to the end of the list.

◆ swapViewOrder()

void swapViewOrder	(	const View *	view1,
		const View *	view2 )

Swaps the position of the two given views in the display layout.

Note: This function will synchronize viewOrder() with the targetDisplay()->views() so that they contain the same set of views.

◆ setMaximizedView()

void setMaximizedView ( const View * value )

Sets an optional view that should be shown alone in a maximized fashion.

If you pass nullptr it will restore the layout config from before setting the maximized view.

◆ moveViewToTopRow()

void moveViewToTopRow ( const View * view )

Moves the given view to the top row for display layouts that support LayoutFeatures::FeaturesTopBottomRow.

Note: This function will synchronize viewOrder() with the targetDisplay()->views() so that they contain the same set of views.

◆ moveViewToBottomRow()

void moveViewToBottomRow ( const View * view )

Moves the given view to the bottom row for display layouts that support LayoutFeatures::FeaturesTopBottomRow.

Note: This function will synchronize viewOrder() with the targetDisplay()->views() so that they contain the same set of views.

◆ removeLayoutAlgorithm()

void removeLayoutAlgorithm ( Mode mode )

Removes a layouting algorithm that was previously registered under the given mode.

Function will have no effect if mode is currentMode().

◆ resetLayout()

const DisplayLayoutConfig & resetLayout ( )

Recompute the view layout with the currently configured settings and apply it to targetDisplay()->layout().

Normally, you do not need to call this function from the outside explicitly because all other member functions ensure to call it when necessary. You can query the result through observing the return value, querying lastLayoutConfig() afterwards, or by subscribing to signalLayoutingPerformed.

◆ configure()

void configure ( const Properties * p )

overridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configuration() for the inverse functionality

Reimplemented from Configurable.

◆ configuration()

void configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from Configurable.

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

ImFusion/GUI/DisplayAutoLayouter.h

Detailed Description

Classes

Public Types

Public Member Functions

Public Attributes

Specify the list of views to be layouted, their visibility, and their order

Configure optional settings passed to the layouting algorithm if applicable.

Select the layouting algorithm/mode and add/remove custom algorithms.

Additional Inherited Members

Member Enumeration Documentation

◆ Mode

◆ Feature

Member Function Documentation

◆ isViewHidden()

◆ setViewHidden()

◆ setViewsHidden()

◆ setViewOrder()

◆ swapViewOrder()

◆ setMaximizedView()

◆ moveViewToTopRow()

◆ moveViewToBottomRow()

◆ removeLayoutAlgorithm()

◆ resetLayout()

◆ configure()

◆ configuration()