Customizable lists display. More...

#include <AUI/View/AForEachUI.h>

Public Types#
using	List = AForEachUIBase::List

using	ListFactory = std::function<List()>

using	ViewFactory = std::function<_<AView>(const T& value)>

Public Types inherited from AForEachUIBase
using	List = aui::any_view<Entry>

Public Member Functions#
template<aui::detail::RangeFactory< T > RangeFactory>
	AForEachUI (RangeFactory &&rangeFactory)

template<aui::detail::RangeFactory< T > RangeFactory>
void	setModel (RangeFactory &&rangeFactory)

template<aui::invocable< const T & > ViewFactoryT>
void	operator- (ViewFactoryT &&f)

void	invalidate () override
	Notifies that range was changed or iterators might have invalidated.

void	setLayout (_unique< ALayout > layout)
	Set new layout manager for this AViewContainerBase. DESTROYS OLD LAYOUT MANAGER WITH ITS VIEWS!!!

Public Member Functions inherited from AForEachUIBase
void	setPosition (glm::ivec2 position) override

Public Member Functions inherited from AViewContainerBase
void	render (ARenderContext context) override
	Draws this AView. Noone should call this function except rendering routine.

void	onMouseEnter () override

void	onPointerMove (glm::vec2 pos, const APointerMoveEvent &event) override
	Handles pointer hover events.

void	onMouseLeave () override

void	onDpiChanged () override

void	onClickPrevented () override
	Called on AWindowBase::preventClickOnPointerRelease.

int	getContentMinimumWidth () override

int	getContentMinimumHeight () override

void	onPointerPressed (const APointerPressedEvent &event) override
	Called on pointer (mouse) released event.

void	onPointerDoubleClicked (const APointerPressedEvent &event) override

void	onPointerReleased (const APointerReleasedEvent &event) override
	Called on pointer (mouse) released event.

void	onScroll (const AScrollEvent &event) override

bool	onGesture (const glm::ivec2 &origin, const AGestureEvent &event) override

bool	consumesClick (const glm::ivec2 &pos) override
	Determines whether this AView processes this click or passes it thru.

void	setSize (glm::ivec2 size) override

void	setEnabled (bool enabled=true) override

auto	begin () const

auto	end () const

const AVector< _< AView > > &	getViews () const
	Get all views of the container.

const _unique< ALayout > &	getLayout () const noexcept
	Get layout manager of the container.

virtual _< AView >	getViewAt (glm::ivec2 pos, ABitField< AViewLookupFlags > flags=AViewLookupFlags::NONE) const noexcept
	Finds first direct child view under position.

_< AView >	getViewAtRecursive (glm::ivec2 pos, ABitField< AViewLookupFlags > flags=AViewLookupFlags::NONE) const noexcept
	Acts as AViewContainerBase::getViewAt but recursively (may include non-direct child).

template<aui::predicate< _< AView > > Callback>
bool	getViewAtRecursive (glm::ivec2 pos, const Callback &callback, ABitField< AViewLookupFlags > flags=AViewLookupFlags::NONE)
	Acts as AViewContainerBase::getViewAtRecursive but calls a callback instead of returning value.

template<aui::predicate< _< AView > > Callback>
bool	visitsViewRecursive (Callback &&callback, ABitField< AViewLookupFlags > flags=AViewLookupFlags::NONE)
	Performs recursive view traversal.

template<typename T>
_< T >	getViewAtRecursiveOfType (glm::ivec2 pos, ABitField< AViewLookupFlags > flags=AViewLookupFlags::NONE)
	Acts as AViewContainerBase::getViewAtRecursive but finds a view castable to specified template type.

void	setFocusChainTarget (_weak< AView > target)
	Set focus chain target.

_< AView >	focusChainTarget ()

void	applyGeometryToChildrenIfNecessary ()
	Applies geometry to all children if needed.

void	onKeyDown (AInput::Key key) override

void	onKeyRepeat (AInput::Key key) override

void	onKeyUp (AInput::Key key) override

void	onCharEntered (char16_t c) override

bool	capturesFocus () override

const ASmallVector< PointerEventsMapping, 1 > &	pointerEventsMapping () const noexcept

void	forceUpdateLayoutRecursively () override

void	markMinContentSizeInvalid () override
	Marks this view it requires a layout update.

