From 1d2ad58af3c038aae0de4eb9d1558c93cfcf0e65 Mon Sep 17 00:00:00 2001 From: Razvan Caliman Date: Wed, 14 Oct 2020 14:19:39 +0000 Subject: [PATCH] Bug 1623667 - [devtools] Update CustomHighlighterActor comments and docs r=ochameau Depends on D92220 Rephrasing of code comments and cleanup of documentation to reflect that `CustomHighlighterActor` is now the only actor which deals with highlighting stuff after removing `HighlighterActor` in D92220. No functionality is changed in this patch. Differential Revision: https://phabricator.services.mozilla.com/D92221 --- devtools/client/fronts/inspector.js | 2 +- devtools/docs/tools/highlighters.md | 25 ++--------------- devtools/server/actors/highlighters.js | 38 ++++++++++---------------- 3 files changed, 18 insertions(+), 47 deletions(-) diff --git a/devtools/client/fronts/inspector.js b/devtools/client/fronts/inspector.js index cc6f2757648a..27acf4f1b09b 100644 --- a/devtools/client/fronts/inspector.js +++ b/devtools/client/fronts/inspector.js @@ -90,7 +90,7 @@ class InspectorFront extends FrontClassWithSpec(inspectorSpec) { destroy() { this._compatibility = null; - // Highlighter fronts are managed by InspectorFront and so will be + // CustomHighlighter fronts are managed by InspectorFront and so will be // automatically destroyed. But we have to clear the `_highlighters` // Map as well as explicitly call `finalize` request on all of them. this.destroyHighlighters(); diff --git a/devtools/docs/tools/highlighters.md b/devtools/docs/tools/highlighters.md index 07d36a7c600e..65905dc46a77 100644 --- a/devtools/docs/tools/highlighters.md +++ b/devtools/docs/tools/highlighters.md @@ -12,7 +12,6 @@ But there can be a wide variety of highlighters. In particular, highlighters are * the exact form of a css shape, * how a css transform applied to an element, -* where are the color stops of a css gradient, * which are all the elements that match a given selector, * ... @@ -20,33 +19,15 @@ But there can be a wide variety of highlighters. In particular, highlighters are Highlighters run on the debuggee side, not on the toolbox side. This is so that it's possible to highlight elements on a remote device for instance. This means you need to go through the [Remote Debugging Protocol](protocol.md) to use a highlighter. -Since the box-model highlighter (HighlighterFront) is the most used type of highlighter (for instance it's displayed when you move your mouse over nodes in the inspector), the HighlighterFront provides a custom set of methods to interact with it: - -| Method | Description | -|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `startPicker()` | Starts the node picker mode which will highlight every node you hover over in the page, and will change the current node selection in the inspector on click. “picker-node-hovered” and “picker-node-picked” events are sent. | -| `stopPicker()` | Stops the node picker mode. | -| `highlightNodeFront(nodeFront)` | Display the box-model highlighter on a given node. NodeFront objects are what the WalkerActor return. | -| `highlightDomValueGrip(valueGrip)` | Display the box-model highlighter on a given node, represented by a debugger object value grip. | -| `unhighlight()` | Hide the box-model highlighter. | - -Not all methods that are related to highlighters are present on the HighlighterFront. The -`highlightDomValueGrip` method also requires the WalkerFront in order to transform a Grip into a -NodeFront. Therefore, methods that access other Fronts are available on the InspectorFront. - -| Method | Description | -|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `highlightDomValueGrip(valueGrip)` | Display the box-model highlighter on a given node, represented by a debugger object value grip. | - -But the box-model highlighter isn't the only type of highlighter, so the InspectorFront also provides the following method: +The InspectorFront provides the following method: | Method | Description | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `getHighlighterByType(typeName)` | Instantiate a new highlighter, given its type (as a String). At the time of writing, the available types of highlighters are: `BoxModelHighlighter`, `CssTransformHighlighter`, `SelectorHighlighter` and `RectHighlighter`. This returns a promise that resolves to the new instance of [protocol.js](https://wiki.mozilla.org/DevTools/protocol.js) actor. | +| `getHighlighterByType(typeName)` | Instantiate a new highlighter, given its type (as a String). At the time of writing, the available types of highlighters are: `CssGridHighlighter`, `BoxModelHighlighter`, `CssTransformHighlighter`, `FlexboxHighlighter`, `FontsHighlighter`, `GeometryEditorHighlighter`, `MeasuringToolHighlighter`, `PausedDebuggerOverlay`, `RulersHighlighter`, `SelectorHighlighter` and `ShapesHighlighter`. This returns a promise that resolves to the new instance of [protocol.js](https://wiki.mozilla.org/DevTools/protocol.js) actor. | ### The highlighter API -When getting a highlighter via `toolbox.inspector.getHighlighterByType(typeName)`, the right type of highlighter will be instantiated on the server-side and will be wrapped into a `CustomHighlighterActor` and that's what will be returned to the caller. This means that all types of highlighters share the same following API: +When getting a highlighter via `InspectorFront.getHighlighterByType(typeName)`, the right type of highlighter will be instantiated on the server-side and will be wrapped into a `CustomHighlighterActor` and that's what will be returned to the caller. This means that all types of highlighters share the same following API: | Method | Description | |------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/devtools/server/actors/highlighters.js b/devtools/server/actors/highlighters.js index 0c2ac26e84e3..70a27307c96d 100644 --- a/devtools/server/actors/highlighters.js +++ b/devtools/server/actors/highlighters.js @@ -19,13 +19,8 @@ loader.lazyRequireGetter( ); /** - * The registration mechanism for highlighters provide a quick way to - * have modular highlighters, instead of a hard coded list. - * It allow us to split highlighers in sub modules, and add them dynamically - * using add-on (useful for 3rd party developers, or prototyping) - * - * Note that currently, highlighters added using add-ons, can only work on - * Firefox desktop, or Fennec if the same add-on is installed in both. + * The registration mechanism for highlighters provides a quick way to + * have modular highlighters instead of a hard coded list. */ const highlighterTypes = new Map(); @@ -38,8 +33,6 @@ exports.isTypeRegistered = isTypeRegistered; /** * Registers a given constructor as highlighter, for the `typeName` given. - * If no `typeName` is provided, the `typeName` property on the constructor's prototype - * is used, if one is found, otherwise the name of the constructor function is used. */ const register = (typeName, modulePath) => { if (highlighterTypes.has(typeName)) { @@ -51,17 +44,16 @@ const register = (typeName, modulePath) => { exports.register = register; /** -/** - * A generic highlighter actor class that instantiate a highlighter given its - * type name and allows to show/hide it. + * CustomHighlighterActor is a generic Actor that instantiates a custom implementation of + * a highlighter class given its type name which must be registered in `highlighterTypes`. + * CustomHighlighterActor proxies calls to methods of the highlighter class instance: + * constructor(targetActor), show(node, options), hide(), destroy() */ exports.CustomHighlighterActor = protocol.ActorClassWithSpec( customHighlighterSpec, { /** - * Create a highlighter instance given its typename - * The typename must be one of HIGHLIGHTER_CLASSES and the class must - * implement constructor(targetActor), show(node), hide(), destroy() + * Create a highlighter instance given its typeName. */ initialize: function(parent, typeName) { protocol.Actor.prototype.initialize.call(this, null); @@ -125,16 +117,14 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec( * method. * * Most custom highlighters are made to highlight DOM nodes, hence the first - * NodeActor argument (NodeActor as in - * devtools/server/actor/inspector). + * NodeActor argument (NodeActor as in devtools/server/actor/inspector). * Note however that some highlighters use this argument merely as a context - * node: The SelectHighlighter for instance uses it as a base node to run the + * node: The SelectorHighlighter for instance uses it as a base node to run the * provided CSS selector on. * * @param {NodeActor} The node to be highlighted * @param {Object} Options for the custom highlighter * @return {Boolean} True, if the highlighter has been successfully shown - * (FF41+) */ show: function(node, options) { if (!this._highlighter) { @@ -163,8 +153,8 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec( }, /** - * Kill this actor. This method is called automatically just before the actor - * is destroyed. + * Destroy the custom highlighter implementation. + * This method is called automatically just before the actor is destroyed. */ finalize: function() { if (this._highlighter) { @@ -193,9 +183,9 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec( * similarly to the BrowsingContextTargetActor. * * It can be initialized either from a BrowsingContextTargetActor (which is the - * most frequent way of using it, since highlighters are usually initialized by - * the HighlighterActor or CustomHighlighterActor, which have a targetActor - * reference). It can also be initialized just with a window object (which is + * most frequent way of using it, since highlighters are initialized by + * CustomHighlighterActor, which has a targetActor reference). + * It can also be initialized just with a window object (which is * useful for when a highlighter is used outside of the devtools server context. */ function HighlighterEnvironment() {