Magnum::Ui::SnapLayouter class new in Git master
#include <Magnum/Ui/SnapLayouter.h>

Snap layouter.

Allows positioning nodes in columns and rows with size propagation along with explicitly snapping particular nodes to corners or edges of other nodes.

Setting up a snap layouter instance

If you create a UserInterfaceGL with a style and don't exclude StyleFeature::SnapLayouter, an implicit instance is already provided and available through UserInterface::snapLayouter(). Otherwise, the layouter doesn't have any shared state or configuration, so it's just about constructing it from a fresh AbstractUserInterface::createLayouter() handle and passing it to UserInterface::setEventLayerInstance():

ui.setSnapLayouterInstance(
    Containers::pointer<Ui::SnapLayouter>(ui.createLayouter()));

In comparison, if you want to set up a custom snap layouter that's independent of the one exposed through UserInterface::snapLayouter(), pass the newly created instance to AbstractUserInterface::setLayouterInstance() instead:

Ui::SnapLayouter& layouter = ui.setLayouterInstance(
    Containers::pointer<Ui::SnapLayouter>(ui.createLayouter()));

Afterwards, with either of the above, assuming AbstractUserInterface::draw() is called in an appropriate place, the layouter is ready to use.

Base classes

class AbstractLayouter new in Git master: Base for layouters.

Constructors, destructors, conversion operators

SnapLayouter(LayouterHandle handle) explicit: Constructor.
SnapLayouter(const SnapLayouter&) deleted: Copying is not allowed.
SnapLayouter(SnapLayouter&&) noexcept: Move constructor.

Public functions

auto operator=(const SnapLayouter&) -> SnapLayouter& deleted: Copying is not allowed.
auto operator=(SnapLayouter&&) -> SnapLayouter& noexcept: Move assignment.
auto add(NodeHandle node, LayoutHandle before = LayoutHandle::Null, SnapLayoutFlags flags = {}) -> LayoutHandle: Add a layout assigned to given node.
auto add(NodeHandle node, SnapLayoutFlags flags) -> LayoutHandle
auto add(NodeHandle node, LayouterDataHandle before, SnapLayoutFlags flags = {}) -> LayoutHandle: Add a layout assigned to given node, and before given layout assuming the layout belongs to this layouter.
auto add(NodeHandle node, Snaps snap, LayoutHandle snapTarget, SnapLayoutFlags flags = {}) -> LayoutHandle: Add a layout snapping explicitly to given target.
auto add(NodeHandle node, Snaps snap, LayouterDataHandle snapTarget, SnapLayoutFlags flags = {}) -> LayoutHandle: Add a layout snapping explicitly to given target, assuming the target belongs to this layouter.
void remove(LayoutHandle handle): Remove a layout.
void remove(LayouterDataHandle handle): Remove a layout assuming it belongs to this layer.
auto flags(LayoutHandle handle) const -> SnapLayoutFlags: Layout flags.
auto flags(LayouterDataHandle handle) const -> SnapLayoutFlags: Layout flags assuming it belongs to this layouter.
void setFlags(LayoutHandle handle, SnapLayoutFlags flags): Set layout flags.
void setFlags(LayouterDataHandle handle, SnapLayoutFlags flags): Set layout flags assuming it belongs to this layouter.
void addFlags(LayoutHandle handle, SnapLayoutFlags flags): Add layout flags.
void addFlags(LayouterDataHandle handle, SnapLayoutFlags flags): Add layout flags assuming it belongs to this layouter.
void clearFlags(LayoutHandle handle, SnapLayoutFlags flags): Clear layout flags.
void clearFlags(LayouterDataHandle handle, SnapLayoutFlags flags): Clear layout flags assuming it belongs to this layouter.
auto childSnap(LayoutHandle handle) const -> Snaps: Snap for child layouts.
auto childSnap(LayouterDataHandle handle) const -> Snaps: Snap for child layouts assuming it belongs to this layouter.
void setChildSnap(LayoutHandle handle, Snaps snap): Set snap for child layouts.
void setChildSnap(LayouterDataHandle handle, Snaps snap): Set snap for child layouts assuming it belongs to this layouter.
auto firstChild(LayoutHandle handle) const -> LayoutHandle: First child layout.
auto firstChild(LayouterDataHandle handle) const -> LayoutHandle: First child layout assuming it belongs to this layouter.
auto firstExplicitSnap(LayoutHandle handle) const -> LayoutHandle: First layout explicitly snapped to this one.
auto firstExplicitSnap(LayouterDataHandle handle) const -> LayoutHandle: First layout explicitly snapped to this one assuming it belongs to this layouter.
auto hasExplicitSnap(LayoutHandle handle) const -> bool: Whether the layout has an explicit snap.
auto hasExplicitSnap(LayouterDataHandle handle) const -> bool: Whether the layout has an explicit snap assuming it belongs to this layouter.
auto parent(LayoutHandle handle) const -> LayoutHandle: Parent layout.
auto parent(LayouterDataHandle handle) const -> LayoutHandle: Parent layout assuming it belongs to this layouter.
auto previous(LayoutHandle handle) const -> LayoutHandle: Previous layout.
auto previous(LayouterDataHandle handle) const -> LayoutHandle: Previous layout assuming it belongs to this layouter.
auto next(LayoutHandle handle) const -> LayoutHandle: Next layout.
auto next(LayouterDataHandle handle) const -> LayoutHandle: Next sibling layout assuming it belongs to this layouter.
auto explicitSnap(LayoutHandle handle) const -> Snaps: Explicit layout snap.
auto explicitSnap(LayouterDataHandle handle) const -> Snaps: Explicit layout snap assuming it belongs to this layouter.
auto explicitSnapTarget(LayoutHandle handle) const -> LayoutHandle: Explicit layout snap target.
auto explicitSnapTarget(LayouterDataHandle handle) const -> LayoutHandle: Explicit layout snap target node assuming it belongs to this layouter.