void	markPixelDataInvalid (ARect< int > invalidArea) override
	A view requests to redraw it and passes it's coords relative to this.

Public Member Functions inherited from AView
auto	enabled () const
	Whether view is enabled (i.e., reacts to user).

auto	position () const
	Top left corner's position relative to top left corner's position of the parent AView.

auto	size () const
	Size, including content area, border and padding.

auto	expanding () const
	Expansion coefficient. Hints layout manager how much this AView should be extended relative to other AViews in the same container.

auto	visibility () const
	Visibility value.

void	redraw ()
	Request window manager to redraw this AView.

AWindowBase *	getWindow () const
	Determines window which this AView belongs to.

virtual void	drawStencilMask (ARenderContext ctx)

virtual void	postRender (ARenderContext ctx)
	Performs post-draw routines of this AView. Noone should call this function except rendering routine.

void	popStencilIfNeeded (ARenderContext ctx)

const AVector< AString > &	getAssNames () const noexcept

glm::ivec2	getPosition () const noexcept
	Top left corner's position relative to top left corner's position of the parent AView.

glm::ivec2	getCenterPointInWindow () const noexcept
	The center point position of the view relatively to top left corner of the window.

glm::ivec2	getSize () const noexcept
	Size, including content area, border and padding.

glm::ivec2	getMinSize () const noexcept

void	setMinSize (glm::ivec2 minSize) noexcept

void	setExtraStylesheet (_< AStylesheet > extraStylesheet)

void	setExtraStylesheet (AStylesheet &&extraStylesheet)

const _< AStylesheet > &	extraStylesheet () const noexcept

AOverflow	getOverflow () const
	Determines whether display graphics that go out of the bounds of this AView or not.

void	setOverflow (AOverflow overflow)

AOverflowMask	getOverflowMask () const
	Controls how does the overflow (stencil) mask is produced.

void	setOverflowMask (AOverflowMask overflow)

float	getBorderRadius () const
	border-radius, specified in ASS.

void	setBorderRadius (float radius)

int	getWidth () const

int	getHeight () const

int	getTotalOccupiedWidth () const

int	getTotalOccupiedHeight () const

glm::ivec2	getMinimumSizePlusMargin ()

const ABoxFields &	getMargin ()
	Returns the margin.

void	setMargin (const ABoxFields &margin)
	Sets the margin.

const ABoxFields &	getPadding ()
	Returns the padding.

void	setPadding (const ABoxFields &padding)
	Sets the padding.

virtual AString	debugString () const
	String which helps to identify this object in debug string output (i.e., for logging)

int	getTotalFieldHorizontal () const

int	getTotalFieldVertical () const

glm::ivec2	getTotalFieldSize () const

AViewContainerBase *	getParent () const
	Parent AView.

const AOptional< ACursor > &	getCursor () const
	Determines shape which should pointer take when it's above this AView.

void	setCursor (AOptional< ACursor > cursor)

glm::ivec2	getContentMinimumSize () noexcept

bool	isContentMinimumSizeInvalidated () noexcept

bool	hasFocus () const

virtual int	getMinimumWidth ()

virtual int	getMinimumHeight ()

glm::ivec2	getMinimumSize ()
	Returns the minimum size required for this view.

void	setMaxSize (const glm::ivec2 &maxSize)

const glm::ivec2 &	getMaxSize () const

glm::ivec2	getContentSize () const

int	getContentWidth () const

int	getContentHeight () const

const glm::ivec2 &	getExpanding () const

void	setExpanding (glm::ivec2 expanding)
	Changes the expanding of view.

void	setExpanding (int expanding)
	Changes the expanding of view.

void	setExpanding ()

const _< AAnimator > &	getAnimator () const

void	setAnimator (const _< AAnimator > &animator)

void	getTransform (glm::mat4 &transform) const

int	getExpandingHorizontal () const

int	getExpandingVertical () const

aui::float_within_0_1	getOpacity () const

void	setOpacity (aui::float_within_0_1 opacity)

void	setSizeForced (glm::ivec2 size)

virtual void	setGeometry (int x, int y, int width, int height)
	Sets position and size of the view.

void	setGeometry (const glm::ivec2 &position, const glm::ivec2 &size)

bool	isBlockClicksWhenPressed () const noexcept

void	setBlockClicksWhenPressed (bool value) noexcept

