Basic easy-to-use property implementation containing T. More...

#include <AUI/Common/AProperty.h>

Public Types#
using	Underlying = T

Public Member Functions#
template<aui::convertible_to< T > U>
	AProperty (U &&value) noexcept(noexcept(T(std::forward< U >(value))))

AObjectBase *	boundObject ()

const AObjectBase *	boundObject () const

	AProperty (const AProperty &value)

	AProperty (AProperty &&value) noexcept

AProperty &	operator= (const AProperty &value)

AProperty &	operator= (AProperty &&value) noexcept

template<aui::convertible_to< T > U>
AProperty &	operator= (U &&value) noexcept

template<ASignalInvokable SignalInvokable>
void	operator^ (SignalInvokable &&t)

void	notify ()
	Notify observers that a change was occurred (no preconditions).

const T &	value () const noexcept

	operator const T & () const noexcept

const T *	operator-> () const noexcept

const T &	operator* () const noexcept

aui::PropertyModifier< AProperty >	writeScope () noexcept

template<aui::invocable< const T & > Projection>
auto	readProjected (Projection &&projection) const noexcept
	Makes a readonly projection of this property.

template<aui::invocable< const T & > ProjectionRead, aui::invocable< const std::invoke_result_t< ProjectionRead, T > & > ProjectionWrite>
auto	biProjected (ProjectionRead &&projectionRead, ProjectionWrite &&projectionWrite) noexcept
	Makes a bidirectional projection of this property.

template<aui::detail::property::ProjectionBidirectional< T > Projection>
auto	biProjected (Projection &&projectionBidirectional) noexcept
	Makes a bidirectional projection of this property (by a single aui::lambda_overloaded).

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

Signals and public fields#
T	raw {}

emits< T >	changed

Additional Inherited Members#
Static Public Attributes inherited from AObjectBase
static ASpinlockMutex	SIGNAL_SLOT_GLOBAL_SYNC

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.

Detailed Description#

template<typename T>
class AProperty< T >

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

: AProperty<T> is a container holding an instance of T. You can assign a value to it with operator= and read value with value() method or implicit conversion operator T().

See property system for usage examples.

Declaration#

To declare a property inside your data model, use AProperty template:

struct User {
    AProperty<AString> name;
    AProperty<AString> surname;
};

AProperty<T> is a container holding an instance of T. You can assign a value to it with operator= and read value with value() method or implicit conversion operator T().

AProperty behaves like a class/struct data member:

User u;
u.name = "Hello";
EXPECT_EQ(u.name, "Hello");

Non-const operators have side effects; const operators don't, so you can perform seamlessly:

User u;
u.name = "Hello";
AString helloWorld = u.name + " world";
EXPECT_EQ(helloWorld, "Hello world");

In most cases, property is implicitly convertible to its underlying type (const only):

auto doSomethingWithName = [](const AString& name) { EXPECT_EQ(name, "Hello"); };
User u;
u.name = "Hello";
doSomethingWithName(u.name);

If it doesn't, simply put an asterisk:

doSomethingWithName(*u.name);

// ^^^ HERE

Observing changes#

All property types offer .changed field which is a signal reporting value changes. Let's make little observer object for demonstration:

class LogObserver : public AObject {
public:
    void log(const AString& msg) {
        ALogger::info("LogObserver") << "Received value: " << msg;
    }
};

Example usage:

auto observer = _new<LogObserver>();
auto u = aui::ptr::manage(new User { .name = "Chloe" });
AObject::connect(u->name.changed, slot(observer)::log);

At the moment, the program prints nothing. When we change the property:

u->name = "Marinette";

Code produces the following output:

[07:58:59][][LogObserver][INFO]: Received value: Marinette

As you can see, observer received the update. But, for example, if we would like to display the value via label, the label wouldn't display the current value until the next update. We want the label to display current value without requiring an update. To do this, connect to the property directly, without explicitly asking for changed:

auto observer = _new<LogObserver>();
auto u = aui::ptr::manage(new User { .name = "Chloe" });
 
EXPECT_CALL(*observer, log(AString("Chloe"))).Times(1);
AObject::connect(u->name, slot(observer)::log);

Code above produces the following output:

[07:58:59][][LogObserver][INFO]: Received value: Chloe

As you can see, observer receives the value without making updates to the value. The call of LogObserver::log is made by AObject::connect itself. In this document, we will call this behaviour as "pre-fire".

Subsequent changes to field would send updates as well:

EXPECT_CALL(*observer, log(AString("Marinette"))).Times(1);

u->name = "Marinette";

Assignment operation above makes an additional line to output:

[07:58:59][][LogObserver][INFO]: Received value: Marinette

Whole program output when connecting to property directly:

[07:58:59][][LogObserver][INFO]: Received value: Chloe

[07:58:59][][LogObserver][INFO]: Received value: Marinette

Copy constructing AProperty#

Copying AProperty is considered as a valid operation as it's a data holder. However, it's worth to note that AProperty copies it's underlying data field only, the signal-slot relations are not borrowed.

auto observer = _new<LogObserver>();
auto original = aui::ptr::manage(new User { .name = "Chloe" });
 
EXPECT_CALL(*observer, log(AString("Chloe"))).Times(1);
AObject::connect(original->name, slot(observer)::log);

