dom/chrome-webidl/InspectorUtils.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * A collection of utility methods for use by devtools.
   9  *
  10  * See InspectorUtils.h for documentation on these methods.
  11  */
  12 [Func="nsContentUtils::IsCallerChromeOrFuzzingEnabled",
  13  Exposed=Window]
  14 namespace InspectorUtils {
  15   // documentOnly tells whether user and UA sheets should get included.
  16   sequence<StyleSheet> getAllStyleSheets(Document document, optional boolean documentOnly = false);
  17   sequence<CSSStyleRule> getCSSStyleRules(
  18     Element element,
  19     optional [LegacyNullToEmptyString] DOMString pseudo = "",
  20     optional boolean relevantLinkVisited = false);
  21   unsigned long getRuleLine(CSSRule rule);
  22   unsigned long getRuleColumn(CSSRule rule);
  23   unsigned long getRelativeRuleLine(CSSRule rule);
  24   sequence<unsigned long> getRuleIndex(CSSRule rule);
  25   boolean hasRulesModifiedByCSSOM(CSSStyleSheet sheet);
  26   // Get a flat list of specific at-rules (including nested ones) of a given stylesheet.
  27   // Useful for DevTools (StyleEditor at-rules sidebar) as this is faster than in JS
  28   // where we'd have a lot of proxy access overhead building the same list.
  29   InspectorStyleSheetRuleCountAndAtRulesResult getStyleSheetRuleCountAndAtRules(CSSStyleSheet sheet);
  30   boolean isInheritedProperty(Document document, UTF8String property);
  31   sequence<DOMString> getCSSPropertyNames(optional PropertyNamesOptions options = {});
  32   sequence<PropertyPref> getCSSPropertyPrefs();
  33   [Throws] sequence<DOMString> getCSSValuesForProperty(UTF8String property);
  34   UTF8String rgbToColorName(octet r, octet g, octet b);
  35   InspectorRGBATuple? colorToRGBA(UTF8String colorString, optional Document? doc = null);
  36   InspectorColorToResult? colorTo(UTF8String fromColor, UTF8String toColorSpace);
  37   boolean isValidCSSColor(UTF8String colorString);
  38   [Throws] sequence<DOMString> getSubpropertiesForCSSProperty(UTF8String property);
  39   [Throws] boolean cssPropertyIsShorthand(UTF8String property);
  40
  41   [Throws] boolean cssPropertySupportsType(UTF8String property, InspectorPropertyType type);
  42
  43   // A version of CSS.supports that allows you to set UA or chrome context.
  44   boolean supports(UTF8String conditionText, optional SupportsOptions options = {});
  45
  46   boolean isIgnorableWhitespace(CharacterData dataNode);
  47   Node? getParentForNode(Node node, boolean showingAnonymousContent);
  48   sequence<Node> getChildrenForNode(Node node,
  49                                     boolean showingAnonymousContent,
  50                                     boolean includeAssignedNodes);
  51   [Throws] boolean setContentState(Element element, unsigned long long state);
  52   [Throws] boolean removeContentState(
  53       Element element,
  54       unsigned long long state,
  55       optional boolean clearActiveDocument = false);
  56   unsigned long long getContentState(Element element);
  57
  58   // Get the font face(s) actually used to render the text in /range/,
  59   // as a collection of InspectorFontFace objects (below).
  60   // If /maxRanges/ is greater than zero, each InspectorFontFace will record
  61   // up to /maxRanges/ fragments of content that used the face, for the caller
  62   // to access via its .ranges attribute.
  63   [NewObject, Throws] sequence<InspectorFontFace> getUsedFontFaces(
  64       Range range,
  65       optional unsigned long maxRanges = 0,
  66       optional boolean skipCollapsedWhitespace = true);
  67
  68   sequence<DOMString> getCSSPseudoElementNames();
  69   undefined addPseudoClassLock(Element element,
  70                                DOMString pseudoClass,
  71                                optional boolean enabled = true);
  72   undefined removePseudoClassLock(Element element, DOMString pseudoClass);
  73   boolean hasPseudoClassLock(Element element, DOMString pseudoClass);
  74   undefined clearPseudoClassLocks(Element element);
  75   [Throws] undefined parseStyleSheet(CSSStyleSheet sheet, UTF8String input);
  76   boolean isCustomElementName([LegacyNullToEmptyString] DOMString name,
  77                               DOMString? namespaceURI);
  78
  79   boolean isElementThemed(Element element);
  80
  81   Element? containingBlockOf(Element element);
  82
  83   // If the element is styled as display:block, returns an array of numbers giving
  84   // the number of lines in each fragment.
  85   // Returns null if the element is not a block.
  86   [NewObject] sequence<unsigned long>? getBlockLineCounts(Element element);
  87
  88   [NewObject] NodeList getOverflowingChildrenOfElement(Element element);
  89   sequence<DOMString> getRegisteredCssHighlights(Document document, optional boolean activeOnly = false);
  90   sequence<InspectorCSSPropertyDefinition> getCSSRegisteredProperties(Document document);
  91
  92   // Get the first rule body text within initialText
  93   // Consider the following example:
  94   // p {
  95   //  line-height: 2em;
  96   //  color: blue;
  97   // }
  98   // Calling the function with the whole text above would return:
  99   // "line-height: 2em; color: blue;"
 100   // Returns null when opening curly bracket wasn't found in initialText
 101   UTF8String? getRuleBodyText(UTF8String initialText);
 102
 103   // Returns string where the rule body text at passed line and column in styleSheetText
 104   // is replaced by newBodyText.
 105   UTF8String? replaceBlockRuleBodyTextInStylesheet(
 106     UTF8String styleSheetText,
 107     unsigned long line,
 108     unsigned long column,
 109     UTF8String newBodyText);
 110 };
 111
 112 dictionary SupportsOptions {
 113   boolean userAgent = false;
 114   boolean chrome = false;
 115   boolean quirks = false;
 116 };
 117
 118 dictionary PropertyNamesOptions {
 119   boolean includeAliases = false;
 120   boolean includeShorthands = true;
 121   boolean includeExperimentals = false;
 122 };
 123
 124 dictionary PropertyPref {
 125   required DOMString name;
 126   required DOMString pref;
 127 };
 128
 129 dictionary InspectorRGBATuple {
 130   /*
 131    * NOTE: This tuple is in the normal 0-255-sized RGB space but can be
 132    * fractional and may extend outside the 0-255 range.
 133    *
 134    * a is in the range 0 - 1.
 135    */
 136   double r = 0;
 137   double g = 0;
 138   double b = 0;
 139   double a = 1;
 140 };
 141
 142 dictionary InspectorColorToResult {
 143   required DOMString color;
 144   required sequence<float> components;
 145   required boolean adjusted;
 146 };
 147
 148 // Any update to this enum should probably also update
 149 // devtools/shared/css/constants.js
 150 enum InspectorPropertyType {
 151   "color",
 152   "gradient",
 153   "timing-function",
 154 };
 155
 156 dictionary InspectorVariationAxis {
 157   required DOMString tag;
 158   required DOMString name;
 159   required float minValue;
 160   required float maxValue;
 161   required float defaultValue;
 162 };
 163
 164 dictionary InspectorVariationValue {
 165   required DOMString axis;
 166   required float value;
 167 };
 168
 169 dictionary InspectorVariationInstance {
 170   required DOMString name;
 171   required sequence<InspectorVariationValue> values;
 172 };
 173
 174 dictionary InspectorFontFeature {
 175   required DOMString tag;
 176   required DOMString script;
 177   required DOMString languageSystem;
 178 };
 179
 180 dictionary InspectorCSSPropertyDefinition {
 181   required UTF8String name;
 182   required UTF8String syntax;
 183   required boolean inherits;
 184   required UTF8String? initialValue;
 185   required boolean fromJS;
 186 };
 187
 188 dictionary InspectorStyleSheetRuleCountAndAtRulesResult {
 189   required sequence<CSSRule> atRules;
 190   required unsigned long ruleCount;
 191 };
 192
 193 [Func="nsContentUtils::IsCallerChromeOrFuzzingEnabled",
 194  Exposed=Window]
 195 interface InspectorFontFace {
 196   // An indication of how we found this font during font-matching.
 197   // Note that the same physical font may have been found in multiple ways within a range.
 198   readonly attribute boolean fromFontGroup;
 199   readonly attribute boolean fromLanguagePrefs;
 200   readonly attribute boolean fromSystemFallback;
 201
 202   // available for all fonts
 203   readonly attribute DOMString name; // full font name as obtained from the font resource
 204   readonly attribute DOMString CSSFamilyName; // a family name that could be used in CSS font-family
 205                                               // (not necessarily the actual name that was used,
 206                                               // due to aliases, generics, localized names, etc)
 207   readonly attribute DOMString CSSGeneric; // CSS generic (serif, sans-serif, etc) that was mapped
 208                                            // to this font, if any (frequently empty!)
 209
 210   [NewObject,Throws] sequence<InspectorVariationAxis> getVariationAxes();
 211   [NewObject,Throws] sequence<InspectorVariationInstance> getVariationInstances();
 212   [NewObject,Throws] sequence<InspectorFontFeature> getFeatures();
 213
 214   // A list of Ranges of text rendered with this face.
 215   // This will list the first /maxRanges/ ranges found when InspectorUtils.getUsedFontFaces
 216   // was called (so it will be empty unless a non-zero maxRanges argument was passed).
 217   // Note that this indicates how the document was rendered at the time of calling
 218   // getUsedFontFaces; it does not reflect any subsequent modifications, so if styles
 219   // have been modified since calling getUsedFontFaces, it may no longer be accurate.
 220   [Constant,Cached]  readonly attribute sequence<Range> ranges;
 221
 222   // meaningful only when the font is a user font defined using @font-face
 223   readonly attribute CSSFontFaceRule? rule; // null if no associated @font-face rule
 224   readonly attribute long srcIndex; // index in the rule's src list, -1 if no @font-face rule
 225   readonly attribute DOMString URI; // empty string if not a downloaded font, i.e. local
 226   readonly attribute DOMString localName; // empty string  if not a src:local(...) rule
 227   readonly attribute DOMString format; // as per http://www.w3.org/TR/css3-webfonts/#referencing
 228   readonly attribute DOMString metadata; // XML metadata from WOFF file (if any)
 229 };
 230
 231 dictionary InspectorCSSToken {
 232   // The token type.
 233   required UTF8String tokenType;
 234
 235   // Text associated with the token.
 236   required UTF8String text;
 237
 238   // Value of the token. Might differ from `text`:
 239   // - for `Function` tokens, text contains the opening paren, `value` does not (e.g. `var(` vs `var`)
 240   // - for `AtKeyword` tokens, text contains the leading `@`, `value` does not (e.g. `@media` vs `media`)
 241   // - for `Hash` and `IDHash` tokens, text contains the leading `#`, `value` does not (e.g. `#myid` vs `myid`)
 242   // - for `UnquotedUrl` tokens, text contains the `url(` parts, `value` only holds the url (e.g. `url(test.jpg)` vs `test.jpg`)
 243   // - for `QuotedString` tokens, text contains the wrapping quotes, `value` does not (e.g. `"hello"` vs `hello`)
 244   // - for `Comment` tokens, text contains leading `/*` and trailing `*/`, `value` does not (e.g. `/* yo */` vs ` yo `)
 245   required UTF8String? value;
 246
 247   // Unit for Dimension tokens
 248   required UTF8String? unit;
 249
 250   // Float value for Dimension, Number and Percentage tokens
 251   double? number = null;
 252 };
 253
 254 /**
 255  * InspectorCSSParser is an interface to the CSS lexer. It tokenizes an
 256  * input stream and returns CSS tokens.
 257  */
 258 [Func="nsContentUtils::IsCallerChromeOrFuzzingEnabled",
 259  Exposed=Window]
 260 interface InspectorCSSParser {
 261   constructor(UTF8String text);
 262
 263   /**
 264    * The line number of the most recently returned token.  Line
 265    * numbers are 0-based.
 266    */
 267   readonly attribute unsigned long lineNumber;
 268
 269   /**
 270    * The column number of the most recently returned token.  Column
 271    * numbers are 1-based.
 272    */
 273   readonly attribute unsigned long columnNumber;
 274
 275   /**
 276    * Return the next token, or null at EOF.
 277    */
 278   InspectorCSSToken? nextToken();
 279 };