Greatly improved README; upversioned to 1.0.3

README.md

@@ -20,6 +20,65 @@ A cursor will be shown if the value of *setpoint* is between *min-value* and *ma
 
 A red-zone may be shown if a *warn-value* is set which is between *min-value* and *max-value*. If such a *warn-value* is set, then if the current value (*model*) exceeds *warn-value*, a class *warning-class* is set on the meter indicating a warning status (by default the frame goes maroon).
 
+## Usage
+
+In your cljs file, require the following:
+
+```clojure
+(:require [re-frame.core :as    rf]
+            [re-com.core   :refer [h-box v-box box label title slider p single-dropdown]]
+            [swinging-needle-meter.swinging-needle-meter :refer [swinging-needle-meter  swinging-needle-args-desc]]
+            [swinging-needle-meter.utils   :refer [panel-title title2 args-table status-text]])
+```
+
+within a [re-com](https://github.com/day8/re-com) component, 
+
+```clojure
+    [swinging-needle-meter
+        :model     @(rf/subscribe [:old-value])
+        :setpoint  @(rf/subscribe [:setpoint])          ;; optional
+        :unit      @(rf/subscribe [:unit])              ;; optional
+        :min-value @(rf/subscribe [:min-val])           ;; optional; default 0
+        :warn-value @(rf/subscribe [:warn-val])         ;; optional; default 80
+        :max-value @(rf/subscribe [:max-val])           ;; optional; default 100
+        :tolerance 2                                    ;; optional; default 3
+        :alarm-class "snm-warning"                      ;; optional; default "snm-warning"
+        :gradations @(rf/subscribe [:gradations])       ;; optional; default 5
+        :height    (int (* @(rf/subscribe [:size]) 6))  ;; optional; default 200 (pixels) 
+        :width     (int (* @(rf/subscribe [:size]) 10))];; optional; default 300 (pixels)
+```
+
+or, minimally, just 
+
+```clojure
+    [swinging-needle-meter
+        :model     @(rf/subscribe [:old-value])]
+```
+
+There are further arguments which may be set which are documented 
+[here](https://simon-brooke.github.io/swinging-needle-meter/resources/public/index.html#parameters).
+
+Obviously, all the subscriptions above must be registered with `re-frame/reg-sub`.
+
+The value subscribed to as the value to `:model` is expected to be a floating point number between that of `:min-value` and `:max-value`. 
+
+### Simulation of a mechanical meter needle with inertia and damping
+
+You don't need animated movement, you can simply jerk the needle to its new position; animation appeals to users who are used to mechanical meters and is easy on the eye, but obviously it means the needle lags a little behind changes in the underlying state.
+
+If you want animation, this is how it works.
+
+The event registered to be driven by `:timer` in `swinging-needle-meter/events.cljs` drives the animation of the movement of the needle. The value of `:timer` is initialised in the state to `(js/Date.)` in `swinging-needle-meter/state.js`. Thus, it's a clock that ticks.
+
+The actual value in the state which is tracked by the meter is the value of, in the example, `:target`. The `:timer` event moves `:old-value` progressively towards `:target` until they coincide. So in a real deployment you'd poll the actual real world value that you were tracking using a repeated asynchronous JSON request, and, on a response to such a request, you would update the value of `:target` in the state.
+
+Obviously, if you want to put multiple meters onto one page tracking different real world variables, you would minimally have to have a separate key in the state for
+
+1. The `target` of each meter;
+2. the `old-value` of each meter (if animation is desired);
+
+You might also want a separate key for the `warn-value` of each meter, and possibly also the `set-point`. Values of other parameters may be subscribed to from values in the state but it will probably be more convenient to hard-wire them or allow them to default.
+
 ## Development Mode
 
 ### Run application:
@@ -35,7 +94,6 @@ Wait a bit, then browse to [http://localhost:3449](http://localhost:3449).
 
 ## Production Build
 
-
 To compile clojurescript to javascript:
 
 ```

project.clj

@@ -1,4 +1,4 @@
-(defproject swinging-needle-meter "1.0.2"
+(defproject swinging-needle-meter "1.0.3"
   :description "A swinging needle meter, as an experiment in animating SVG from re-frame. Draws heavily on re-com."
   :dependencies [[org.clojure/clojure "1.8.0"]
                  [org.clojure/clojurescript "1.9.229"]

src/cljs/swinging_needle_meter/utils.cljs

@@ -1,5 +1,5 @@
 (ns swinging-needle-meter.utils
-  (:require [re-com.core :refer [h-box v-box box gap title line label hyperlink-href align-style]]))
+  (:require [re-com.core :refer [h-box v-box gap title line label hyperlink-href align-style]]))
 
 ;;;; This file is mostly stolen wholesale from re-demo in the re-com package;
 ;;;; I claim no credit for it.

src/cljs/swinging_needle_meter/views.cljs

@@ -69,7 +69,8 @@
                                            value, the class target-class will be set on the meter to indicate an on-target status. The setpoint value, like the model value,
                                            may change dynamically at run-time."]
 
-                                          [args-table swinging-needle-args-desc]]]
+                                          [:a {:name "parameters"}
+                                           [args-table swinging-needle-args-desc]]]]
                               [v-box
                                :gap      "10px"
                                :children [[title2 "Demo"]