This part is similar to previous examples, nothing new. Let's introduce a copy:

auto copy = _new<User>(*original);

EXPECT_EQ(copy->name, "Chloe"); // copied name

Now, let's change origin->name and check that observer received an update, but value in the copy remains:

EXPECT_CALL(*observer, log(AString("Marinette"))).Times(1);
original->name = "Marinette";
EXPECT_EQ(copy->name, "Chloe"); // still

In this example, observer is aware of changes "Chloe" -> "Marinette". The copy is not aware because it is a copy. If we try to change the copy's name:

copy->name = "Adrien";

The observer is not aware about changes in copy. In fact. copy->name has zero connections.

Copy assigning AProperty#

The situation with copy assigning auto copy = _new<User>(); *copy = *original; is similar to copy construction auto copy = _new<User>(*original);, except that we are copying to some pre-existing data structure that potentially have signal-slot relations already. So, not only connections should be kept as is but a notification for copy destination's observers is needed.

As with copy construction, copy operation of AProperty does not affect signal-slot relations. Moreover, it notifies the observers.

auto observer = _new<LogObserver>();
auto original = aui::ptr::manage(new User { .name = "Chloe" });
 
EXPECT_CALL(*observer, log(AString("Chloe"))).Times(1);
AObject::connect(original->name, slot(observer)::log);

This part is similar to previous examples, nothing new. Let's perform copy-assignment:

EXPECT_CALL(*observer, log(AString("Marinette"))).Times(1);
User copy { .name = "Marinette" };
*original = copy;

See, not only the connection remains, but it also receives notification about the change.

Moving AProperty#

Similary to copy, AProperty is both move assignable and constructible except that underlying value is moved instead of copying. Also, the observers of the source object receive notification that the value was emptied. The signal-slot relations are left unchanged.

auto observer = _new<LogObserver>();
auto original = aui::ptr::manage(new User { .name = "Chloe" });
 
EXPECT_CALL(*observer, log(AString("Chloe"))).Times(1);
AObject::connect(original->name, slot(observer)::log);

This part is similar to previous examples, nothing new. Let's introduce a move:

// by move operation, we've affected the source, hence the
// empty string notification
EXPECT_CALL(*observer, log(AString(""))).Times(1);
auto moved = _new<User>(std::move(*original));
 
EXPECT_EQ(original->name, ""); // empty
EXPECT_EQ(moved->name, "Chloe"); // moved name

Now, let's change origin->name and check that observer received an update, but value in the moved remains:

EXPECT_CALL(*observer, log(AString("Marinette"))).Times(1);
original->name = "Marinette";
EXPECT_EQ(moved->name, "Chloe"); // still

In this example, observer is aware of changes "Chloe" -> "" -> "Marinette". The moved is not aware. If we try to change the moved's name:

moved->name = "Adrien";

The observer is not aware about changes in moved. In fact. moved->name has zero connections. Move assignment work in a similar way to copy assignment:

auto observer = _new<LogObserver>();
auto original = aui::ptr::manage(new User { .name = "Chloe" });
 
EXPECT_CALL(*observer, log(AString("Chloe"))).Times(1);
AObject::connect(original->name, slot(observer)::log);

This part is similar to previous examples, nothing new. Let's perform move-assignment:

EXPECT_CALL(*observer, log(AString("Marinette"))).Times(1);
User copy { .name = "Marinette" };
*original = std::move(copy);

See, not only the connection remains, but it also receives notification about the change.

Non-const operators#

Refer to aui::PropertyModifier.

Examples: examples/7guis/cells/src/Cell.h, examples/7guis/cells/src/main.cpp, examples/7guis/circle_drawer/src/main.cpp, examples/7guis/counter/src/main.cpp, examples/7guis/crud/src/main.cpp, examples/7guis/flight_booker/src/main.cpp, examples/7guis/timer/src/main.cpp, examples/app/notes/src/main.cpp, examples/ui/contacts/src/model/Contact.h, examples/ui/contacts/src/view/ContactDetailsView.cpp, examples/ui/contacts/src/view/ContactDetailsView.h, and examples/ui/infinite_lazy_list/src/main.cpp.

Member Function Documentation#

◆ notify()#

template<typename T>

void AProperty< T >::notify ( )

inline

In common, you won't need to use this function. AProperty is reevaluated automatically as soon as one updates the value within property.

If your scenario goes beyond writeScope that explicitly defines modification scope within RAII scope, you can modify the underlying value by accessing AProperty::raw and then call notify to notify the observers that value is changed.

◆ writeScope()#

template<typename T>

aui::PropertyModifier< AProperty > AProperty< T >::writeScope ( )

inlinenoexcept

Returns: Temporary transparent object that gains write access to underlying property's value, notifying about value changes when destructed. See aui::PropertyModifier.

Examples: examples/7guis/crud/src/main.cpp, and examples/ui/contacts/src/main.cpp.

Public Types#

Public Member Functions#

Signals and public fields#

Additional Inherited Members#

Detailed Description#

Declaration#

Observing changes#

Copy constructing AProperty#

Copy assigning AProperty#

Moving AProperty#

Non-const operators#

Member Function Documentation#

◆ notify()#

◆ writeScope()#