.. index:: pair: class; EE::UI::UIValueBinding
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding:

template class EE::UI::UIValueBinding
=====================================

.. toctree::
	:hidden:

	struct_EE_UI_UIValueBinding_State.rst

Overview
~~~~~~~~

Move-only two-way binding between an :ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` and a :ref:`UIWidget <doxid-class_e_e_1_1_u_i_1_1_u_i_widget>` property. :ref:`More...<details-class_e_e_1_1_u_i_1_1_u_i_value_binding>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <uivaluebinding.hpp>
	
	template <typename T>
	class UIValueBinding {
	public:
		// typedefs
	
		typedef :ref:`UIValueConverter<doxid-struct_e_e_1_1_u_i_1_1_u_i_value_converter>`<T> :target:`Converter<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab7961af3828cef3fb72b6688819e3450>`;

		// structs
	
		struct :ref:`State<doxid-struct_e_e_1_1_u_i_1_1_u_i_value_binding_1_1_state>`;

		// construction
	
		:target:`UIValueBinding<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a1381f45ef21b5d5ff7e3937060b8c252>`();
		:target:`UIValueBinding<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a460084f3688ae0b8ec0953d850f6ed5a>`(const UIValueBinding&);
		:target:`UIValueBinding<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1acf91f8f312901073d9d9afa8f4f49c83>`(UIValueBinding&&);
		:ref:`UIValueBinding<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1abce872bbeb5fe11c957bcab771af3db4>`(:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>& value, :ref:`UIWidget<doxid-class_e_e_1_1_u_i_1_1_u_i_widget>`* widget, const :ref:`Converter<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab7961af3828cef3fb72b6688819e3450>`& converter = :ref:`converterDefault<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1aa3d45e2009ff5ed20e05f1a516a1b18d>`(), const std::string& propertyName = "value", :ref:`Event::EventType<doxid-class_e_e_1_1_scene_1_1_event_1a230934826f432a3bb4b3694760b59b69>` eventType = Event::OnValueChange);

		// methods
	
		static :ref:`Converter<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab7961af3828cef3fb72b6688819e3450>` :ref:`converterDefault<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1aa3d45e2009ff5ed20e05f1a516a1b18d>`();
		UIValueBinding& :target:`operator=<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab44af043dd507e0d01801b5b83696f3a>`(const UIValueBinding&);
		UIValueBinding& :target:`operator=<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a335af5db2905ce8532b98d6501371576>`(UIValueBinding&&);
		void :ref:`disconnect<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a8edb0875bd22b196414f4f99c1be2427>`();
		:ref:`operator bool<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a45608d8df5dd825ee736b6303e00a8b5>`() const;
		bool :ref:`isConnected<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ac79f405218fe76ccdf0dd9901d8c120b>`() const;
		bool :ref:`isValid<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a5c4a3ac9de536d8c6c05e43007911051>`() const;
		:ref:`UIWidget<doxid-class_e_e_1_1_u_i_1_1_u_i_widget>`* :ref:`widget<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a11269fce8b94a45ddd104b9178a0cce4>`() const;
		std::optional<T> :ref:`value<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1abcc1051617352441d0a1943d9b9a4670>`() const;
		bool :ref:`setValue<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a1c40875c64b94fed7aff157aeb56cdcd>`(const T& value);
		:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>::Connection :ref:`observeValue<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a2528d624cfa5c95976d86a4e79dfc44c>`(typename :ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>::Callback callback);
		:ref:`UIValueValidationState<doxid-class_e_e_1_1_u_i_1_1_u_i_value_validation_state>`* :ref:`validationState<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a8b60f0f33e2786e8d180c117ec4b13a3>`();
		const :ref:`UIValueValidationState<doxid-class_e_e_1_1_u_i_1_1_u_i_value_validation_state>`* :target:`validationState<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a70c229ef53576d688bd0c5f70826817a>`() const;
	};
