dom/chrome-webidl/UserInteraction.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/.
   4  */
   5
   6 [ChromeOnly, Exposed=Window]
   7 namespace UserInteraction {
   8   /**
   9    * Starts a timer associated with a UserInteraction ID. The timer can be
  10    * directly associated with a UserInteraction ID, or with a pair of a
  11    * UserInteraction ID and an object.
  12    *
  13    * @param id - the interaction being recorded, as
  14    * declared in UserInteractions.yaml. This is also the annotation
  15    * key that will be set in the BHR hang report if a hang occurs
  16    * before the UserInteraction is finished.
  17    *
  18    * @param value - a value to be set on the key in the event
  19    * that a hang occurs when the timer is running. This value is limited
  20    * to 50 characters to avoid abuse, and if the value exceeds that limit
  21    * then no timer is started, an error is printed, and this function returns
  22    * false.
  23    *
  24    * @param obj - Optional parameter. If specified, the timer is
  25    * associated with this object, meaning that multiple timers for the
  26    * same annotation key may be run concurrently, as long as they are
  27    * associated with different objects.
  28    *
  29    * @returns True if the timer was successfully started, false otherwise.
  30    * If a timer already exists, it will be overwritten, and the new timer
  31    * will include a "(clobbered)" suffix in any BHR annotations that get
  32    * created.
  33    */
  34   boolean start(DOMString id,
  35                 UTF8String value,
  36                 optional object? obj = null);
  37
  38   /**
  39    * Updates an already-running timer associated with a UserInteraction ID
  40    * (and object) with a new value string.
  41    *
  42    * @param id - the interaction being recorded, as
  43    * declared in UserInteractions.yaml. This is also the annotation
  44    * key that will be set in the BHR hang report if a hang occurs
  45    * before the UserInteraction is finished.
  46    *
  47    * @param value - a new value to be set on the key in the event
  48    * that a hang occurs when the timer is running. This value is limited
  49    * to 50 characters to avoid abuse.
  50    *
  51    * @param obj - Optional parameter. If specified, the timer is
  52    * associated with this object, meaning that multiple timers for the
  53    * same annotation key may be run concurrently, as long as they are
  54    * associated with different objects.
  55    *
  56    * @returns True if the timer was successfully updated, false
  57    * otherwise.
  58    */
  59   boolean update(DOMString id,
  60                  UTF8String value,
  61                  optional object? obj = null);
  62
  63   /**
  64    * Cancels the timer associated with the given UserInteraction ID
  65    * (and object) and does not add the profiler marker for it.
  66    *
  67    * @param id - the interaction being recorded, as
  68    * declared in UserInteractions.yaml.
  69    *
  70    * @param obj - Optional parameter which associates the
  71    * timer with the given object.
  72    *
  73    * @returns True if the timer was successfully stopped.
  74    */
  75   boolean cancel(DOMString id, optional object? obj = null);
  76
  77   /**
  78    * Returns whether a UserInteraction timer is currently running.
  79    *
  80    * @param id - the ID of the interaction to check, as declared in
  81    * UserInteractions.yaml.
  82    *
  83    * @param obj - Optional parameter which checks for a timer associated
  84    * with this particular object. If you're checking for a running timer
  85    * that was started with an object, you'll need to pass in that same
  86    * object here to check its running state.
  87    *
  88    * @returns True if the timer exists and is currently running.
  89    */
  90   boolean running(DOMString id, optional object? obj = null);
  91
  92   /**
  93    * Stops the timer associated with the given UserInteraction ID
  94    * (and object), calculates the time delta between start and finish,
  95    * and adds a profiler marker with that time range.
  96    *
  97    * @param id - the interaction being recorded, as
  98    * declared in UserInteractions.yaml.
  99    *
 100    * @param obj - Optional parameter which associates the
 101    * timer with the given object.
 102    *
 103    * @param additionalText - Optional parameter with includes additional
 104    * text in the profiler marker. This text is not included in the hang
 105    * annotation.
 106    *
 107    * @returns True if the timer was successfully stopped and the data
 108    * was added to the profile.
 109    */
 110   boolean finish(DOMString id,
 111                  optional object? obj = null,
 112                  optional UTF8String additionalText);
 113 };