properties.h

 
 
 
/* !!!!!!!!!!!!!!!! THIS FILE IS AUTOGENERATED !!!!!!!!!!!!!!!! */
 

 * GENDERS = std::array { Gender::MALE, Gender::FEMALE, GENDER::OTHER };
 * @endcode
 * 
 * We just using `aui::enumerate::ALL_VALUES` because it was provided conveniently by `AUI_ENUM_VALUES` for us.
 * 
 * It's not hard to guess that we'll use indices of this array to uniquely identify `Gender` associated with this
 * index:
 * @code{cpp}
 * /* pseudocode */
 * GENDERS[0]; // -> MALE
 * GENDERS[1]; // -> FEMALE
 * GENDERS[2]; // -> OTHER
 * @endcode
 * 
 * 
 * To perform opposite operation (i.e., `Gender` to int), we can use `aui::indexOf`:
 * @code{cpp}
 * /* pseudocode */
 * aui::indexOf(GENDERS, Gender::MALE);   // -> 0
 * aui::indexOf(GENDERS, Gender::FEMALE); // -> 1
 * aui::indexOf(GENDERS, Gender::OTHER);  // -> 2
 * @endcode
 * 
 * 
 * To bring these conversions together, let's use overloaded lambda:
 * @code{cpp}
 * static constexpr auto GENDER_INDEX_PROJECTION = aui::lambda_overloaded {
 *     [](Gender g) -> int { return aui::indexOf(GENDERS, g).valueOr(0); },
 *     [](int i) -> Gender { return GENDERS[i]; },
 * };
 * @endcode
 * 
 * @note
 * It's convenient to use lambda trailing return type syntax (i.e., `... -> int`, `... -> Gender`)
 * to make it obvious what do transformations do and how one type is transformed to another.
 * 
 * The function-like object above detects the direction of transformation and performs as follows:
 * @code{cpp}
 * GENDER_INDEX_PROJECTION(0); // -> MALE
 * GENDER_INDEX_PROJECTION(Gender::MALE); // -> 0
 * @endcode
 * 
 * 
 * It is all what we need to set up bidirectional transformations. Inside AUI_ENTRY:
 * @code{cpp}
 *    auto user = aui::ptr::manage(new User { .gender = Gender::MALE });
 * 
 *    class MyWindow: public AWindow {
 *    public:
 *        MyWindow(const _<User>& user) {
 *            // generate a string list model for genders from GENDERS array defined earlier
 *            auto gendersStr = AListModel<AString>::fromVector(
 *                GENDERS
 *                | ranges::views::transform(AEnumerate<Gender>::toName)
 *                | ranges::to_vector);
 * 
 *            // equivalent:
 *            // gendersStr = { "MALE", "FEMALE", "OTHER" }
 *            // you can customize the displayed strings by playing with
 *            // ranges::views::transform argument.
 * 
 *            setContents(Centered {
 *              _new<ADropdownList>(gendersStr) let {
 *                  // AObject::connect(user->gender, it->selectionId());
 *                  //
 *                  // The code above would break, because Gender and int
 *                  // (selectionId() type) are incompatible.
 *                  //
 *                  // Instead, define bidirectional projection:
 *                   AObject::biConnect(
 *                       user->gender.biProjected(GENDER_INDEX_PROJECTION),
 *                       it->selectionId());
 *                  },
 *            });
 *        }
 *    };
 *    _new<MyWindow>(user)->show();
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_1.png)
 * 
 * - If we try to change `user->gender` programmatically, ADropdownList will respond:
 * @code{cpp}
 * user->gender = Gender::FEMALE;
 * EXPECT_EQ(dropdownList->getSelectedId(), 1); // second option
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_2.png)
 * 
 * - If the user changes the value of ADropdownList, it reflects on the model as well:
 * @code{cpp}
 * EXPECT_EQ(user->gender, Gender::OTHER);
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_3.png)
 * 
 * # UI declarative data binding {#UI_declarative_data_binding}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L479"></b>
 * As said earlier, \c let syntax is a little bit clunky and requires extra boilerplate code to set up.
 * 
 * Here's where declarative syntax comes into play. The logic behind the syntax is the same as in
 * `AObject::connect`/`AObject::biConnect` (for ease of replacement/understanding).
 * 
 * Declarative syntax uses `&` and `&&` operators to set up connections. These were chosen intentionally: `&&` resembles
 * chain, so we "chaining view and property up".
 * 
 * - `&` sets up one-directional connection (`AObject::connect`).
 * - `&&` sets up bidirectional connection (`AObject::biConnect`).
 * 
 * Also, `>` operator (resembles arrow) is used to specify the destination slot.
 * 
 * The example below is essentially the same as @ref "UIDataBindingTest_Label_via_let" but uses declarative connection set up syntax.
 * 
 * ## Label via declarative {#UIDataBindingTest_Label_via_declarative}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L494"></b>
 * Use `&` and `>` expression to connect the model's username property to the label's @ref ALabel::text "text"
 * property.
 * @code{cpp}
 *    using namespace declarative;
 *    struct User {
 *        AProperty<AString> name;
 *    };
 * 
 *    auto user = aui::ptr::manage(new User { .name = "Roza" });
 * 
 *    class MyWindow: public AWindow {
 *    public:
 *        MyWindow(const _<User>& user) {
 *            setContents(Centered {
 *              _new<ALabel>() & user->name > &ALabel::text
 *            });
 *        }
 *    };
 *    auto window = _new<MyWindow>(user);
 *    window->show();
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_1.png)
 * Note that the label already displays the value stored in User.
 * 
 * Let's change the name:
 * @code{cpp}
 * user->name = "Vasil";
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_2.png)
 * In this example, we've achieved the same intuitive behaviour of data binding of `user->name` (like in
 * @ref "UIDataBindingTest_Label_via_let" example) but using declarative syntax. The logic behind `&` is almost the same as with `let`
 * and `AObject::connect` so projection use cases can be adapted in a similar manner.
 * 
 * ## ADataBindingDefault for omitting view property {#UIDataBindingTest_ADataBindingDefault_for_omitting_view_property}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L551"></b>
 * In previous example we have explicitly specified ALabel's property to connect with.
 * 
 * One of notable features of declarative way (in comparison to procedural `let` way) is that we can omit the view's
 * property to connect with if such `ADataBindingDefault` specialization exist for the target view and the property
 * type. Some views have already predefined such specialization for their underlying types. For instance, ALabel has
 * such specialization:
 * 
 * @code{cpp}
 * /* PREDEFINED! You don't need to define it! This listing is an example */
 * template<>
 * struct ADataBindingDefault<ALabel, AString> {
 * public:
 *     static auto property(const _<ALabel>& view) { return view->text(); }
 * };
 * @endcode
 * 
 * We can use this predefined specialization to omit the destination property:
 * @code{cpp}
 * _new<ALabel>() & user->name
 * @endcode
 * 
 * 
 * Behaviour of such connection is equal to @ref "UIDataBindingTest_Label_via_declarative":
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_1.png)
 * Note that the label already displays the value stored in User.
 * 
 * Let's change the name:
 * @code{cpp}
 * user->name = "Vasil";
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_2.png)
 * In this example, we've omitted the destination property of the connection while maintaining the same behaviour
 * as in @ref "UIDataBindingTest_Label_via_declarative".
 * 
 * ## ADataBindingDefault strong type propagation {#UIDataBindingTest_ADataBindingDefault_strong_type_propagation}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L622"></b>
 * Think of `ADataBindingDefault` as we're not only connecting properties to properties, but also creating a
 * "property to view" relationship. This philosophy covers the following scenario.
 * 
 * In AUI, there's aui::ranged_number template which stores valid value range right inside the type:
 * @code{cpp}
 * struct User {
 *     AProperty<aui::ranged_number<int, 1, 99>> age;
 * };
 * @endcode
 * 
 * 
 * These strong types can be used to propagate their traits on views, i.e., ANumberPicker. When using declarative
 * syntax, the property system calls `ADataBindingDefault::setup` to apply some extra traits of the bound value on
 * the view. Here's an abstract on how `ANumberPicker` defines specialization of `ADataBingingDefault` with
 * `aui::ranged_number`:
 * @code{cpp}
 * /* PREDEFINED! You don't need to define it! This listing is an example */
 * template <aui::arithmetic UnderlyingType, auto min, auto max>
 * struct ADataBindingDefault<ANumberPicker, aui::ranged_number<UnderlyingType, min, max>> {
 * public:
 *     static auto property(const _<ANumberPicker>& view) {
 *         return view->value();
 *     }
 *     static void setup(const _<ANumberPicker>& view) {
 *         view->setMin(aui::ranged_number<UnderlyingType, min, max>::MIN);
 *         view->setMax(aui::ranged_number<UnderlyingType, min, max>::MAX);
 *     }
 *     // ...
 * };
 * @endcode
 * 
 * As you can see, this specialization pulls the min and max values from `aui::ranged_number` type and sets them
 * to `ANumberPicker`. This way `ANumberPicker` finds out the valid range of values by simply being bound to value
 * that has constraints encoded inside its type.
 * @code{cpp}
 * _new<ANumberPicker>() && user->age,
 * @endcode
 * 
 * @note
 * We're using `operator&&` here to set up bidirectional connection. For more info, go to
 * @ref "UIDataBindingTest_Declarative_bidirectional_connection".
 * 
 * 
 * By creating this connection, we've done a little bit more. We've set ANumberPicker::setMin and
 * ANumberPicker::setMax as well:
 * @code{cpp}
 * EXPECT_EQ(numberPicker->getMin(), 1);
 * EXPECT_EQ(numberPicker->getMax(), 99);
 * @endcode
 * 
 * 
 * This example demonstrates how to use declarative binding to propagate strong types. `aui::ranged_number`
 * propagates its constraints on `ANumberPicker` thanks to `ADataBindingDefault` specialization.
 * 
 * ## Label via declarative projection {#UIDataBindingTest_Label_via_declarative_projection}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L696"></b>
 * We can use projections in the same way as with `let`.
 * @code{cpp}
 *    using namespace declarative;
 *    struct User {
 *        AProperty<AString> name;
 *    };
 * 
 *    auto user = aui::ptr::manage(new User { .name = "Roza" });
 * 
 *    class MyWindow: public AWindow {
 *    public:
 *        MyWindow(const _<User>& user) {
 *            _<ALabel> label;
 *            setContents(Centered {
 *                _new<ALabel>() & user->name.readProjected(&AString::uppercase)
 *            });
 *        }
 *    };
 *    auto window = _new<MyWindow>(user);
 *    window->show();
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_projection_1.png)
 * 
 * Note that the label already displays the **projected** value stored in User.
 * 
 * Projection applies to value changes as well. Let's change the name:
 * @code{cpp}
 *    user->name = "Vasil";
 * 
 *    EXPECT_EQ(user->name, "Vasil");
 *    EXPECT_EQ(label->text(), "VASIL"); // projected
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Label_via_declarative_projection_2.png)
 * 
 * ## Declarative bidirectional connection {#UIDataBindingTest_Declarative_bidirectional_connection}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L825"></b>
 * In previous examples, we've used `&` to make one directional (one sided) connection. This is
 * perfectly enough for ALabel because it cannot be changed by user.
 * 
 * In some cases, you might want to use property-to-property as it's bidirectional. It's used for populating view
 * from model and obtaining data from view back to the model.
 * 
 * For this example, let's use ATextField instead of ALabel as it's an editable view. In this case, we'd want to use
 * `&&` because we do want `user->name` to be aware of changes of the view.
 * @code{cpp}
 * _new<ATextField>() && user->name
 * @endcode
 * 
 * 
 * This gives the following result:
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_connection_1.png)
 * 
 * Let's change the name programmatically:
 * @code{cpp}
 * user->name = "Vasil";
 * @endcode
 * 
 * 
 * ATextField will respond:
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_connection_2.png)
 * 
 * If the user changes the value from UI, these changes will reflect on `user->model` as well:
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_connection_3.png)
 * @code{cpp}
 * EXPECT_EQ(user->name, "Changed from UI");
 * @endcode
 * 
 * 
 * This way we've set up bidirectional projection via `&&` which makes `user->name` aware of UI
 * changes.
 * 
 * ## Declarative bidirectional projection {#UIDataBindingTest_Declarative_bidirectional_projection}
 * <b aui-src="aui.uitests/tests/UIDataBindingTest.cpp#L890"></b>
 * We can use projections in the same way as with `let`.
 * 
 * Let's repeat the @ref "UIDataBindingTest_Bidirectional_projection" sample in declarative way:
 * @code{cpp}
 * _new<ADropdownList>(gendersStr) && user->gender.biProjected(GENDER_INDEX_PROJECTION) > &ADropdownList::selectionId
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_1.png)
 * @note
 * We used the `&&` operator here instead of `&` because we want the connection work in both
 * directions: `user.gender -> ADropdownList` and `ADropdownList -> user.gender`.
 * 
 * 
 * - If we try to change `user->gender` programmatically, ADropdownList will respond:
 * @code{cpp}
 * user->gender = Gender::FEMALE;
 * EXPECT_EQ(dropdownList->getSelectedId(), 1); // second option
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_2.png)
 * 
 * - If the user changes the value of ADropdownList, it reflects on the model as well:
 * @code{cpp}
 * EXPECT_EQ(user->gender, Gender::OTHER);
 * @endcode
 * 
 * ![](imgs/UIDataBindingTest.Declarative_bidirectional_projection_3.png)
 * 
 */

© 2025 AUI Framework Contributors. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. All trademarks are property of their respective owners.