# observable README

This is a basic notify-listen framework on top of wxWidgets.  It requires
C++11.

There are three out of the box use cases:

* The event variable depends on a variable which is visible on both
  the listener and notifying side. It is described in the
  _observable_evtvar.h_ header.

* The config variable mechanism allows for listening to configuraion
  variable changes, and to notify about such changes. It is described
  in the _observable_confvar.h_ header

* The global variable mechanism (sic!) allows for listening to global
  variable changes and to notify about such changes. It is described in
  the _observable_globvar.h_ header.

The notify event is based on wxCommandEvent and can thus optionally carry
a string, a number and/or a pointer to the listening side. It has been
extended to also be able to carry a `shared_ptr<void>` which basically
makes it possible to transfer any shared_ptr from the notifying side to
the listeners.

Library is thread-safe in the sense that Notify() can be invoked from
asynchronous worker threads. However, actual work performed by Listen()
must be done in the main thread.

The framework is developed in the opencpn project [1].

## Extending

The framework can be extended to handle other types. The basic
condition is that anything which should use Listen() and Notify()
should implement the KeyProvider interface. This is just the ability
to return a unique, stable key.

Stated otherwise, the key used when invoking Listen() should be the
same as when doing Notify(). Examples includes:

* The event variable described above uses an auto generated random key,
  this works since both sides knows about the same event variable.

* The config variable uses a key derived from the configuration value name.
  This works since both sides knows the name (path) of the configuration
  variable.

In the OpenCPN project the framework is extended to handle messages. Each
message implements the KeyProvider interface which generates a key based on
the message "type". This makes it possible to listen for specific message
types as well as notifying when such a message is received.

## Copyright and License

This work is copyright (c) Alec Leamas 2021-2022. It is distributed under
the GPL licence, version 2 or later. See the source files for details.


[1] https://github.com/opencpn/OpenCPN