const glm::ivec2 &	getFixedSize ()
	Fixed size.

void	setFixedSize (glm::ivec2 size)

bool	isMouseHover () const noexcept

bool	isPressed () const noexcept

bool	isPressed (APointerIndex index) const noexcept

bool	isFocused () const

bool	isMouseEntered () const

Visibility	getVisibility () const

Visibility	getVisibilityRecursive () const

void	setVisibility (Visibility visibility) noexcept

void	setVisible (bool visible) noexcept

MouseCollisionPolicy	getMouseCollisionPolicy () const

void	setMouseCollisionPolicy (MouseCollisionPolicy mouseCollisionPolicy)

void	click ()

void	pack ()
	Sets minimal size.

void	focus (bool needFocusChainUpdate=true)
	Requests focus for this AView.

bool	hasIndirectParent (const _< AView > &v)
	Checks if the specified view is an indirect parent of this view.

glm::ivec2	getPositionInWindow () const

void	addAssName (const AString &assName)
	Adds an ASS class to this AView.

void	removeAssName (const AString &assName)
	Removes an ASS class to this AView.

void	setAssName (const AString &assName, bool value)
	Depending on value, either adds or removes ass name.

AView &	operator<< (const AString &assName)

const _< AAssHelper > &	getAssHelper () const

const ass::PropertyListRecursive &	getCustomAss () const

void	setCustomStyle (ass::PropertyListRecursive rule)

void	ensureAssUpdated ()

_< AView >	sharedPtr ()

_weak< AView >	weakPtr ()

virtual void	onFocusAcquired ()

virtual void	onFocusLost ()

virtual bool	handlesNonMouseNavigation ()

void	setDisabled (bool disabled=true)

void	updateEnableState ()

void	enable ()

void	disable ()

void	operator& (ass::PropertyListRecursive rule)
	Helper function for kAUI.h:with_style.

void	invalidateStateStyles ()
	Updates state selectors for ASS.

virtual bool	wantsTouchscreenKeyboard ()
	Returns true if view is textfield-like view which requires touchscreen keyboard when clicked.

void	setSkipUntilLayoutUpdate (bool skipUntilLayoutUpdate)

void	setFloating (AFloat f) noexcept
	Set floating value for AText.

AFloat	getFloating () const noexcept
	Floating value for AText.

Public Member Functions inherited from AObject
_< AObject >	sharedPtr ()

_weak< AObject >	weakPtr ()

template<typename Connectable, ACompatibleSlotFor< Connectable > Function>
decltype(auto)	connect (const Connectable &connectable, Function &&function)
	Connects signal or property to slot of `"this"` object.

void	setSignalsEnabled (bool enabled)

bool	isSignalsEnabled () const noexcept

template<ASignalInvokable T>
void	operator^ (T &&t) noexcept

const _< AAbstractThread > &	getThread () const noexcept

bool	isSlotsCallsOnlyOnMyThread () const noexcept

void	setSlotsCallsOnlyOnMyThread (bool slotsCallsOnlyOnMyThread)

Public Member Functions inherited from AObjectBase
	AObjectBase (AObjectBase &&rhs) noexcept

	AObjectBase (const AObjectBase &rhs) noexcept

AObjectBase &	operator= (const AObjectBase &rhs) noexcept

AObjectBase &	operator= (AObjectBase &&rhs) noexcept

Public Member Functions inherited from aui::noncopyable
	noncopyable (const noncopyable &)=delete

noncopyable &	operator= (const noncopyable &)=delete

Protected Member Functions#
aui::for_each_ui::detail::ViewsSharedCache *	getViewsCache () override
	Returns a cache of views, if any.

Protected Member Functions inherited from AForEachUIBase
void	onViewGraphSubtreeChanged () override
	Called when direct or indirect parent has changed.

void	applyGeometryToChildren () override
	Applies geometry to all children with no preconditions.

void	setModelImpl (List model)
	Notifies that range was changed or iterators might have invalidated.

Protected Member Functions inherited from AViewContainerBase
void	drawView (const _< AView > &view, ARenderContext contextOfTheContainer)

template<typename Iterator>
void	drawViews (Iterator begin, Iterator end, ARenderContext contextPassedToContainer)

void	invalidateAllStyles () override
	Invalidates all styles, causing to iterate over all rules in global and parent stylesheets.

