ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2024-12-18 20:57:53 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[Docs] Update Time API docs

Browse Source 
Update time API docs to accurately reflect usage of the time API.
This commit is contained in:
Pete Richards 2017-05-16 14:56:56 -07:00
parent b70501a7ed
commit 749a2ba088
1 changed files with 47 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
API.md
View File

@ -547,29 +547,24 @@ numbers in UTC terrestrial time.
#### Getting and Setting the Active Time System #### Getting and Setting the Active Time System
Once registered, a time system can be activated using a key, or an instance of Once registered, a time system can be activated by calling `timeSystem` with
the time system itself. the timeSystem `key` or an instance of the time system. If you are not using a
[clock](#clocks), you must also specify valid [bounds](#time-bounds) for the
timeSystem.
```javascript ```javascript
openmct.time.timeSystem('utc'); openmct.time.timeSystem('utc', bounds);
``` ```
A time system can be immediately activated upon registration: A time system can be immediately activated after registration:
```javascript ```javascript
var utcTimeSystem = {
key: 'utc',
name: 'UTC Time',
cssClass = 'icon-clock',
timeFormat = 'utc',
durationFormat = 'duration',
isUTCBased = true
};
openmct.time.addTimeSystem(utcTimeSystem); openmct.time.addTimeSystem(utcTimeSystem);
openmct.time.timeSystem(utcTimeSystem); openmct.time.timeSystem(utcTimeSystem, bounds);
``` ```
Setting the active time system will trigger a [time system event](#time-events). Setting the active time system will trigger a [`'timeSystem'`](#time-events)
event. If you supplied bounds, a [`'bounds'`](#time-events) event will be triggered afterwards with your newly supplied bounds.
### Time Bounds ### Time Bounds
@ -592,8 +587,8 @@ let now = Date.now();
openmct.time.bounds({start: now - ONE_HOUR, now); openmct.time.bounds({start: now - ONE_HOUR, now);
``` ```
To respond to bounds change events, simply register a callback against the `bounds` To respond to bounds change events, listen for the [`'bounds'`](#time-events)
event. For more information on the bounds event, please see the section on [Time Events](#time-events). event.
## Clocks ## Clocks
@ -673,14 +668,16 @@ An example clock implementation is provided in the form of the [LocalClock](http
Once registered a clock can be activated by calling the `clock` function on the Once registered a clock can be activated by calling the `clock` function on the
Time API passing in the key or instance of a registered clock. Only one clock Time API passing in the key or instance of a registered clock. Only one clock
may be active at once, so activating a clock will deactivate any currently may be active at once, so activating a clock will deactivate any currently
active clock. Setting the clock will also trigger a ['clock' event](#time-events). active clock. [`clockOffsets`](#clock-offsets) must be specified when changing a clock.
Setting the clock triggers a [`'clock'`](#time-events) event, followed by a [`'clockOffsets'`](#time-events) event, and then a [`'bounds'`](#time-events) event as the offsets are applied to the clock's currentValue().
``` ```
openmct.time.clock(someClock); openmct.time.clock(someClock, clockOffsets);
``` ```
Upon being activated, a clock's `on` function will be immediately called to subscribe Upon being activated, the time API will listen for tick events on the clock by calling `clock.on`.
to `tick` events.
The currently active clock (if any) can be retrieved by calling the same The currently active clock (if any) can be retrieved by calling the same
function without any arguments. function without any arguments.
@ -707,7 +704,7 @@ relative time spans. Offsets are defined as an object with two properties:
* `start`: A `number` that must be < 0 and which is used to calculate the start * `start`: A `number` that must be < 0 and which is used to calculate the start
bounds on each clock tick. The start offset will be calculated relative to the bounds on each clock tick. The start offset will be calculated relative to the
value provided by a clock's tick callback, or its `currentValue()` function. value provided by a clock's tick callback, or its `currentValue()` function.
* `end`: A `number` that must be >=0 and which is used to calculate the end * `end`: A `number` that must be >= 0 and which is used to calculate the end
bounds on each clock tick. bounds on each clock tick.
The `clockOffsets` function can be used to get or set clock offsets. For example, The `clockOffsets` function can be used to get or set clock offsets. For example,
@ -728,16 +725,9 @@ Clock offsets are only relevant when a clock source is active.
## Time Events ## Time Events
The time API supports the registration of listeners that will be invoked when the The Time API is a standard event emitter; you can register callbacks for events using the `on` method and remove callbacks for events with the `off` method.
application's temporal state changes. Events listeners can be registered using
the `on` function. They can be deregistered using the `off` function. The arguments
accepted by the `on` and `off` functions are:
* `event`: A `string` naming the event to subscribe to. Event names correspond to For example:
the property of the Time API you're interested in. A [full list of time events](#list-of-time-events)
is provided later.
As an example, the code to listen to bounds change events looks like:
``` javascript ``` javascript
openmct.time.on('bounds', function callback (newBounds, tick) { openmct.time.on('bounds', function callback (newBounds, tick) {
@ -747,40 +737,38 @@ openmct.time.on('bounds', function callback (newBounds, tick) {
#### List of Time Events #### List of Time Events
The events supported by the Time API are: The events emitted by the Time API are:
* `bounds`: Listen for changes to current bounds. The callback will be invoked * `bounds`: emitted whenever the bounds change. The callback will be invoked
with two arguments: with two arguments:
* `bounds`: A [bounds](#getting-and-setting-bounds) bounds object representing * `bounds`: A [bounds](#getting-and-setting-bounds) bounds object
a new time period bound by the specified start and send times. representing a new time period bound by the specified start and send times.
* `tick`: A `boolean` indicating whether or not this bounds change is due to a * `tick`: A `boolean` indicating whether or not this bounds change is due to
"tick" from a [clock source](#clocks). This information can be useful when a "tick" from a [clock source](#clocks). This information can be useful
determining a strategy for fetching telemetry data in response to a bounds when determining a strategy for fetching telemetry data in response to a
change event. For example, if the bounds change was automatic, and is due bounds change event. For example, if the bounds change was automatic, and
to a tick then it's unlikely that you would need to perform a historical is due to a tick then it's unlikely that you would need to perform a
data query. It should be sufficient to just show any new telemetry received historical data query. It should be sufficient to just show any new
via subscription since the last tick, and optionally to discard any older telemetry received via subscription since the last tick, and optionally to
data that now falls outside of the currently set bounds. If `tick` is false, discard any older data that now falls outside of the currently set bounds.
then the bounds change was not due to an automatic tick, and a query for If `tick` is false,then the bounds change was not due to an automatic tick,
historical data may be necessary, depending on your data caching strategy, and a query for historical data may be necessary, depending on your data
and how significantly the start bound has changed. caching strategy, and how significantly the start bound has changed.
* `timeSystem`: Listen for changes to the active [time system](#defining-and-registering-time-systems). * `timeSystem`: emitted whenever the active time system changes. The callback will be invoked with a single argument:
The callback will be invoked with a single argument - the newly active time system. * `timeSystem`: The newly active [time system](#defining-and-registering-time-systems).
* `timeSystem`: The newly active [time system](#defining-and-registering-time-systems) object. * `clock`: emitted whenever the clock changes. The callback will be invoked
* `clock`: Listen for changes to the active clock. When invoked, the callback with a single argument:
will be provided with the new clock. * `clock`: The newly active [clock](#clocks), or `undefined` if an active
* `clock`: The newly active [clock](#clocks), or `undefined` if an active clock clock has been deactivated.
has been deactivated. * `clockOffsets`: emitted whenever the active clock offsets change. The
* `clockOffsets`: Listen for changes to active clock offsets. When invoked the callback will be invoked with a single argument:
callback will be provided with the new clock offsets. * `clockOffsets`: The new [clock offsets](#clock-offsets).
* `clockOffsets`: A [clock offsets](#clock-offsets) object.
## The Time Conductor ## The Time Conductor
The Time Conductor provides a user interface for managing time bounds in Open MCT. The Time Conductor provides a user interface for managing time bounds in Open
It allows a user to select from configured time systems and clocks, and to set bounds MCT. It allows a user to select from configured time systems and clocks, and to set bounds and clock offsets.
and clock offsets.
If activated, the time conductor must be provided with configuration options, If activated, the time conductor must be provided with configuration options,
detailed below. detailed below.