/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
* You can obtain one at
http://mozilla.org/MPL/2.0/.
*/
[ChromeOnly, Exposed=Window]
namespace UserInteraction {
/**
* Starts a timer associated with a UserInteraction ID. The timer can be
* directly associated with a UserInteraction ID, or with a pair of a
* UserInteraction ID and an object.
*
* @param id - the interaction being recorded, as
* declared in UserInteractions.yaml. This is also the annotation
* key that will be set in the BHR hang report if a hang occurs
* before the UserInteraction is finished.
*
* @param value - a value to be set on the key in the event
* that a hang occurs when the timer is running. This value is limited
* to 50 characters to avoid abuse, and if the value exceeds that limit
* then no timer is started, an error is printed, and this function returns
* false.
*
* @param obj - Optional parameter. If specified, the timer is
* associated with this object, meaning that multiple timers for the
* same annotation key may be run concurrently, as long as they are
* associated with different objects.
*
* @returns True if the timer was successfully started, false otherwise.
* If a timer already exists, it will be overwritten, and the new timer
* will include a "(clobbered)" suffix in any BHR annotations that get
* created.
*/
boolean start(DOMString id,
UTF8String value,
optional object? obj = null);
/**
* Updates an already-running timer associated with a UserInteraction ID
* (and object) with a new value string.
*
* @param id - the interaction being recorded, as
* declared in UserInteractions.yaml. This is also the annotation
* key that will be set in the BHR hang report if a hang occurs
* before the UserInteraction is finished.
*
* @param value - a new value to be set on the key in the event
* that a hang occurs when the timer is running. This value is limited
* to 50 characters to avoid abuse.
*
* @param obj - Optional parameter. If specified, the timer is
* associated with this object, meaning that multiple timers for the
* same annotation key may be run concurrently, as long as they are
* associated with different objects.
*
* @returns True if the timer was successfully updated, false
* otherwise.
*/
boolean update(DOMString id,
UTF8String value,
optional object? obj = null);
/**
* Cancels the timer associated with the given UserInteraction ID
* (and object) and does not add the profiler marker for it.
*
* @param id - the interaction being recorded, as
* declared in UserInteractions.yaml.
*
* @param obj - Optional parameter which associates the
* timer with the given object.
*
* @returns True if the timer was successfully stopped.
*/
boolean cancel(DOMString id, optional object? obj = null);
/**
* Returns whether a UserInteraction timer is currently running.
*
* @param id - the ID of the interaction to check, as declared in
* UserInteractions.yaml.
*
* @param obj - Optional parameter which checks for a timer associated
* with this particular object. If you're checking for a running timer
* that was started with an object, you'll need to pass in that same
* object here to check its running state.
*
* @returns True if the timer exists and is currently running.
*/
boolean running(DOMString id, optional object? obj = null);
/**
* Stops the timer associated with the given UserInteraction ID
* (and object), calculates the time delta between start and finish,
* and adds a profiler marker with that time range.
*
* @param id - the interaction being recorded, as
* declared in UserInteractions.yaml.
*
* @param obj - Optional parameter which associates the
* timer with the given object.
*
* @param additionalText - Optional parameter with includes additional
* text in the profiler marker. This text is not included in the hang
* annotation.
*
* @returns True if the timer was successfully stopped and the data
* was added to the profile.
*/
boolean finish(DOMString id,
optional object? obj = null,
optional UTF8String additionalText);
};