void	onViewGraphSubtreeChanged () override
	Called when direct or indirect parent has changed.

void	invalidateAssHelper () override
	Resets mAssHelper.

void	setViews (AVector< _< AView > > views)
	Replace views.

void	addViewCustomLayout (const _< AView > &view)
	Adds view to container without exposing it to the layout manager.

void	addViews (AVector< _< AView > > views)
	Add all views from vector.

void	addView (const _< AView > &view)
	Add view to the container.

void	addView (size_t index, const _< AView > &view)
	Add view at specific index to the container.

void	removeViews (aui::range< AVector< _< AView > >::const_iterator > views)
	Remove views from the container.

void	removeView (const _< AView > &view)
	Remove view from the container.

void	removeView (AView *view)
	Remove view from the container.

void	removeView (size_t index)
	Remove view from the container at specified index.

void	removeAllViews ()
	Remove all views from container.

void	setContents (const _< AViewContainer > &container)
	Moves (like via std::move) all children and layout of the specified container to this container.

void	setLayout (_unique< ALayout > layout)
	Set new layout manager for this AViewContainerBase. DESTROYS OLD LAYOUT MANAGER WITH ITS VIEWS!!!

void	renderChildren (ARenderContext contextPassedToContainer)

Protected Member Functions inherited from AView
bool	transformGestureEventsToDesktop (const glm::ivec2 &origin, const AGestureEvent &event)
	Converts touch screen events to desktop.

void	applyAssRule (const ass::PropertyList &propertyList)

void	applyAssRule (const ass::PropertyListRecursive &propertyList)

virtual AMenuModel	composeContextMenu ()
	Produce context (right click) menu.

virtual void	commitStyle ()

Protected Member Functions inherited from AObject
void	setThread (_< AAbstractThread > thread)
	Set thread of the object.

Protected Member Functions inherited from AObjectBase
void	clearAllIngoingConnections () noexcept

virtual void	handleSlotException (std::exception_ptr exception)
	Called then an exception has thrown during slot processing of the signal emitted by this object.

Additional Inherited Members#
Static Public Member Functions inherited from AObject
static void	disconnect ()

template<AAnySignal Signal, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Signal > Function>
static decltype(auto)	connect (const Signal &signal, Object *object, Function &&function)
	Connects signal to the slot of the specified object.

template<AAnyProperty Property, aui::derived_from< AObjectBase > Object, typename Function>
static decltype(auto)	connect (const Property &property, Object *object, Function &&function)
	Connects property to the slot of the specified object.

template<APropertyReadable PropertySource, APropertyWritable PropertyDestination> requires requires { { propertySource } -> aui::convertible_to<std::decay_t<decltype(propertyDestination)>>; }
static void	connect (PropertySource &&propertySource, PropertyDestination &&propertyDestination)
	Connects source property to the destination property.

template<APropertyWritable PropertySource, APropertyWritable PropertyDestination> requires requires { { propertySource } -> aui::convertible_to<std::decay_t<decltype(propertyDestination)>>; { propertyDestination } -> aui::convertible_to<std::decay_t<decltype(propertySource)>>; }
static void	biConnect (PropertySource &&propertySource, PropertyDestination &&propertyDestination)
	Connects source property to the destination property and opposite (bidirectionally).

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Connectable > Function>
static decltype(auto)	connect (const Connectable &connectable, Object &object, Function &&function)
	Connects signal or property to the slot of the specified object.

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Connectable > Function>
static decltype(auto)	connect (const Connectable &connectable, _< Object > object, Function &&function)
	Connects signal or property to the slot of the specified object.

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, typename Function>
static decltype(auto)	connect (const Connectable &connectable, ASlotDef< Object *, Function > slotDef)
	Connects signal to the slot of the specified object. Slot is packed to single argument.

template<AAnyProperty Property, typename Object, ACompatibleSlotFor< Property > Function> requires (!aui::derived_from<Object, AObject>)
static void	connect (const Property &property, _< Object > object, Function &&function)
	Connects signal or property to the slot of the specified non-AObject type.

static void	moveToThread (aui::no_escape< AObject > object, _< AAbstractThread > thread)

Signals and public fields inherited from AViewContainerBase
emits	childrenChanged
	Emitted when addView(s)/removeView/setLayout was called.

Signals and public fields inherited from AView
emits	viewGraphSubtreeChanged

