ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2024-12-19 21:27:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[Documentation] Time API docs update new/deprecated functionality (#7107)

Browse Source 
* update time api docs to reflect recent changes

* clarify what mode openmct starts in and update setMode arguments
This commit is contained in:
Jamie V 2023-10-03 11:42:35 -07:00 committed by GitHub
parent b1169ffd7d
commit d973140906
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 135 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
API.md
View File

@ -44,8 +44,10 @@
- [Clocks](#clocks)
- [Defining and registering clocks](#defining-and-registering-clocks)
- [Getting and setting active clock](#getting-and-setting-active-clock)
- [Stopping an active clock](#stopping-an-active-clock)
- [⚠️ \[DEPRECATED\] Stopping an active clock](#️-deprecated-stopping-an-active-clock)
- [Clock Offsets](#clock-offsets)
- [Time Modes](#time-modes)
- [Time Mode Helper Methods](#time-mode-helper-methods)
- [Time Events](#time-events)
- [List of Time Events](#list-of-time-events)
- [The Time Conductor](#the-time-conductor)
@ -685,8 +687,9 @@ state of the application, and emits events to inform listeners when the state ch
Because the data displayed tends to be time domain data, Open MCT must always
have at least one time system installed and activated. When you download Open
MCT, it will be pre-configured to use the UTC time system, which is installed and activated, along with other default plugins, in `index.html`. Installing and activating a time system is simple, and is covered
[in the next section](#defining-and-registering-time-systems).
MCT, it will be pre-configured to use the UTC time system, which is installed and activated,
along with other default plugins, in `index.html`. Installing and activating a time system
is simple, and is covered [in the next section](#defining-and-registering-time-systems).
### Time Systems and Bounds
@ -737,28 +740,38 @@ numbers in UTC terrestrial time.
#### Getting and Setting the Active Time System
Once registered, a time system can be activated by calling `timeSystem` with
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.
Once registered, a time system can be activated by calling `setTimeSystem` with
the timeSystem `key` or an instance of the time system. You can also specify
valid [bounds](#time-bounds) for the timeSystem.
```javascript
openmct.time.timeSystem('utc', bounds);
openmct.time.setTimeSystem('utc', bounds);
```
The current time system can be retrieved as well by calling `getTimeSystem`.
```javascript
openmct.time.getTimeSystem();
```
A time system can be immediately activated after registration:
```javascript
openmct.time.addTimeSystem(utcTimeSystem);
openmct.time.timeSystem(utcTimeSystem, bounds);
openmct.time.setTimeSystem(utcTimeSystem, bounds);
```
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.
Setting the active time system will trigger a [`'timeSystemChanged'`](#time-events)
event. If you supplied bounds, a [`'boundsChanged'`](#time-events) event will be triggered afterwards with your newly supplied bounds.
> ⚠️ **Deprecated**
> - The method `timeSystem()` is deprecated. Please use `getTimeSystem()` and `setTimeSystem()` as a replacement.
#### Time Bounds
The TimeAPI provides a getter/setter for querying and setting time bounds. Time
The TimeAPI provides a getter and setter for querying and setting time bounds. Time
bounds are simply an object with a `start` and an end `end` attribute.
- `start`: A `number` representing a moment in time in the active [Time System](#defining-and-registering-time-systems).
@ -768,26 +781,34 @@ telemetry views.
This will be used as the end of the time period displayed by time-responsive
telemetry views.
If invoked with bounds, it will set the new time bounds system-wide. If invoked
without any parameters, it will return the current application-wide time bounds.
New bounds can be set system wide by calling `setBounds` with [bounds](#time-bounds).
``` javascript
const ONE_HOUR = 60 * 60 * 1000;
let now = Date.now();
openmct.time.bounds({start: now - ONE_HOUR, now);
openmct.time.setBounds({start: now - ONE_HOUR, now);
```
To respond to bounds change events, listen for the [`'bounds'`](#time-events)
Calling `getBounds` will return the current application-wide time bounds.
``` javascript
openmct.time.getBounds();
```
To respond to bounds change events, listen for the [`'boundsChanged'`](#time-events)
event.
> ⚠️ **Deprecated**
> - The method `bounds()` is deprecated and will be removed in a future release. Please use `getBounds()` and `setBounds()` as a replacement.
### Clocks
The Time API can be set to follow a clock source which will cause the bounds
to be updated automatically whenever the clock source "ticks". A clock is simply
an object that supports registration of listeners and periodically invokes its
listeners with a number. Open MCT supports registration of new clock sources that
tick on almost anything. A tick occurs when the clock invokes callback functions
registered by its listeners with a new time value.
The Time API requires a clock source which will cause the bounds to be updated
automatically whenever the clock source "ticks". A clock is simply an object that
supports registration of listeners and periodically invokes its listeners with a
number. Open MCT supports registration of new clock sources that tick on almost
anything. A tick occurs when the clock invokes callback functions registered by its
listeners with a new time value.
An example of a clock source is the [LocalClock](https://github.com/nasa/openmct/blob/master/src/plugins/utcTimeSystem/LocalClock.js)
which emits the current time in UTC every 100ms. Clocks can tick on anything. For
@ -855,23 +876,29 @@ An example clock implementation is provided in the form of the [LocalClock](http
#### Getting and setting active clock
Once registered a clock can be activated by calling the `clock` function on the
Once registered a clock can be activated by calling the `setClock` function on the
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
active clock. [`clockOffsets`](#clock-offsets) must be specified when changing a clock.
active clock and start the new 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().
Setting the clock triggers a [`'clockChanged'`](#time-events) event, followed by a [`'clockOffsetsChanged'`](#time-events) event, and then a [`'boundsChanged'`](#time-events) event as the offsets are applied to the clock's currentValue().
```
openmct.time.clock(someClock, clockOffsets);
openmct.time.setClock(someClock, clockOffsets);
```
Upon being activated, the time API will listen for tick events on the clock by calling `clock.on`.
The currently active clock (if any) can be retrieved by calling the same
function without any arguments.
The currently active clock can be retrieved by calling `getClock`.
#### Stopping an active clock
```
openmct.time.getClock();
```
> ⚠️ **Deprecated**
> - The method `clock()` is deprecated and will be removed in a future release. Please use `getClock()` and `setClock()` as a replacement.
#### ⚠️ [DEPRECATED] Stopping an active clock
_As of July 2023, this method will be deprecated. Open MCT will always have a ticking clock._
@ -882,12 +909,14 @@ will stop the clock from ticking, and set the active clock to `undefined`.
openmct.time.stopClock();
```
> ⚠️ **Deprecated**
> - The method `stopClock()` is deprecated and will be removed in a future release.
#### Clock Offsets
When a clock is active, the time bounds of the application will be updated
automatically each time the clock "ticks". The bounds are calculated based on
the current value provided by the active clock (via its `tick` event, or its
`currentValue()` method).
When in Real-time [mode](#time-modes), the time bounds of the application will be updated automatically each time the
clock "ticks". The bounds are calculated based on the current value provided by
the active clock (via its `tick` event, or its `currentValue()` method).
Unlike bounds, which represent absolute time values, clock offsets represent
relative time spans. Offsets are defined as an object with two properties:
@ -898,21 +927,77 @@ 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
bounds on each clock tick.
The `clockOffsets` function can be used to get or set clock offsets. For example,
The `setClockOffsets` function can be used to get or set clock offsets. For example,
to show the last fifteen minutes in a ms-based time system:
```javascript
var FIFTEEN_MINUTES = 15 * 60 * 1000;
openmct.time.clockOffsets({
openmct.time.setClockOffsets({
start: -FIFTEEN_MINUTES,
end: 0
})
```
The `getClockOffsets` method will return the currently set clock offsets.
```javascript
openmct.time.getClockOffsets()
```
**Note:** Setting the clock offsets will trigger an immediate bounds change, as
new bounds will be calculated based on the `currentValue()` of the active clock.
Clock offsets are only relevant when a clock source is active.
Clock offsets are only relevant when in Real-time [mode](#time-modes).
> ⚠️ **Deprecated**
> - The method `clockOffsets()` is deprecated and will be removed in a future release. Please use `getClockOffsets()` and `setClockOffsets()` as a replacement.
### Time Modes
There are two time modes in Open MCT, "Fixed" and "Real-time". In Real-time mode the
time bounds of the application will be updated automatically each time the clock "ticks".
The bounds are calculated based on the current value provided by the active clock. In
Fixed mode, the time bounds are set for a specified time range. When Open MCT is first
initialized, it will be in Real-time mode.
The `setMode` method can be used to set the current time mode. It accepts a mode argument,
`'realtime'` or `'fixed'` and it also accepts an optional [offsets](#clock-offsets)/[bounds](#time-bounds) argument dependent
on the current mode.
``` javascript
openmct.time.setMode('fixed');
openmct.time.setMode('fixed', bounds); // with optional bounds
```
or
``` javascript
openmct.time.setMode('realtime');
openmct.time.setMode('realtime', offsets); // with optional offsets
```
The `getMode` method will return the current time mode, either `'realtime'` or `'fixed'`.
``` javascript
openmct.time.getMode();
```
#### Time Mode Helper Methods
There are two methods available to determine the current time mode in Open MCT programmatically,
`isRealTime` and `isFixed`. Each one will return a boolean value based on the current mode.
``` javascript
if (openmct.time.isRealTime()) {
// do real-time stuff
}
```
``` javascript
if (openmct.time.isFixed()) {
// do fixed-time stuff
}
```
### Time Events
@ -921,7 +1006,7 @@ The Time API is a standard event emitter; you can register callbacks for events
For example:
``` javascript
openmct.time.on('bounds', function callback (newBounds, tick) {
openmct.time.on('boundsChanged', function callback (newBounds, tick) {
// Do something with new bounds
});
```
@ -930,7 +1015,7 @@ openmct.time.on('bounds', function callback (newBounds, tick) {
The events emitted by the Time API are:
- `bounds`: emitted whenever the bounds change. The callback will be invoked
- `boundsChanged`: emitted whenever the bounds change. The callback will be invoked
with two arguments:
- `bounds`: A [bounds](#getting-and-setting-bounds) bounds object
representing a new time period bound by the specified start and send times.
@ -945,15 +1030,24 @@ The events emitted by the Time API are:
If `tick` is false,then the bounds change was not due to an automatic tick,
and a query for historical data may be necessary, depending on your data
caching strategy, and how significantly the start bound has changed.
- `timeSystem`: emitted whenever the active time system changes. The callback will be invoked with a single argument:
- `timeSystemChanged`: emitted whenever the active time system changes. The callback will be invoked with a single argument:
- `timeSystem`: The newly active [time system](#defining-and-registering-time-systems).
- `clock`: emitted whenever the clock changes. The callback will be invoked
- `clockChanged`: emitted whenever the clock changes. The callback will be invoked
with a single argument:
- `clock`: The newly active [clock](#clocks), or `undefined` if an active
clock has been deactivated.
- `clockOffsets`: emitted whenever the active clock offsets change. The
- `clockOffsetsChanged`: emitted whenever the active clock offsets change. The
callback will be invoked with a single argument:
- `clockOffsets`: The new [clock offsets](#clock-offsets).
- `modeChanged`: emitted whenever the time [mode](#time-modes) changed. The callback will
be invoked with one argument:
- `mode`: A string representation of the current time mode, either `'realtime'` or `'fixed'`.
> ⚠️ **Deprecated Events** (These will be removed in a future release):
> - `bounds` → `boundsChanged`
> - `timeSystem` → `timeSystemChanged`
> - `clock` → `clockChanged`
> - `clockOffsets` → `clockOffsetsChanged`
### The Time Conductor