mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-07 18:04:46 +00:00
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
This commit is contained in:
parent
8dacfff4f6
commit
7feae1e668
@ -90,7 +90,7 @@ class InspectorFront extends FrontClassWithSpec(inspectorSpec) {
|
|||||||
|
|
||||||
destroy() {
|
destroy() {
|
||||||
this._compatibility = null;
|
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`
|
// automatically destroyed. But we have to clear the `_highlighters`
|
||||||
// Map as well as explicitly call `finalize` request on all of them.
|
// Map as well as explicitly call `finalize` request on all of them.
|
||||||
this.destroyHighlighters();
|
this.destroyHighlighters();
|
||||||
|
@ -12,7 +12,6 @@ But there can be a wide variety of highlighters. In particular, highlighters are
|
|||||||
|
|
||||||
* the exact form of a css shape,
|
* the exact form of a css shape,
|
||||||
* how a css transform applied to an element,
|
* 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,
|
* 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.
|
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:
|
The InspectorFront provides the following method:
|
||||||
|
|
||||||
| 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:
|
|
||||||
|
|
||||||
| Method | Description |
|
| 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
|
### 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 |
|
| Method | Description |
|
||||||
|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
@ -19,13 +19,8 @@ loader.lazyRequireGetter(
|
|||||||
);
|
);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The registration mechanism for highlighters provide a quick way to
|
* The registration mechanism for highlighters provides a quick way to
|
||||||
* have modular highlighters, instead of a hard coded list.
|
* 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.
|
|
||||||
*/
|
*/
|
||||||
const highlighterTypes = new Map();
|
const highlighterTypes = new Map();
|
||||||
|
|
||||||
@ -38,8 +33,6 @@ exports.isTypeRegistered = isTypeRegistered;
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Registers a given constructor as highlighter, for the `typeName` given.
|
* 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) => {
|
const register = (typeName, modulePath) => {
|
||||||
if (highlighterTypes.has(typeName)) {
|
if (highlighterTypes.has(typeName)) {
|
||||||
@ -51,17 +44,16 @@ const register = (typeName, modulePath) => {
|
|||||||
exports.register = register;
|
exports.register = register;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
/**
|
* CustomHighlighterActor is a generic Actor that instantiates a custom implementation of
|
||||||
* A generic highlighter actor class that instantiate a highlighter given its
|
* a highlighter class given its type name which must be registered in `highlighterTypes`.
|
||||||
* type name and allows to show/hide it.
|
* CustomHighlighterActor proxies calls to methods of the highlighter class instance:
|
||||||
|
* constructor(targetActor), show(node, options), hide(), destroy()
|
||||||
*/
|
*/
|
||||||
exports.CustomHighlighterActor = protocol.ActorClassWithSpec(
|
exports.CustomHighlighterActor = protocol.ActorClassWithSpec(
|
||||||
customHighlighterSpec,
|
customHighlighterSpec,
|
||||||
{
|
{
|
||||||
/**
|
/**
|
||||||
* Create a highlighter instance given its typename
|
* 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()
|
|
||||||
*/
|
*/
|
||||||
initialize: function(parent, typeName) {
|
initialize: function(parent, typeName) {
|
||||||
protocol.Actor.prototype.initialize.call(this, null);
|
protocol.Actor.prototype.initialize.call(this, null);
|
||||||
@ -125,16 +117,14 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec(
|
|||||||
* method.
|
* method.
|
||||||
*
|
*
|
||||||
* Most custom highlighters are made to highlight DOM nodes, hence the first
|
* Most custom highlighters are made to highlight DOM nodes, hence the first
|
||||||
* NodeActor argument (NodeActor as in
|
* NodeActor argument (NodeActor as in devtools/server/actor/inspector).
|
||||||
* devtools/server/actor/inspector).
|
|
||||||
* Note however that some highlighters use this argument merely as a context
|
* 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.
|
* provided CSS selector on.
|
||||||
*
|
*
|
||||||
* @param {NodeActor} The node to be highlighted
|
* @param {NodeActor} The node to be highlighted
|
||||||
* @param {Object} Options for the custom highlighter
|
* @param {Object} Options for the custom highlighter
|
||||||
* @return {Boolean} True, if the highlighter has been successfully shown
|
* @return {Boolean} True, if the highlighter has been successfully shown
|
||||||
* (FF41+)
|
|
||||||
*/
|
*/
|
||||||
show: function(node, options) {
|
show: function(node, options) {
|
||||||
if (!this._highlighter) {
|
if (!this._highlighter) {
|
||||||
@ -163,8 +153,8 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec(
|
|||||||
},
|
},
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Kill this actor. This method is called automatically just before the actor
|
* Destroy the custom highlighter implementation.
|
||||||
* is destroyed.
|
* This method is called automatically just before the actor is destroyed.
|
||||||
*/
|
*/
|
||||||
finalize: function() {
|
finalize: function() {
|
||||||
if (this._highlighter) {
|
if (this._highlighter) {
|
||||||
@ -193,9 +183,9 @@ exports.CustomHighlighterActor = protocol.ActorClassWithSpec(
|
|||||||
* similarly to the BrowsingContextTargetActor.
|
* similarly to the BrowsingContextTargetActor.
|
||||||
*
|
*
|
||||||
* It can be initialized either from a BrowsingContextTargetActor (which is the
|
* It can be initialized either from a BrowsingContextTargetActor (which is the
|
||||||
* most frequent way of using it, since highlighters are usually initialized by
|
* most frequent way of using it, since highlighters are initialized by
|
||||||
* the HighlighterActor or CustomHighlighterActor, which have a targetActor
|
* CustomHighlighterActor, which has a targetActor reference).
|
||||||
* reference). It can also be initialized just with a window object (which is
|
* 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.
|
* useful for when a highlighter is used outside of the devtools server context.
|
||||||
*/
|
*/
|
||||||
function HighlighterEnvironment() {
|
function HighlighterEnvironment() {
|
||||||
|
Loading…
Reference in New Issue
Block a user