Function documentation

Magnum::Ui::SnapLayouter::SnapLayouter(LayouterHandle handle) explicit

Constructor.

Parameters
handle	Layouter handle returned from AbstractUserInterface::createLayouter()

Magnum::Ui::SnapLayouter::SnapLayouter(SnapLayouter&&) noexcept

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

LayoutHandle Magnum::Ui::SnapLayouter::add(NodeHandle node, LayoutHandle before = LayoutHandle::Null, SnapLayoutFlags flags = {})

Add a layout assigned to given node.

Parameters
node	Node to assign the layout to
before	A layout to order before or LayoutHandle::Null if ordered as last
flags	Layout flags
Returns	New layout handle

The node is expected to not have a layout assigned from this layouter yet. If before is not LayoutHandle::Null, it's expected to be valid, belong to the same layouter and have the same non-null parent layout as node.

If node parent has a layout coming from this layouter, the positioning is done according to childSnap() defined by the parent layout, and the total size and padding of all child layouts then affects parent layout size and padding according to flags. If node parent doesn't have a layout coming from this layouter, the layout acts as a parent for child layouts or as a target for explicitly snapped layouts and isn't affected by layout calculation.

Use add(NodeHandle, Snaps, LayoutHandle, SnapLayoutFlags) for explicitly snapping to given layout without taking childSnap() into account and without affecting the parent layout size.

Delegates to AbstractLayouter::add(), see its documentation for detailed description of all constraints.

LayoutHandle Magnum::Ui::SnapLayouter::add(NodeHandle node, SnapLayoutFlags flags)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

LayoutHandle Magnum::Ui::SnapLayouter::add(NodeHandle node, LayouterDataHandle before, SnapLayoutFlags flags = {})

Add a layout assigned to given node, and before given layout assuming the layout belongs to this layouter.

Like add(NodeHandle, LayoutHandle, SnapLayoutFlags) but without checking that before indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::add(NodeHandle node, Snaps snap, LayoutHandle snapTarget, SnapLayoutFlags flags = {})

Add a layout snapping explicitly to given target.

Parameters
node	Node to assign the layout to
snap	How to snap
snapTarget	Target layout to snap to or LayoutHandle::Null to snap a root `node` to the UI itself
flags	Layout flags
Returns	New layout handle

If node is root, snapTarget can be LayoutHandle::Null to snap to the whole UI. Otherwise snapTarget is expected to be coming from the same layouter and assigned to either a parent or a sibling of node. If snapTarget is a parent, Snap::Inside is implicitly used in addition to what's specified in snap.

Note that explicitly snapped layouts aren't considered in any way when calculating parent layout sizes and paddings and thus may overflow the parent node area. Use add(NodeHandle, LayoutHandle, SnapLayoutFlags) for implicit child layouts which then propagate their total size and margin to the parent.

Delegates to AbstractLayouter::add(), see its documentation for detailed description of all constraints.

LayoutHandle Magnum::Ui::SnapLayouter::add(NodeHandle node, Snaps snap, LayouterDataHandle snapTarget, SnapLayoutFlags flags = {})

Add a layout snapping explicitly to given target, assuming the target belongs to this layouter.

Like add(NodeHandle, Snaps, LayoutHandle, SnapLayoutFlags) but without checking that snapTarget indeed belongs to this layouter. See its documentation for more information.

void Magnum::Ui::SnapLayouter::remove(LayoutHandle handle)

Remove a layout.

Expects that handle is valid and has no child layouts or explicitly snapped layouts from the same layouter. To remove a layout that has dependent layouts, either remove the dependent layouts first or remove the whole node along with its children using Ui::AbstractUserInterface::removeNode().

Delegates to AbstractLayouter::remove(LayoutHandle), see its documentation for detailed description of all constraints.

void Magnum::Ui::SnapLayouter::remove(LayouterDataHandle handle)

Remove a layout assuming it belongs to this layer.

Compared to remove(LayoutHandle) delegates to AbstractLayouter::remove(LayouterDataHandle) instead.

SnapLayoutFlags Magnum::Ui::SnapLayouter::flags(LayoutHandle handle) const

Layout flags.

Expects that handle is valid.

SnapLayoutFlags Magnum::Ui::SnapLayouter::flags(LayouterDataHandle handle) const

Layout flags assuming it belongs to this layouter.

