UserInteraction.webidl (4449B)
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 };