emits	redrawn
	View is painted onto the some surface.

emits< bool >	hoveredState

emits	mouseEnter

emits	mouseLeave

emits< bool, APointerIndex >	pressedState

emits< APointerIndex >	pressed

emits< APointerIndex >	released

emits< APointerIndex >	clickedButton
	Some mouse button clicked.

emits	clicked
	Left mouse button clicked.

emits< glm::ivec2, glm::ivec2 >	geometryChanged
	Geometry (position and size) changed.

emits< glm::ivec2 >	scrolled
	Scroll event.

emits< AInput::Key >	keyPressed
	Keyboard key pressed.

emits< AInput::Key >	keyReleased
	Keyboard key released.

emits	clickedRight
	Right mouse button clicked.

emits	clickedRightOrLongPressed
	Right mouse button clicked or long press gesture applied.

emits< APointerIndex >	doubleClicked

emits	customCssPropertyChanged

emits< bool >	focusState
	Focus state changed.

emits	focusAcquired

emits	focusLost

emits< _< AView > >	childFocused

Static Public Attributes inherited from AObject
static constexpr AObjectBase *	GENERIC_OBSERVER = nullptr
	Indicates that a connection should not be explicitly linked to receiver's lifetime.

Static Public Attributes inherited from AObjectBase
static ASpinlockMutex	SIGNAL_SLOT_GLOBAL_SYNC

Protected Attributes inherited from AForEachUIBase
AOptional< Cache >	mCache

Protected Attributes inherited from AViewContainerBase
bool	mWantsLayoutUpdate = true

glm::ivec2	mLastLayoutUpdateSize {0, 0}

Protected Attributes inherited from AView
AViewContainerBase *	mParent = nullptr
	Parent AView.

std::array< ass::prop::IPropertyBase *, int(ass::prop::PropertySlot::COUNT)>	mAss
	Drawing list, or baking drawing commands so that you don't have to parse the ASS every time.

ass::PropertyListRecursive	mCustomStyleRule
	Custom ASS Rules.

AOptional< ACursor >	mCursor = ACursor::DEFAULT
	Determines shape which should pointer take when it's above this AView.

glm::ivec2	mPosition = { 0, 0 }
	Top left corner's position relative to top left corner's position of the parent AView.

emits< glm::ivec2 >	mPositionChanged
	Position changed.

glm::ivec2	mSize = { 20, 20 }
	Size, including content area, border and padding.

emits< glm::ivec2 >	mSizeChanged
	Size changed.

AOptional< glm::ivec2 >	mCachedMinContentSize

bool	mMarkedMinContentSizeInvalid = false

bool	mRedrawRequested = false
	Redraw requested flag for this particular view/.

glm::ivec2	mMinSize = {0, 0}
	Minimal size.

glm::ivec2	mMaxSize = {0x7fffffff, 0x7fffffff}
	Maximal size.

glm::ivec2	mFixedSize = {0, 0}
	Fixed size.

ABoxFields	mMargin
	Margin, which defines the spacing around this AView. Processed by the layout manager.

ABoxFields	mPadding
	Padding, which defines the spacing around content area inside the view. Processed by AView implementation.

AVector< AString >	mAssNames
	ASS class names.

bool	mSkipUntilLayoutUpdate = true
	If set to true, AViewContainer is obligated ignore this view. This value is set to false by AView::setGeometry.

Detailed Description#

template<typename T>
class AForEachUI< T >

Used to lazily present possibly large or infinite linear non-hierarchical sequences of data.

Warning: This API is experimental. Experimental APIs are likely to contain bugs, might be changed or removed in the future.

Note: If you are familiar with RecyclerView/LazyColumn/LazyRow/LazyVStack/LazyHStack, AForEachUI follows the same set of principles; with an exception: AForEachUI does not provide a scrollable area on its own.

AForEachUI is created by using AUI_DECLARATIVE_FOR macro.

AUI_DECLARATIVE_FOR mimics ranged for loop semantically.

static const std::array users = { "Foo", "Bar", "Lol" };
for (const auto& user : users) {
  fmt::println("{}", user);
}

static const std::array users = { "Foo", "Bar", "Lol" };
...
setContents(Centered {
  AScrollArea::Builder().withContents(
    AUI_DECLARATIVE_FOR(user, users, AVerticalLayout) {
      return Label { fmt::format("{}", user) };
    }
  ).build() with_style { FixedSize { 150_dp, 200_dp } },
});