.. _details-class_e_e_1_1_u_i_1_1_u_i_value_binding:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Move-only two-way binding between an :ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` and a :ref:`UIWidget <doxid-class_e_e_1_1_u_i_1_1_u_i_widget>` property.

The converter maps directly between T and the widget property string. Its toValue() callback decides whether widget input may enter the model. Model-originated values are authoritative and are formatted through fromValue().

Destroying the binding disconnects both directions. Destroying either the observable or widget first is safe and does not keep that endpoint alive.

Synchronization is immediate and single-threaded. The observable, widget, and binding must all be used on the widget's owning :ref:`UI <doxid-namespace_e_e_1_1_u_i>` thread.

Use :ref:`UIValueBinding <doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding>` when an :ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` belongs to a UI-independent model. The returned binding must be retained for as long as synchronization is desired.

.. ref-code-block:: cpp

	ObservableValue<std::string> userName{ "Ada" };
	auto binding = bindValue( userName, textInput,
	                     UIValueConverter<std::string>::converterString(),
	                     "text", Event::OnTextChanged );
	userName = "Grace"; // Updates textInput without coupling the model to UIWidget.

Construction
------------

.. index:: pair: function; UIValueBinding
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1abce872bbeb5fe11c957bcab771af3db4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	UIValueBinding(:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>& value, :ref:`UIWidget<doxid-class_e_e_1_1_u_i_1_1_u_i_widget>`* widget, const :ref:`Converter<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab7961af3828cef3fb72b6688819e3450>`& converter = :ref:`converterDefault<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1aa3d45e2009ff5ed20e05f1a516a1b18d>`(), const std::string& propertyName = "value", :ref:`Event::EventType<doxid-class_e_e_1_1_scene_1_1_event_1a230934826f432a3bb4b3694760b59b69>` eventType = Event::OnValueChange)

Starts synchronizing ``value`` with a property of ``widget``.

The current model value is applied to the widget immediately. Later ``eventType`` events parse the widget property back into the model.

Methods
-------

.. index:: pair: function; converterDefault
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1aa3d45e2009ff5ed20e05f1a516a1b18d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	static :ref:`Converter<doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ab7961af3828cef3fb72b6688819e3450>` converterDefault()



.. rubric:: Returns:

The standard converter for the bound value type.

.. index:: pair: function; disconnect
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a8edb0875bd22b196414f4f99c1be2427:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void disconnect()

Stops synchronization in both directions. Calling this repeatedly is safe.

.. index:: pair: function; operator bool
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a45608d8df5dd825ee736b6303e00a8b5:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	operator bool() const



.. rubric:: Returns:

Whether both model and widget endpoints are still alive and connected.

.. index:: pair: function; isConnected
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1ac79f405218fe76ccdf0dd9901d8c120b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool isConnected() const



.. rubric:: Returns:

Whether both model and widget endpoints are still alive and connected.

.. index:: pair: function; isValid
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a5c4a3ac9de536d8c6c05e43007911051:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool isValid() const



.. rubric:: Returns:

Whether the most recent conversion or validation succeeded.

.. index:: pair: function; widget
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a11269fce8b94a45ddd104b9178a0cce4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`UIWidget<doxid-class_e_e_1_1_u_i_1_1_u_i_widget>`* widget() const



.. rubric:: Returns:

The bound widget, or nullptr after disconnection or widget destruction.

.. index:: pair: function; value
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1abcc1051617352441d0a1943d9b9a4670:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	std::optional<T> value() const



.. rubric:: Returns:

A copy of the model value, or std::nullopt after disconnection.

.. index:: pair: function; setValue
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a1c40875c64b94fed7aff157aeb56cdcd:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool setValue(const T& value)



.. rubric:: Returns:

true when the connected model still exists and was assigned ``value``.

.. index:: pair: function; observeValue
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a2528d624cfa5c95976d86a4e79dfc44c:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>::Connection observeValue(typename :ref:`ObservableValue<doxid-class_e_e_1_1_observable_value>`<T>::Callback callback)



.. rubric:: Returns:

A scoped observer connection to later model changes, or an empty connection.

.. index:: pair: function; validationState
.. _doxid-class_e_e_1_1_u_i_1_1_u_i_value_binding_1a8b60f0f33e2786e8d180c117ec4b13a3:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`UIValueValidationState<doxid-class_e_e_1_1_u_i_1_1_u_i_value_validation_state>`* validationState()



.. rubric:: Returns:

Observable conversion and input-validation state.