Like flags(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

void Magnum::Ui::SnapLayouter::setFlags(LayoutHandle handle, SnapLayoutFlags flags)

Set layout flags.

Expects that handle is valid. Initially, a layout has the flags that were passed to add(), which are by default none.

Calling this function causes LayouterState::NeedsUpdate to be set.

void Magnum::Ui::SnapLayouter::setFlags(LayouterDataHandle handle, SnapLayoutFlags flags)

Set layout flags assuming it belongs to this layouter.

Like setFlags(LayoutHandle, SnapLayoutFlags) but without checking that handle indeed belongs to this layouter. See its documentation for more information.

void Magnum::Ui::SnapLayouter::addFlags(LayoutHandle handle, SnapLayoutFlags flags)

Add layout flags.

Calls setFlags() with the existing flags ORed with flags. Useful for preserving previously set flags.

void Magnum::Ui::SnapLayouter::addFlags(LayouterDataHandle handle, SnapLayoutFlags flags)

Add layout flags assuming it belongs to this layouter.

Like addFlags(LayoutHandle, SnapLayoutFlags) but without checking that handle indeed belongs to this layouter. See its documentation for more information.

void Magnum::Ui::SnapLayouter::clearFlags(LayoutHandle handle, SnapLayoutFlags flags)

Clear layout flags.

Calls setFlags() with the existing flags ANDed with the inverse of flags. Useful for removing a subset of previously set flags.

void Magnum::Ui::SnapLayouter::clearFlags(LayouterDataHandle handle, SnapLayoutFlags flags)

Clear layout flags assuming it belongs to this layouter.

Like addFlags(LayoutHandle, SnapLayoutFlags) but without checking that handle indeed belongs to this layouter. See its documentation for more information.

Snaps Magnum::Ui::SnapLayouter::childSnap(LayoutHandle handle) const

Snap for child layouts.

Expects that handle is valid.

Snaps Magnum::Ui::SnapLayouter::childSnap(LayouterDataHandle handle) const

Snap for child layouts assuming it belongs to this layouter.

Like childSnap(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

void Magnum::Ui::SnapLayouter::setChildSnap(LayoutHandle handle, Snaps snap)

Set snap for child layouts.

Expects that handle is valid and that snap produces a non-overlapping purely horizontal or vertical order. Default is Snap::Bottom, i.e. child nodes get placed one after each other in a column.

Calling this function causes LayouterState::NeedsUpdate to be set.

void Magnum::Ui::SnapLayouter::setChildSnap(LayouterDataHandle handle, Snaps snap)

Set snap for child layouts assuming it belongs to this layouter.

Like setChildSnap(LayouterDataHandle, Snaps) but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::firstChild(LayoutHandle handle) const

First child layout.

Expects that handle is valid. If the layout has no children or if all nested layouts have an explicit snap, returns LayoutHandle::Null. Otherwise, the handle is always valid and belonging to this layouter.

LayoutHandle Magnum::Ui::SnapLayouter::firstChild(LayouterDataHandle handle) const

First child layout assuming it belongs to this layouter.

Like firstChild(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::firstExplicitSnap(LayoutHandle handle) const

First layout explicitly snapped to this one.

Expects that handle is valid. If no other layouts are explicitly snapped to this layout, returns LayoutHandle::Null. Otherwise, the handle is always valid and belonging to this layouter.

LayoutHandle Magnum::Ui::SnapLayouter::firstExplicitSnap(LayouterDataHandle handle) const

First layout explicitly snapped to this one assuming it belongs to this layouter.

Like firstExplicitSnap(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

bool Magnum::Ui::SnapLayouter::hasExplicitSnap(LayoutHandle handle) const

Whether the layout has an explicit snap.

Expects that handle is valid. Returns true if the layout was created using add(NodeHandle, Snaps, LayoutHandle, SnapLayoutFlags), false otherwise.

bool Magnum::Ui::SnapLayouter::hasExplicitSnap(LayouterDataHandle handle) const

Whether the layout has an explicit snap assuming it belongs to this layouter.

Like hasExplicitSnap(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::parent(LayoutHandle handle) const

Parent layout.

Expects that handle is valid and doesn't have an explicit snap. Layouts with an explicit snap are not following any parent/child hierarchy. If there was no layout assigned to the parent node at the time handle was created, or handle is assigned to a root node, returns LayoutHandle::Null. Otherwise, the handle is always valid and belonging to this layouter.

LayoutHandle Magnum::Ui::SnapLayouter::parent(LayouterDataHandle handle) const

Parent layout assuming it belongs to this layouter.

Like parent(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::previous(LayoutHandle handle) const

Previous layout.

Expects that handle is valid. If the handle doesn't have an explicit snap, returns a previous sibling with the same parent() in layout order. If the handle has an explicit snap, returns a previous layout with the same explicitSnapTarget(), but their relative order doesn't affect the layouting result in any way. If the layout is first in given list, returns LayoutHandle::Null. Otherwise, the handle is always valid and belonging to this layouter.

LayoutHandle Magnum::Ui::SnapLayouter::previous(LayouterDataHandle handle) const

Previous layout assuming it belongs to this layouter.

Like previous(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::next(LayoutHandle handle) const

Next layout.

Expects that handle is valid. If the handle doesn't have an explicit snap, returns a next sibling with the same parent() in layout order. If the handle has an explicit snap, returns a next layout with the same explicitSnapTarget(), but their relative order doesn't affect the layouting result in any way. If the layout is last among its siblings, returns LayoutHandle::Null. Otherwise, the handle is always valid and belonging to this layouter.

LayoutHandle Magnum::Ui::SnapLayouter::next(LayouterDataHandle handle) const

Next sibling layout assuming it belongs to this layouter.

Like next(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

Snaps Magnum::Ui::SnapLayouter::explicitSnap(LayoutHandle handle) const

Explicit layout snap.

Expects that handle is valid and has an explicit snap. Note that if explicitSnapTarget() is NodeHandle::Null, Snap::Inside is implicitly considered to be included as well, even if not part of the actual value.

Similarly to node() and explicitSnapTarget(), the snap cannot be changed after creation as it could break internal constraints.

Snaps Magnum::Ui::SnapLayouter::explicitSnap(LayouterDataHandle handle) const

Explicit layout snap assuming it belongs to this layouter.

Like explicitSnap(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.

LayoutHandle Magnum::Ui::SnapLayouter::explicitSnapTarget(LayoutHandle handle) const

Explicit layout snap target.

Expects that handle is valid and has an explicit snap. Returns LayoutHandle::Null if the layout is assigned to a root node and is snapped relative to the whole user interface. Note that the returned handle may be invalid if AbstractUserInterface::removeNode() was called on the target node or its parents and AbstractUserInterface::update() hasn't been called since.

Similarly to node() and explicitSnap(), the target cannot be changed after creation as it could break internal constraints.

LayoutHandle Magnum::Ui::SnapLayouter::explicitSnapTarget(LayouterDataHandle handle) const

Explicit layout snap target node assuming it belongs to this layouter.

Like explicitSnapTarget(LayoutHandle) const but without checking that handle indeed belongs to this layouter. See its documentation for more information.