AUI_DECLARATIVE_FOR consists of single entry variable name, a potentially reactive expression evaluating to range, layout name (acceptable are AVerticalLayout and AHorizontalLayout) and a lambda that creates a new view based on data entry. In terms of C++ syntax, the lambda is partially defined by AUI_DECLARATIVE_FOR macro; the lambda's body (including curly braces) is left up to developer. The final declaration of AUI_DECLARATIVE_FOR returns an instance of AForEachUI.

range models one-dimensional list.

AForEachUI works on iterator level by design. In fact, any kind of range (C++20 ranges/range-v3) can be used, starting from bidirectional containers such as std::vector and std::list, lazy non-owning dummies like ranges::views::ints and even fancy range views from std::ranges::views or ranges::views are acceptable. One-directional containers like std::queue or std::stack can't be used because they don't implement begin() and end(). As such, requirements to a range are dictated by ranges::range concept.

range has .begin() method or ranges::begin() overload defined auto it = ranges::begin(rng)
range has .end() method or ranges::end() overload defined auto it = ranges::end(rng)
both begin() and end() return an iterator
iterator has dereference operator auto& value = *it
iterator has increment operator ++it

Alternatively, these requirements can be described by a ranged for loop: for (const auto& value : rng) { ... }.

The range's type is erased with runtime-based range layer aui::any_view.

AUI_DECLARATIVE_FOR can be nested with no restrictions in both directions.

Examples#

See examples of AUI_DECLARATIVE_FOR.

Lazy Semantics#

AForEachUI presents all data available. If placed somewhere inside AScrollArea (implies AScrollAreaViewport), lazy semantics take place. This means that AForEachUI knows scroll position and sliding window size in pixels, making it possible to present a limited set of data that is actually visible, and present data further as soon as the user scrolls down the scroll area.

Under the hood, AForEachUI stores a pair of iterators of the passed range of presented entries, forming a sliding window subrange. When the user scrolls down the list, both iterators are incremented; when the user scrolls upwards, both iterators are decremented.

In this scenario, AForEachUI adds an extra requirement to range's iterator:

iterator has decrement operator --it

If this requirement is not satisfied (case of some ranges::views), AForEachUI would not unload old items, unless a data update event occurred.

The amount of displayed data is governed by range size, Render to texture tile size, AScrollArea's viewport size and individual entry size. Optimal frequency of sliding during scroll and window size are determined by AForEachUI. In particular, the sliding is performed once per Render to texture tile is passed.

Note: During rendering inside AScrollArea, the renderer clips visible views more precisely; the goal of lazy semantics of AForEachUI is to optimize view instantiation and layout processing overhead, as well as range views' lazy semantics, thanks to iterators.

Scrollbars#

From perspective of layout, lazy semantics is implemented by careful layout updates driven by scroll area events. If possible, the items that appear far from sliding window are unloaded (views are removed). The new items are loaded (new views are instantiated). To avoid content jittering, scroll position is synced with layout updates within AForEachUI. As such, these hijacking operations may confuse scroll bar.

In modern software, especially when it comes to infinite lists in web/mobile applications (i.e., news feed), scrollbar might be completely hidden or significantly transparentized.

This optimization gives a severe performance benefit. Despite the fact that there's a complete mess "under the hood" (scrollbar is the only visual confirmation), the scrolled contents appear normal and natural.

A lie is going on behind the scenes

A static range like in the example above will not blow up the machine because AForEachUI is wrapped with a AScrollArea, thus it is not required to evaluate the whole range, which is infinite in our case.

An attempt to update AForEachUI with a large range still can lead to high resource consumption, due to need of recomposition.

Initialization#

This section explains how to initialize AUI_DECLARATIVE_FOR, manage lifetime of containers and how to make them reactive.

In AUI_DECLARATIVE_FOR, a potentially reactive expression evaluating to range and the lambda that creates a new views are both lambdas with capture default by value [=]. This means that:

All mentioned local variables are captured by copying.
All mentioned class member variables (fields) are captured by reference.

Both lambdas can be evaluated at any point during lifetime of a AForEachUI, so the by-value capture makes it's hard to introduce dangling references, by either copying locals or referencing class members.

