[Time] Conductors and API Enhancements

API.md

@@ -2,7 +2,7 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Building Applications With Open MCT](#developing-applications-with-open-mct)
+- [Developing Applications With Open MCT](#developing-applications-with-open-mct)
   - [Scope and purpose of this document](#scope-and-purpose-of-this-document)
   - [Building From Source](#building-from-source)
   - [Starting an Open MCT application](#starting-an-open-mct-application)
@@ -26,7 +26,7 @@
           - [Value Hints](#value-hints)
         - [The Time Conductor and Telemetry](#the-time-conductor-and-telemetry)
       - [Telemetry Providers](#telemetry-providers)
-      - [Telemetry Requests and Responses.](#telemetry-requests-and-responses)
+      - [Telemetry Requests and Responses](#telemetry-requests-and-responses)
       - [Request Strategies **draft**](#request-strategies-draft)
         - [`latest` request strategy](#latest-request-strategy)
         - [`minmax` request strategy](#minmax-request-strategy)
@@ -873,6 +873,8 @@ function without any arguments.
 
 #### Stopping an active clock
 
+_As of July 2023, this method will be deprecated. Open MCT will always have a ticking clock._
+
 The `stopClock` method can be used to stop an active clock, and to clear it. It
 will stop the clock from ticking, and set the active clock to `undefined`.
 

example/imagery/plugin.js

@@ -156,9 +156,9 @@ export default function () {
       key: 'thumbnail',
       ...formatThumbnail
     });
-    openmct.telemetry.addProvider(getRealtimeProvider());
-    openmct.telemetry.addProvider(getHistoricalProvider());
-    openmct.telemetry.addProvider(getLadProvider());
+    openmct.telemetry.addProvider(getRealtimeProvider(openmct));
+    openmct.telemetry.addProvider(getHistoricalProvider(openmct));
+    openmct.telemetry.addProvider(getLadProvider(openmct));
   };
 }
 
@@ -207,14 +207,14 @@ function getImageLoadDelay(domainObject) {
   return imageLoadDelay;
 }
 
-function getRealtimeProvider() {
+function getRealtimeProvider(openmct) {
   return {
     supportsSubscribe: (domainObject) => domainObject.type === 'example.imagery',
     subscribe: (domainObject, callback) => {
       const delay = getImageLoadDelay(domainObject);
       const interval = setInterval(() => {
         const imageSamples = getImageSamples(domainObject.configuration);
-        const datum = pointForTimestamp(Date.now(), domainObject.name, imageSamples, delay);
+        const datum = pointForTimestamp(openmct.time.now(), domainObject.name, imageSamples, delay);
         callback(datum);
       }, delay);
 
@@ -225,15 +225,15 @@ function getRealtimeProvider() {
   };
 }
 
-function getHistoricalProvider() {
+function getHistoricalProvider(openmct) {
   return {
     supportsRequest: (domainObject, options) => {
       return domainObject.type === 'example.imagery' && options.strategy !== 'latest';
     },
     request: (domainObject, options) => {
       const delay = getImageLoadDelay(domainObject);
       let start = options.start;
-      const end = Math.min(options.end, Date.now());
+      const end = Math.min(options.end, openmct.time.now());
       const data = [];
       while (start <= end && data.length < delay) {
         data.push(
@@ -252,15 +252,15 @@ function getHistoricalProvider() {
   };
 }
 
-function getLadProvider() {
+function getLadProvider(openmct) {
   return {
     supportsRequest: (domainObject, options) => {
       return domainObject.type === 'example.imagery' && options.strategy === 'latest';
     },
     request: (domainObject, options) => {
       const delay = getImageLoadDelay(domainObject);
       const datum = pointForTimestamp(
-        Date.now(),
+        openmct.time.now(),
         domainObject.name,
         getImageSamples(domainObject.configuration),
         delay

src/api/menu/components/SuperMenu.vue

@@ -58,7 +58,6 @@
         :key="action.name"
         role="menuitem"
         :class="action.cssClass"
-        :title="action.description"
         :data-testid="action.testId || false"
         @click="action.onItemClicked"
         @mouseover="toggleItemDescription(action)"

src/api/time/IndependentTimeContext.js

@@ -20,7 +20,8 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import TimeContext, { TIME_CONTEXT_EVENTS } from './TimeContext';
+import TimeContext from './TimeContext';
+import { REALTIME_MODE_KEY, TIME_CONTEXT_EVENTS } from './constants';
 
 /**
  * The IndependentTimeContext handles getting and setting time of the openmct application in general.
@@ -46,35 +47,59 @@ class IndependentTimeContext extends TimeContext {
     this.globalTimeContext.on('removeOwnContext', this.removeIndependentContext);
   }
 
-  bounds(newBounds) {
+  bounds() {
     if (this.upstreamTimeContext) {
       return this.upstreamTimeContext.bounds(...arguments);
     } else {
       return super.bounds(...arguments);
     }
   }
 
-  tick(timestamp) {
+  getBounds() {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.getBounds();
+    } else {
+      return super.getBounds();
+    }
+  }
+
+  setBounds() {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.setBounds(...arguments);
+    } else {
+      return super.setBounds(...arguments);
+    }
+  }
+
+  tick() {
     if (this.upstreamTimeContext) {
       return this.upstreamTimeContext.tick(...arguments);
     } else {
       return super.tick(...arguments);
     }
   }
 
-  clockOffsets(offsets) {
+  clockOffsets() {
     if (this.upstreamTimeContext) {
       return this.upstreamTimeContext.clockOffsets(...arguments);
     } else {
       return super.clockOffsets(...arguments);
     }
   }
 
-  stopClock() {
+  getClockOffsets() {
     if (this.upstreamTimeContext) {
-      this.upstreamTimeContext.stopClock();
+      return this.upstreamTimeContext.getClockOffsets();
     } else {
-      super.stopClock();
+      return super.getClockOffsets();
+    }
+  }
+
+  setClockOffsets() {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.setClockOffsets(...arguments);
+    } else {
+      return super.setClockOffsets(...arguments);
     }
   }
 
@@ -86,10 +111,19 @@ class IndependentTimeContext extends TimeContext {
     return this.globalTimeContext.timeSystem(...arguments);
   }
 
+  /**
+   * Get the time system of the TimeAPI.
+   * @returns {TimeSystem} The currently applied time system
+   * @memberof module:openmct.TimeAPI#
+   * @method getTimeSystem
+   */
+  getTimeSystem() {
+    return this.globalTimeContext.getTimeSystem();
+  }
+
   /**
    * Set the active clock. Tick source will be immediately subscribed to
-   * and ticking will begin. Offsets from 'now' must also be provided. A clock
-   * can be unset by calling {@link stopClock}.
+   * and ticking will begin. Offsets from 'now' must also be provided.
    *
    * @param {Clock || string} keyOrClock The clock to activate, or its key
    * @param {ClockOffsets} offsets on each tick these will be used to calculate
@@ -126,15 +160,18 @@ class IndependentTimeContext extends TimeContext {
       this.activeClock = clock;
 
       /**
-       * The active clock has changed. Clock can be unset by calling {@link stopClock}
+       * The active clock has changed.
        * @event clock
        * @memberof module:openmct.TimeAPI~
        * @property {Clock} clock The newly activated clock, or undefined
        * if the system is no longer following a clock source
        */
       this.emit('clock', this.activeClock);
+      this.emit(TIME_CONTEXT_EVENTS.clockChanged, this.activeClock);
 
       if (this.activeClock !== undefined) {
+        this.setMode(REALTIME_MODE_KEY);
+
         this.clockOffsets(offsets);
         this.activeClock.on('tick', this.tick);
       }
@@ -145,14 +182,125 @@ class IndependentTimeContext extends TimeContext {
     return this.activeClock;
   }
 
+  /**
+   * Get the active clock.
+   * @return {Clock} the currently active clock;
+   */
+  getClock() {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.getClock();
+    }
+
+    return this.activeClock;
+  }
+
+  /**
+   * Set the active clock. Tick source will be immediately subscribed to
+   * and the currently ticking will begin.
+   * Offsets from 'now', if provided, will be used to set realtime mode offsets
+   *
+   * @param {Clock || string} keyOrClock The clock to activate, or its key
+   * @param {ClockOffsets} offsets on each tick these will be used to calculate
+   * the start and end bounds when in realtime mode.
+   * This maintains a sliding time window of a fixed width that automatically updates.
+   * @fires module:openmct.TimeAPI~clock
+   * @return {Clock} the currently active clock;
+   */
+  setClock(keyOrClock, offsets) {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.setClock(...arguments);
+    }
+
+    let clock;
+
+    if (typeof keyOrClock === 'string') {
+      clock = this.globalTimeContext.clocks.get(keyOrClock);
+      if (clock === undefined) {
+        throw `Unknown clock ${keyOrClock}. Has it been registered with 'addClock'?`;
+      }
+    } else if (typeof keyOrClock === 'object') {
+      clock = keyOrClock;
+      if (!this.globalTimeContext.clocks.has(clock.key)) {
+        throw `Unknown clock ${keyOrClock.key}. Has it been registered with 'addClock'?`;
+      }
+    }
+
+    // this.setMode(REALTIME_MODE_KEY);
+
+    const previousClock = this.activeClock;
+    if (previousClock) {
+      previousClock.off('tick', this.tick);
+    }
+
+    this.activeClock = clock;
+    this.activeClock.on('tick', this.tick);
+
+    /**
+     * The active clock has changed.
+     * @event clock
+     * @memberof module:openmct.TimeAPI~
+     * @property {Clock} clock The newly activated clock, or undefined
+     * if the system is no longer following a clock source
+     */
+    this.emit(TIME_CONTEXT_EVENTS.clockChanged, this.activeClock);
+
+    if (offsets !== undefined) {
+      this.setClockOffsets(offsets);
+    }
+
+    return this.activeClock;
+  }
+
+  /**
+   * Get the current mode.
+   * @return {Mode} the current mode;
+   */
+  getMode() {
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.getMode();
+    }
+
+    return this.mode;
+  }
+
+  /**
+   * Set the mode to either fixed or realtime.
+   *
+   * @param {Mode} mode The mode to activate
+   * @fires module:openmct.TimeAPI~clock
+   * @return {Mode} the currently active mode;
+   */
+  setMode(mode) {
+    if (!mode || mode === this.mode) {
+      return;
+    }
+
+    if (this.upstreamTimeContext) {
+      return this.upstreamTimeContext.setMode(...arguments);
+    }
+
+    this.mode = mode;
+
+    /**
+     * The active clock has changed.
+     * @event clock
+     * @memberof module:openmct.TimeAPI~
+     * @property {Clock} clock The newly activated clock, or undefined
+     * if the system is no longer following a clock source
+     */
+    this.emit(TIME_CONTEXT_EVENTS.modeChanged, this.#copy(this.mode));
+
+    return this.mode;
+  }
+
   /**
    * Causes this time context to follow another time context (either the global context, or another upstream time context)
    * This allows views to have their own time context which points to the appropriate upstream context as necessary, achieving nesting.
    */
   followTimeContext() {
     this.stopFollowingTimeContext();
     if (this.upstreamTimeContext) {
-      TIME_CONTEXT_EVENTS.forEach((eventName) => {
+      Object.values(TIME_CONTEXT_EVENTS).forEach((eventName) => {
         const thisTimeContext = this;
         this.upstreamTimeContext.on(eventName, passthrough);
         this.unlisteners.push(() => {
@@ -197,6 +345,7 @@ class IndependentTimeContext extends TimeContext {
 
     // Emit bounds so that views that are changing context get the upstream bounds
     this.emit('bounds', this.bounds());
+    this.emit(TIME_CONTEXT_EVENTS.boundsChanged, this.getBounds());
   }
 
   hasOwnContext() {
@@ -259,11 +408,16 @@ class IndependentTimeContext extends TimeContext {
       this.followTimeContext();
 
       // Emit bounds so that views that are changing context get the upstream bounds
-      this.emit('bounds', this.bounds());
+      this.emit('bounds', this.getBounds());
+      this.emit(TIME_CONTEXT_EVENTS.boundsChanged, this.getBounds());
       // now that the view's context is set, tell others to check theirs in case they were following this view's context.
       this.globalTimeContext.emit('refreshContext', viewKey);
     }
   }
+
+  #copy(object) {
+    return JSON.parse(JSON.stringify(object));
+  }
 }
 
 export default IndependentTimeContext;