diff --git a/src/documents/README.md b/src/documents/README.md index 9f321437..5e9afad5 100644 --- a/src/documents/README.md +++ b/src/documents/README.md @@ -114,5 +114,6 @@ layout: default * [Undo](to-do/UndoAPI.md) * [Table of Contents](to-do/TableOfContentsAPI.md) * [Text to Speech](TextToSpeechAPI.md) +* [State Tracker](StateTrackerAPI.md) diff --git a/src/documents/StateTrackerAPI.md b/src/documents/StateTrackerAPI.md new file mode 100644 index 00000000..037e6ede --- /dev/null +++ b/src/documents/StateTrackerAPI.md @@ -0,0 +1,265 @@ +--- +title: StateTracker API +layout: default +category: Components +--- + +A **StateTracker** is an [Infusion component](UnderstandingInfusionComponents.md) that tracks another object whose state can change over time, and provides notification of the change in state. + +One example is tracking an operating system process to detect when that process starts or stops running. Another example is tracking the checked state of a checkbox. The tracker is agnostic about the state to track, and how to track it. It is up to the client to provide information about states and how they change. The tracker focusses on checking the state and notifying when a change occurs. + +The StateTracker uses polling to periodically check the state. Polling is implemented using JavaScript's `setInterval()` function. + +## Grade ## + +StateTrackers are defined using the `fluid.component` [grade](ComponentGrades.md), as shown in the following code block: + +```javascript +fluid.defaults("fluid.stateTracker", { + gradeNames: ["fluid.component"], + ... +}); +``` +## Creator ## + +Use the following function to create a StateTracker component: + + + + + + + + + + + + + + + + + + + + + + + + +
Method + fluid.stateTracker(); +
Description + Instantiate the state tracker. The methods of the instantiated component can be called to start and stop tracking. +
Parametersnone
ReturnsThe state tracker component
Examples +
+
+var stateTracker = fluid.stateTracker();
+
+
+
+ +## Supported Methods ## + +### startTracking ### + + + + + + + + + + + + + + + + + + + + + + + + +
Method + stateTracker.startTracking(changeEvaluator, changeListener[, interval]); +
Description + The startTracking method allows clients to attach a callback that the tracker calls when the relevant state changes. The changeEvaluator parameter is an object that knows which state to track, and if that state changed in the relavant manner. +
Parameters +
+
changeEvaluator
+
+ A JavaScript object that has a zero parameter evaluateChange() method that returns a boolean. +
+
changeListener
+
+ A callback function that is invoked when the onStateChange event occurs. +
+
interval
+
+ An optional parameter that defines how frequently the state is checked to see if it has changed, in msec. If not specified, the interval defaults to that defined by the global setInterval() function, i.e. 10 msec. +
+
+
ReturnsAn intervalID as returned by setInterval(). This is used later to cancel tracking.
Example +
+
+// Use the runtime's default interval.
+var intervalID = stateTracker.startTracking(checkBoxEvaluator, onCheckStateChanged);
+
+// Check the state every 100 msec.
+var intervalID = stateTracker.startTracking(checkBoxEvaluator, onCheckStateChanged, 100);
+
+
+
+ +### stopTracking ### + + + + + + + + + + + + + + + + + + + + +
Method + stateTracker.stopTracking(intervalID); +
Description + The stopTracking() method allows clients to cancel state change tracking. +
Parameters +
+
intervalID
+
+ The intervalID returned by startTracking() +
+
+
Example +
+
+stateTracker.stopTracking(intervalID);
+
+
+
+ +### monitorChange ### + + + + + + + + + + + + + + + + +
Method + stateTracker.monitorChange(); +
Description + Internal method used to coordinate monitoring of the changes in + state using the evaluator object, and emitting onStateChange events as needed. +
Parametersnone
+ +### initMonitorInfo ### + + + + + + + + + + + + + + + + + + + + +
Method + stateTracker.initMonitorInfo(); +
Description + Internal method called to create and initialize a monitor object that is subseqently used by stateTracker.monitorChange(). +
Parameters +
+
changeEvaluator
+
+ The JavaScript object passed to stateTracker.startTracking() that is used to evaluate if a change in state has occurred. +
+
+
Returns +

A monitorInfo object whose structure is:

+
+
+{
+    intervalID:         // slot for the interval id
+    changeEvaluator:    // the change evaluator object
+}
+
+
+
+ +## Supported Events ## + +
Note: if needed, please read the Infusion Event System document for a full description of infusion events.
+ +The event fired by the State Tracker component is described below. + +### onStateChange ### + + + + + + + + + + + + + + + + +
Description + This event fires when a change in state is detected. +
Typedefault
Parameters +
+
changeEvaluator
+
+ The state evaluator object that was passed to stateTracker.startTracking(). +
+
+
+ +## Caveat ## + +Since the state tracker uses polling to detect changes in state, it is possible that some of the changes are missed or, even, that none of the changes are detected. This can happen when the polling frequency is less than the frequency with which the state changes. For example, suppose the state being monitored changes from state0 to state1 after 23 msec, and then back to state0 11 msec later. If the tracker is checking that change every 100 msec, then it will fail to notice the changes due to the relatively longer time between evaluations. The limiting factor is the JavaScript runtime environment's fastest polling frequency, which is typically every 10 msec. If the state that you are interested in changes more frequently than every 10 msec, then another, possibly native, tracker is needed. +