.. index:: pair: class; EE::ObservableValue
.. _doxid-class_e_e_1_1_observable_value:

template class EE::ObservableValue
==================================

.. toctree::
	:hidden:

	struct_EE_ObservableValue_State.rst
	class_EE_ObservableValue_Connection.rst
	class_EE_ObservableValue_WeakHandle.rst

Overview
~~~~~~~~

Owns a value and notifies scoped observers after the value changes. :ref:`More...<details-class_e_e_1_1_observable_value>`


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

	#include <observablevalue.hpp>
	
	template <typename T>
	class ObservableValue {
	public:
		// typedefs
	
		typedef T :target:`ValueType<doxid-class_e_e_1_1_observable_value_1a63fb597fac85a0e9a8b0909ac8f7c5cc>`;
		typedef std::function<void(const T&)> :target:`Callback<doxid-class_e_e_1_1_observable_value_1a53e49c3580bc69ffc87a473c9d638b9d>`;

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

		// classes
	
		class :ref:`Connection<doxid-class_e_e_1_1_observable_value_1_1_connection>`;
		class :ref:`WeakHandle<doxid-class_e_e_1_1_observable_value_1_1_weak_handle>`;

		// construction
	
		:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value_1af5b7bbc0cc20b466d357e4dc1f5bc1e0>`();
		:ref:`ObservableValue<doxid-class_e_e_1_1_observable_value_1a467fd1c9a36ba40acffe8d1d74759537>`(T value);
		:target:`ObservableValue<doxid-class_e_e_1_1_observable_value_1a38dfb6e9f9d1c19f0eb0528681a2bc7c>`(const ObservableValue&);
		:target:`ObservableValue<doxid-class_e_e_1_1_observable_value_1a83457b5ac0bb3871658c33c85d00532e>`(ObservableValue&&);

		// methods
	
		ObservableValue& :target:`operator=<doxid-class_e_e_1_1_observable_value_1a6908089d32c5d55ba9e02f617b544b26>`(const ObservableValue&);
		ObservableValue& :target:`operator=<doxid-class_e_e_1_1_observable_value_1accd4038a4a4c883a2ebcd3d9b468b3fd>`(ObservableValue&&);
		const T& :ref:`get<doxid-class_e_e_1_1_observable_value_1a09b30b2f00ee8e230053faf4b2c12396>`() const;
		void :ref:`set<doxid-class_e_e_1_1_observable_value_1ad0f68766b43ac8a21855aabc3a0e2520>`(const T& value);
		void :ref:`set<doxid-class_e_e_1_1_observable_value_1a35a74adadd32b6b2e19a77b9535d1f5b>`(T&& value);
		ObservableValue& :target:`operator=<doxid-class_e_e_1_1_observable_value_1a39338aaecac912a5baca6a87e09b6589>`(const T& value);
		ObservableValue& :target:`operator=<doxid-class_e_e_1_1_observable_value_1a3406366b712f30b4dcd3e0319b54e750>`(T&& value);
		const T& :target:`operator*<doxid-class_e_e_1_1_observable_value_1a94d5698b9cfdfcb9ebd589fa1fb8012a>`() const;
		const T* :target:`operator-><doxid-class_e_e_1_1_observable_value_1aef0d2e215a2ec3ffea8286542f60ad43>`() const;
		:target:`operator const T &<doxid-class_e_e_1_1_observable_value_1a2253423bf9c18ddf2f0fbf7dd5f709de>`() const;
		:ref:`Connection<doxid-class_e_e_1_1_observable_value_1_1_connection>` :ref:`observe<doxid-class_e_e_1_1_observable_value_1a3ba08b2ee0bd84be4bbf25aacc726f87>`(:ref:`Callback<doxid-class_e_e_1_1_observable_value_1a53e49c3580bc69ffc87a473c9d638b9d>` callback);
		:ref:`WeakHandle<doxid-class_e_e_1_1_observable_value_1_1_weak_handle>` :ref:`weakHandle<doxid-class_e_e_1_1_observable_value_1a2f100b43921d89134863a0b884855340>`() const;
		std::size_t :ref:`observerCount<doxid-class_e_e_1_1_observable_value_1ac0753da9b3c8f1dda95ea25e908d9a16>`() const;
		bool :ref:`isNotifying<doxid-class_e_e_1_1_observable_value_1a1372269fe7a7225987c7818949290d25>`() const;
	};
.. _details-class_e_e_1_1_observable_value:

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

Owns a value and notifies scoped observers after the value changes.

:ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` is a deliberately small synchronous primitive. Assignment and :ref:`set() <doxid-class_e_e_1_1_observable_value_1ad0f68766b43ac8a21855aabc3a0e2520>` notify observers immediately on the calling thread. Observer callbacks use snapshot semantics: changes to the observer list during a notification take effect on the next notification.

The class is non-copyable. Moving it transfers the value and its existing observers, allowing handles and :ref:`UI <doxid-namespace_e_e_1_1_u_i>` bindings to keep observing the moved-to instance. :ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` and all of its connections must be used from a single owning thread.

Use :ref:`ObservableValue <doxid-class_e_e_1_1_observable_value>` for model or application state whose observers are not known by the model. A configuration object, for example, can publish changes without depending on UIWidget; a live :ref:`UI <doxid-namespace_e_e_1_1_u_i>` may attach with UIValueBinding and disappear safely later.

.. ref-code-block:: cpp

	struct ApplicationConfig {
	    ObservableValue<bool> showLineNumbers{ true };
	};
	ApplicationConfig config;
	auto connection = config.showLineNumbers.observe(
	    []( bool enabled ) { updateEditorPolicy( enabled ); } );
	config.showLineNumbers = false;

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

.. index:: pair: function; ObservableValue
.. _doxid-class_e_e_1_1_observable_value_1af5b7bbc0cc20b466d357e4dc1f5bc1e0:

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

	ObservableValue()

Creates an observable containing a default-constructed value.

.. index:: pair: function; ObservableValue
.. _doxid-class_e_e_1_1_observable_value_1a467fd1c9a36ba40acffe8d1d74759537:

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

	ObservableValue(T value)

Creates an observable containing ``value``. No notification is emitted.

Methods
-------

.. index:: pair: function; get
.. _doxid-class_e_e_1_1_observable_value_1a09b30b2f00ee8e230053faf4b2c12396:

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

	const T& get() const



.. rubric:: Returns:

A reference to the current value.

.. index:: pair: function; set
.. _doxid-class_e_e_1_1_observable_value_1ad0f68766b43ac8a21855aabc3a0e2520:

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

	void set(const T& value)

Replaces the value and synchronously notifies observers when it changed.

.. index:: pair: function; set
.. _doxid-class_e_e_1_1_observable_value_1a35a74adadd32b6b2e19a77b9535d1f5b:

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

	void set(T&& value)

Move-replaces the value and synchronously notifies observers when it changed.

.. index:: pair: function; observe
.. _doxid-class_e_e_1_1_observable_value_1a3ba08b2ee0bd84be4bbf25aacc726f87:

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

	:ref:`Connection<doxid-class_e_e_1_1_observable_value_1_1_connection>` observe(:ref:`Callback<doxid-class_e_e_1_1_observable_value_1a53e49c3580bc69ffc87a473c9d638b9d>` callback)

Observes subsequent value changes.

Registration does not invoke ``callback`` with the current value. Reentrant :ref:`set() <doxid-class_e_e_1_1_observable_value_1ad0f68766b43ac8a21855aabc3a0e2520>` calls are queued and delivered after the current observer snapshot completes.



.. rubric:: Returns:

A scoped connection; destroying it disconnects the callback.

.. index:: pair: function; weakHandle
.. _doxid-class_e_e_1_1_observable_value_1a2f100b43921d89134863a0b884855340:

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

	:ref:`WeakHandle<doxid-class_e_e_1_1_observable_value_1_1_weak_handle>` weakHandle() const



.. rubric:: Returns:

A non-owning handle that expires safely with this observable.

.. index:: pair: function; observerCount
.. _doxid-class_e_e_1_1_observable_value_1ac0753da9b3c8f1dda95ea25e908d9a16:

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

	std::size_t observerCount() const



.. rubric:: Returns:

The number of currently connected observers.

.. index:: pair: function; isNotifying
.. _doxid-class_e_e_1_1_observable_value_1a1372269fe7a7225987c7818949290d25:

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

	bool isNotifying() const



.. rubric:: Returns:

Whether observer callbacks are currently being delivered.