Detailed Description

template<typename M, aui::invocable< M & > Getter, aui::invocable< M &, std::invoke_result_t< Getter, M & > > Setter, typename SignalArg>
class APropertyDef< M, Getter, Setter, SignalArg >

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

: You can use this way if you are required to define custom behaviour on getter/setter. As a downside, you have to write extra boilerplate code: define property, data field, signal, getter and setter checking equality. Also, APropertyDef requires the class to derive AObject. Most of AView's properties are defined this way.

See property system for usage examples.

Performance considerations#

APropertyDef does not involve extra runtime overhead between assignment and getter/setter.

Declaration#

To declare a property with custom getter/setter, use APropertyDef template. APropertyDef-based property is defined by const member function as follows:

class User : public AObject {
public:
    auto name() const {
        return APropertyDef {
            this,
            &User::getName,   // this works too: &User::mName
            &User::setName,
            mNameChanged,
        };
    }
 
private:
    AString mName;
    emits<AString> mNameChanged;
 
    void setName(AString name) {
        // APropertyDef requires us to emit
        // changed signal if value is actually
        // changed
        if (mName == name) {
            return;
        }
        mName = std::move(name);
        emit mNameChanged(mName);
    }
 
    const AString& getName() const { return mName; }
};

APropertyDef behaves like a class/struct function member:

User u;
u.name() = "Hello"; // calls setName implicitly
EXPECT_EQ(u.name(), "Hello");

Note: Properties defined with APropertyDef instead of AProperty impersonate themselves by trailing braces (). We can't get rid of them, as APropertyDef is defined thanks to member function. In comparison to user->name, think of user->name() as the same kind of property except defining custom behaviour via function, hence the braces ().

For the rest, APropertyDef is identical to AProperty including seamless interaction:

User u;
u.name() = "Hello";
u.name() += " world!";
EXPECT_EQ(u.name(), "Hello world!");
EXPECT_EQ(u.name()->length(), AString("Hello world!").length());

Note: In order to honor getters/setters, APropertyDef calls getter/setter instead of using += on your property directly. Equivalent code will be:
u.setName(u.getName() + " world!")

The implicit conversions work the same way as with AProperty:

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;
    }
};

The usage is close to AProperty:

auto observer = _new<LogObserver>();
auto u = _new<User>();
u->name() = "Chloe";
// ...
AObject::connect(u->name().changed, AUI_SLOT(observer)::log);

u->name() = "Marinette";

Code produces the following output:

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

Making connection to property directly instead of .changed:

auto observer = _new<LogObserver>();
auto u = _new<User>();
u->name() = "Chloe";
// ...
AObject::connect(u->name(), AUI_SLOT(observer)::log);

Code above produces the following output:

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

Subsequent changes to field would send updates as well:

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

Examples: /home/runner/work/aui/aui/aui.views/src/AUI/View/AView.h.

Member Function Documentation

◆ writeScope()

template<typename M, aui::invocable< M & > Getter, aui::invocable< M &, std::invoke_result_t< Getter, M & > > Setter, typename SignalArg>

aui::PropertyModifier< APropertyDef > APropertyDef< M, Getter, Setter, SignalArg >::writeScope ( )

inlinenoexcept

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

Member Data Documentation

◆ set

template<typename M, aui::invocable< M & > Getter, aui::invocable< M &, std::invoke_result_t< Getter, M & > > Setter, typename SignalArg>

Setter APropertyDef< M, Getter, Setter, SignalArg >::set

The setter implementation typically emits changed signal. If it is, it must emit changes only if value is actually changed.

void setValue(int value) {
  if (mValue == value) {
    return;
  }
  mValue = value;
  emit mValueChanged(valueChanged);
}