130
edits
DevTools/Highlighter: Difference between revisions
Jump to navigation
Jump to search
First version of the article
(Created page with "This article provides technical documentation about DevTools highlighters. By highlighter, we mean anything that the DevTools display on top of the content page, in order to...") |
(First version of the article) |
||
| Line 5: | Line 5: | ||
The most obvious form of highlighter is the box-model highlighter, whose job is to display the 4 box-model regions on top of a given element in the content page, as illustrated in the following screen capture: | The most obvious form of highlighter is the box-model highlighter, whose job is to display the 4 box-model regions on top of a given element in the content page, as illustrated in the following screen capture: | ||
[[File:box-model-highlighter.png | [[File:box-model-highlighter.png|Box-model highlighter]] | ||
But there can be a | But there can be a wide variety of highlighters. In particular, highlighters are a pretty good way to give detailed information about: | ||
* 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, | * 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, | ||
* | * ... | ||
== Inserting content in the page | == Using highlighters == | ||
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]] to use a highlighter. | |||
=== The highlighter utils === | |||
The easiest way to access the highlighters from toolbox-side DevTools code is by using the highlighter utils, which is conveniently available on the toolbox object. Here is how you can access the utils: | |||
let hUtils = toolbox.highlighterUtils; | |||
Since the box-model highlighter is the most used type of highlighter (for instance it's displayed when you move your mouse over nodes in the inspector), the utils provides a set of methods to interact with it: | |||
{| class="fullwidth-table wikitable" | |||
|- | |||
! 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. | |||
|- | |||
| '''highlighterNodeFront(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. | |||
|- | |||
|} | |||
But the box-model highlighter isn't the only type of highlighter, so the highlighter utils provides the following method: | |||
{| class="fullwidth-table wikitable" | |||
|- | |||
! 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''. | |||
|- | |||
|} | |||
== Inserting content in the page == | |||
Highlighters use web technology themselves to display the required information on screen. For instance, the box-model highlighter uses SVG to draw the margin, border, padding and content regions over the highlighted node. | Highlighters use web technology themselves to display the required information on screen. For instance, the box-model highlighter uses SVG to draw the margin, border, padding and content regions over the highlighted node. | ||
This means the highlighter content needs to be inserted in the page, but in a non-intrusive way. Indeed, the | This means the highlighter content needs to be inserted in the page, but in a non-intrusive way. Indeed, the DevTools should never alter the page unless the alteration was done by the user (like changing the DOM using the inspector or a CSS rule via the style-editor for example). So simply appending the highlighter's markup in the content document is not an option. | ||
Furthermore, highlighters not | Furthermore, highlighters not only need to work with Firefox Desktop, but they should work just as well on Firefox OS, Firefox for Android, and more generally anything that runs the Gecko rendering engine. Therefore appending the highlighter's markup to the browser chrome XUL structure isn't an option either. | ||
To this end, | To this end, DevTools highlighters make use of a (chrome-only) API: | ||
/** | /** | ||
| Line 39: | Line 85: | ||
[ChromeOnly, NewObject, Throws] | [ChromeOnly, NewObject, Throws] | ||
AnonymousContent insertAnonymousContent(Element aElement); | AnonymousContent insertAnonymousContent(Element aElement); | ||
/** | /** | ||
* Removes the element inserted into the CanvasFrame given an AnonymousContent | * Removes the element inserted into the CanvasFrame given an AnonymousContent | ||
| Line 60: | Line 106: | ||
Note that the returned insertedEl object isn't a DOM node, its API is described further in this article. | Note that the returned insertedEl object isn't a DOM node, its API is described further in this article. | ||
== AnonymousContent API | == == | ||
== The AnonymousContent API == | |||