зеркало из https://github.com/mozilla/gecko-dev.git
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:
Razvan Caliman
Родитель
e7d88cfad5
Коммит
1d2ad58af3
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче