1 # This file contains functions for getting markable elements and related data.
3 utils = require('./utils')
4 viewportUtils = require('./viewport')
6 {devtools} = Cu.import('resource://devtools/shared/Loader.jsm', {})
8 _Element = Ci.nsIDOMElement
10 isElementInstance = (el) -> el instanceof _Element
12 Cu.importGlobalProperties(['Element'])
13 isElementInstance = (el) -> Element.isInstance(el)
17 find = (window, filter, selector = '*') ->
18 viewport = viewportUtils.getWindowViewport(window)
20 getMarkableElements(window, viewport, wrappers, filter, selector)
23 # `filter` is a function that is given every element in every frame of the page.
24 # It should return wrapper objects for markable elements and a falsy value for
25 # all other elements. All returned wrappers are added to `wrappers`. `wrappers`
26 # is modified instead of using return values to avoid array concatenation for
27 # each frame. It might sound expensive to go through _every_ element, but that’s
28 # actually what other methods like using XPath or CSS selectors would need to do
29 # anyway behind the scenes. However, it is possible to pass in a CSS selector,
30 # which allows getting markable elements in several passes with different sets
32 getMarkableElements = (
33 window, viewport, wrappers, filter, selector, parents = []
37 for element in getAllElements(document, selector)
38 continue unless isElementInstance(element)
39 # `getRects` is fast and filters out most elements, so run it first of all.
40 rects = getRects(element, viewport)
41 continue unless rects.insideViewport.length > 0
42 continue unless wrapper = filter(
43 element, (elementArg, tryRight = 1) ->
44 return getElementShape(
45 {window, viewport, parents, element: elementArg}, tryRight,
46 if elementArg == element then rects else null
49 wrappers.push(wrapper)
51 for frame in window.frames when frame.frameElement
52 continue unless result = viewportUtils.getFrameViewport(
53 frame.frameElement, viewport
55 {viewport: frameViewport, offset} = result
57 frame, frameViewport, wrappers, filter, selector,
58 parents.concat({window, offset})
63 findAllDOMs = (dom) ->
65 Array.from(dom.querySelectorAll('*'))
66 .filter((e) -> e.shadowRoot?)
67 .map((e) -> findAllDOMs(e.shadowRoot))...
70 getAllElements = (document, selector) ->
71 unless utils.isXULDocument(document) and document.getAnonymousNodes?
73 findAllDOMs(document).map((d) ->
74 Array.from(d.querySelectorAll(selector))
78 # Note: getAnonymousNodes() has been removed from fx72. FIXME: remove.
79 # Use a `Set` since this algorithm may find the same element more than once.
80 # Ideally we should find a way to find all elements without duplicates.
82 getAllRegular = (element) ->
83 # The first time `eb` is run `.getElementsByTagName('*')` may oddly include
84 # `undefined` in its result! Filter those out. (Also, `selector` is ignored
85 # here since it doesn’t make sense in XUL documents because of all the
86 # trickery around anonymous elements.)
87 for child in element.getElementsByTagName('*') when child
89 getAllAnonymous(child)
91 getAllAnonymous = (element) ->
92 for child in document.getAnonymousNodes(element) or []
93 continue unless isElementInstance(child)
96 getAllAnonymous(child)
98 getAllRegular(document.documentElement)
99 return Array.from(elements)
101 getRects = (element, viewport) ->
102 # `element.getClientRects()` returns a list of rectangles, usually just one,
103 # which is identical to the one returned by `element.getBoundingClientRect()`.
104 # However, if `element` is inline and line-wrapped, then it returns one
105 # rectangle for each line, since each line may be of different length, for
106 # example. That allows us to properly add hints to line-wrapped links.
107 rects = element.getClientRects?() or []
110 insideViewport: Array.prototype.filter.call(
112 (rect) -> viewportUtils.isInsideViewport(rect, viewport)
116 # Returns the “shape” of an element:
118 # - `nonCoveredPoint`: The coordinates of the first point of the element that
119 # isn’t covered by another element (except children of the element). It also
120 # contains the offset needed to make those coordinates relative to the top
121 # frame, as well as the rectangle that the coordinates occur in. It is `null`
122 # if the element is outside `viewport` or entirely covered by other elements.
123 # - `area`: The area of the part of the element that is inside the viewport.
124 # - `width`: The width of the visible rect at `nonCoveredPoint`.
125 # - `textOffset`: The distance between the left edge of the element and the left
126 # edge of its text vertically near `nonCoveredPoint`. Might be `null`. The
127 # calculation might stop early if `isBlock`.
128 # - `isBlock`: `true` if the element is a block and has several lines of text
129 # (which is the case for “cards” with an image to the left and a title as well
130 # as some text to the right (where the entire “card” is a link)). This is used
131 # to place the the marker at the edge of the block.
132 getElementShape = (elementData, tryRight, rects = null) ->
133 {viewport, element} = elementData
135 {nonCoveredPoint: null, area: 0, width: 0, textOffset: null, isBlock: false}
137 rects ?= getRects(element, viewport)
140 for rect, index in rects.insideViewport
141 visibleRect = viewportUtils.adjustRectToViewport(rect, viewport)
142 continue if visibleRect.area == 0
143 visibleRect.index = index
144 totalArea += visibleRect.area
145 visibleRects.push(visibleRect)
147 if visibleRects.length == 0
148 if rects.all.length == 1 and totalArea == 0
150 if rect.width > 0 or rect.height > 0
151 # If we get here, it means that everything inside `element` is floated
152 # and/or absolutely positioned (and that `element` hasn’t been made to
153 # “contain” the floats). For example, a link in a menu could contain a
154 # span of text floated to the left and an icon floated to the right.
155 # Those are still clickable. Therefore we return the shape of the first
156 # visible child instead. At least in that example, that’s the best bet.
157 for child in element.children
158 childData = Object.assign({}, elementData, {element: child})
159 shape = getElementShape(childData, tryRight)
160 return shape if shape
163 result.area = totalArea
165 # Even if `element` has a visible rect, it might be covered by other elements.
166 nonCoveredPoint = null
167 nonCoveredPointRect = null
168 for visibleRect in visibleRects
169 nonCoveredPoint = getFirstNonCoveredPoint(
170 elementData, visibleRect, tryRight
173 nonCoveredPointRect = visibleRect
176 return result unless nonCoveredPoint
177 result.nonCoveredPoint = nonCoveredPoint
179 result.width = nonCoveredPointRect.width
182 smallestBottom = Infinity
183 hasSingleRect = (rects.all.length == 1)
185 utils.walkTextNodes(element, (node) ->
186 unless node.data.trim() == ''
187 for quads in node.getBoxQuads()
189 bounds = quads.getBounds()
191 bounds = quads.bounds # waterfox 56
192 if bounds.width < MIN_TEXTNODE_SIZE or bounds.height < MIN_TEXTNODE_SIZE
195 if utils.overlaps(bounds, nonCoveredPointRect)
196 lefts.push(bounds.left)
199 # The element is likely a block and has several lines of text; ignore
200 # the `textOffset` (see the description of `textOffset` at the
201 # beginning of the function).
202 if bounds.top > smallestBottom
203 result.isBlock = true
206 if bounds.bottom < smallestBottom
207 smallestBottom = bounds.bottom
214 Math.round(Math.min(lefts...) - nonCoveredPointRect.left)
218 getFirstNonCoveredPoint = (elementData, elementRect, tryRight) ->
219 # Try the left-middle point, or immediately to the right of a covering element
220 # at that point (when `tryRight == 1`). If both of those are covered the whole
221 # element is considered to be covered. The reasoning is:
223 # - A marker should show up as near the left edge of its visible area as
224 # possible. Having it appear to the far right (for example) is confusing.
225 # - We can’t try too many times because of performance.
226 # - We used to try left-top first, but if the element has `border-radius`, the
227 # corners won’t belong to the element, so `document.elementFromPoint()` will
228 # return whatever is behind. One _could_ temporarily add a CSS class that
229 # removes `border-radius`, but that turned out to be too slow. Trying
230 # left-middle instead avoids the problem, and looks quite nice, actually.
231 # - We used to try left-bottom as well, but that is so rare that it’s not
234 # It is safer to try points at least one pixel into the element from the
235 # edges, hence the `+1`.
236 {left, top, bottom, height} = elementRect
238 elementData, elementRect,
239 left, +1, Math.round(top + height / 2), 0, tryRight
242 # Tries a point `(x + dx, y + dy)`. Returns `(x, y)` (and the frame offset) if
243 # the element passes the tests. Otherwise it tries to the right of whatever is
244 # at `(x, y)`, `tryRight` times . If nothing succeeds, `false` is returned. `dx`
245 # and `dy` are used to offset the wanted point `(x, y)` while trying.
246 tryPoint = (elementData, elementRect, x, dx, y, dy, tryRight = 0) ->
247 {window, viewport, parents, element} = elementData
248 elementAtPoint = window.document.elementFromPoint(x + dx, y + dy)
249 offset = {left: 0, top: 0}
253 # Ensure that `element`, or a child of `element` (anything inside an `<a>` is
254 # clickable too), really is present at (x,y). Note that this is not 100%
255 # bullet proof: Combinations of CSS can cause this check to fail, even though
256 # `element` isn’t covered. We don’t try to temporarily reset such CSS because
257 # of performance. (See further down for the special value `-1` of `tryRight`.)
258 if contains(element, elementAtPoint) or tryRight == -1
260 # If we’re currently in a frame, there might be something on top of the
261 # frame that covers `element`. Therefore we ensure that the frame really is
262 # present at the point for each parent in `parents`.
263 currentWindow = window
264 for parent in parents by -1
265 # If leaving the devtools container take the devtools zoom into account.
266 if utils.isDevtoolsWindow(currentWindow)
267 docShell = currentWindow
268 .getInterface(Ci.nsIWebNavigation)
269 .QueryInterface(Ci.nsIDocShell)
271 devtoolsZoom = docShell.contentViewer.fullZoom
272 offset.left *= devtoolsZoom
273 offset.top *= devtoolsZoom
279 offset.left += parent.offset.left
280 offset.top += parent.offset.top
281 elementAtPoint = parent.window.document.elementFromPoint(
282 offset.left + x + dx, offset.top + y + dy
285 unless contains(currentWindow.frameElement, elementAtPoint)
288 currentWindow = parent.window
290 return {x, y, offset} if found
292 return false if elementAtPoint == null or tryRight <= 0
293 rect = elementAtPoint.getBoundingClientRect()
295 # `.getBoundingClientRect()` does not include pseudo-elements that are
296 # absolutely positioned so that they go outside of the element (which is
297 # common for `/###\`-looking tabs), but calling `.elementAtPoint()` on the
298 # pseudo-element _does_ return the element. This means that the covering
299 # element’s _rect_ won’t cover the element we’re looking for. If so, it’s
300 # better to try again, forcing the element to be considered located at this
301 # point. That’s what `-1` for the `tryRight` argument means. This is also used
302 # in the 'complementary' pass, to include elements considered covered in
303 # earlier passes (which might have been false positives).
304 if firstLevel and rect.right <= x + offset.left
305 return tryPoint(elementData, elementRect, x, dx, y, dy, -1)
307 # If `elementAtPoint` is a parent to `element`, it most likely means that
308 # `element` is hidden some way. It can also mean that a pseudo-element of
309 # `elementAtPoint` covers `element` partly. Therefore, try once at the most
310 # likely point: The center of the part of the rect to the right of `x`.
311 if elementRect.right > x and contains(elementAtPoint, element)
313 elementData, elementRect,
314 (x + elementRect.right) / 2, 0, y, 0, 0
317 newX = rect.right - offset.left + 1
318 return false if newX > viewport.right or newX > elementRect.right
319 return tryPoint(elementData, elementRect, newX, 0, y, 0, tryRight - 1)
321 # In XUL documents there are “anonymous” elements. These are never returned by
322 # `document.elementFromPoint` but their closest non-anonymous parents are.
323 # The same is true for Web Components (where their hosts are returned), with
324 # the further caveat that they might be nested.
325 normalize = (element) ->
326 element = elem while (elem = element.ownerDocument.getBindingParent(element))? # <fx71
327 element = elem while (elem = element.containingShadowRoot?.host)? # >=fx72
328 element = element.parentNode while element.prefix?
331 # Returns whether `element` corresponds to `elementAtPoint`. This is only
332 # complicated for browser elements in the web page content area.
333 # `.elementAtPoint()` always returns `<tabbrowser#content>` then. The element
334 # might be in another tab and thus invisible, but `<tabbrowser#content>` is the
335 # same and visible in _all_ tabs, so we have to check that the element really
336 # belongs to the current tab.
337 contains = (element, elementAtPoint) ->
338 return false unless elementAtPoint
339 container = normalize(element)
340 if elementAtPoint.localName == 'tabbrowser' and elementAtPoint.id == 'content'
341 {gBrowser} = element.ownerGlobal.top
342 tabpanel = gBrowser.getNotificationBox(gBrowser.selectedBrowser)
343 return tabpanel.contains(element)
345 # Note that `a.contains(a)` is supposed to be true, but strangely aren’t for
346 # `<menulist>`s in the Add-ons Manager, so do a direct comparison as well.
347 return container == elementAtPoint or container.contains(elementAtPoint)