Most modern compilers are capable to optimize out copying and initialize *copied* locals just in place.

An attempt to go out of the scenarios listed below will likely lead to a static_assert with a link to this section.

Constant global data#

The most straightforward way is using constant global data:

static constexpr auto COLORS = { "Red", "Green", "Blue", "Black", "White" };
 
class MyWindow: public AWindow {
public:
    MyWindow() {
        setContents(Vertical {
            AUI_DECLARATIVE_FOR(i, COLORS, AVerticalLayout) {
              return Label { "{}"_format(i) };
            }
        });
    }
};
AUI_ENTRY {
  auto w = _new<MyWindow>();
  w->show();
  return 0;
}

It's a good idea to wrap AForEachUI with an AScrollArea.

setContents(Vertical {
    AScrollArea::Builder()
        .withContents(
            AUI_DECLARATIVE_FOR(i, COLORS, AVerticalLayout) {
              return Label { "{}"_format(i) };
            })
        .build() with_style { FixedSize { 150_dp, 200_dp } },
});

Infinite ranges and views#

Most generators, ranges and views are expected to work.

setContents(Vertical {
    AScrollArea::Builder().withContents(
        AUI_DECLARATIVE_FOR(i, ranges::views::ints, AVerticalLayout) {
            return Label { "{}"_format(i) };
        }
    ).build() with_style { FixedSize { 150_dp, 200_dp } },
});

Transferring ownership by copying#

When using locals, their immediate values are copied during initialization of AUI_DECLARATIVE_FOR.

auto items = AVector<AString> { "Hello", "World", "Test" };
setContents(Vertical {
    AScrollArea::Builder().withContents(
        AUI_DECLARATIVE_FOR(i, items, AVerticalLayout) {
           return Label { i };
        }
    ).build() with_style { FixedSize { 150_dp, 200_dp } },
});

As such, an attempt to modify items will not reflect on presentation, because it has own copy of items.

items.push_back("Bruh");

Borrowing constant containers#

If your container lives inside your class, its value is not copied but referenced. To avoid unobserved iterator invalidation and content changes, AUI_DECLARATIVE_FOR requires borrowed containers to be constant. There's a compile-time check to verify this requirement that does work in most cases, like this one.

class MyWindow: public AWindow {
public:
    MyWindow(AVector<AString> colors): mColors(std::move(colors)) {
        setContents(Vertical {
            AUI_DECLARATIVE_FOR(i, mColors, AVerticalLayout) {
              return Label { "{}"_format(i) };
            }
        });
    }
private:
    const AVector<AString> mColors;
};
AUI_ENTRY {
     auto w = _new<MyWindow>(AVector<AString>{ "Red", "Green", "Blue", "Black", "White" });
     w->show();
     return 0;
}

Marking the borrowed container as const effectively saves you from unintended borrowed data changes. If you'd like to change the container or view options and AUI_DECLARATIVE_FOR to respond to the changes, read the section below.

Reactive lists#

The reason why AUI_DECLARATIVE_FOR is so restrictive about using borrowed non-const data is because it stores range's iterators under the hood. Various containers have different rules on iterator invalidation, but, since it accepts any type of range, we consider using its iterators after a modifying access to the container or a view as unsafe:

visual presentation by AUI_DECLARATIVE_FOR might seem unresponsive to borrowed data changes,
may lead to program crash.

To address this issue, we provide a convenient way to make iterator invalidation observable:

wrap the container with AProperty,
dereference mColors in AUI_DECLARATIVE_FOR clause.

class MyWindow: public AWindow {
public:
    MyWindow(AVector<AString> colors): mColors(std::move(colors)) {
        setContents(Vertical {
            _new<AButton>("Add A new color").connect(&AView::clicked, me::addColor),
            AScrollArea::Builder().withContents(
              AUI_DECLARATIVE_FOR(i, *mColors, AVerticalLayout) {
                return Label { "{}"_format(i) };
              }
            ).build() with_style { FixedSize { 150_dp, 200_dp } },
        });
    }
private:
    AProperty<AVector<AString>> mColors;
 
    void addColor() {
        mColors.writeScope()->push_back("A new color");
    }
};
AUI_ENTRY {
    auto w = _new<MyWindow>(AVector<AString>{ "Red", "Green", "Blue", "Black", "White" });
    w->show();
    return 0;
}