extension/lib/markable-elements.coffee

   1 ###
   2 # Copyright Anton Khodakivskiy 2012, 2013.
   3 # Copyright Simon Lydell 2013, 2014, 2015, 2016.
   4 #
   5 # This file is part of VimFx.
   6 #
   7 # VimFx is free software: you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation, either version 3 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # VimFx is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with VimFx.  If not, see <http://www.gnu.org/licenses/>.
  19 ###
  20
  21 # This file contains functions for getting markable elements and related data.
  22
  23 utils = require('./utils')
  24 viewportUtils = require('./viewport')
  25
  26 {devtools} = Cu.import('resource://devtools/shared/Loader.jsm', {})
  27
  28 Element = Ci.nsIDOMElement
  29 XULDocument = Ci.nsIDOMXULDocument
  30
  31 MIN_TEXTNODE_SIZE = 4
  32
  33 find = (window, filter, selector = '*') ->
  34   viewport = viewportUtils.getWindowViewport(window)
  35   wrappers = []
  36   getMarkableElements(window, viewport, wrappers, filter, selector)
  37   return wrappers
  38
  39 # `filter` is a function that is given every element in every frame of the page.
  40 # It should return wrapper objects for markable elements and a falsy value for
  41 # all other elements. All returned wrappers are added to `wrappers`. `wrappers`
  42 # is modified instead of using return values to avoid array concatenation for
  43 # each frame. It might sound expensive to go through _every_ element, but that’s
  44 # actually what other methods like using XPath or CSS selectors would need to do
  45 # anyway behind the scenes. However, it is possible to pass in a CSS selector,
  46 # which allows getting markable elements in several passes with different sets
  47 # of candidates.
  48 getMarkableElements = (
  49   window, viewport, wrappers, filter, selector, parents = []
  50 ) ->
  51   {document} = window
  52
  53   for element in getAllElements(document, selector)
  54     continue unless element instanceof Element
  55     # `getRects` is fast and filters out most elements, so run it first of all.
  56     rects = getRects(element, viewport)
  57     continue unless rects.insideViewport.length > 0
  58     continue unless wrapper = filter(
  59       element, (elementArg, tryRight = 1) ->
  60         return getElementShape(
  61           {window, viewport, parents, element: elementArg}, tryRight,
  62           if elementArg == element then rects else null
  63         )
  64     )
  65     wrappers.push(wrapper)
  66
  67   for frame in window.frames when frame.frameElement
  68     continue unless result = viewportUtils.getFrameViewport(
  69       frame.frameElement, viewport
  70     )
  71     {viewport: frameViewport, offset} = result
  72     getMarkableElements(
  73       frame, frameViewport, wrappers, filter, selector,
  74       parents.concat({window, offset})
  75     )
  76
  77   return
  78
  79 getAllElements = (document, selector) ->
  80   unless document instanceof XULDocument
  81     return document.querySelectorAll(selector)
  82
  83   # Use a `Set` since this algorithm may find the same element more than once.
  84   # Ideally we should find a way to find all elements without duplicates.
  85   elements = new Set()
  86   getAllRegular = (element) ->
  87     # The first time `eb` is run `.getElementsByTagName('*')` may oddly include
  88     # `undefined` in its result! Filter those out. (Also, `selector` is ignored
  89     # here since it doesn’t make sense in XUL documents because of all the
  90     # trickery around anonymous elements.)
  91     for child in element.getElementsByTagName('*') when child
  92       elements.add(child)
  93       getAllAnonymous(child)
  94     return
  95   getAllAnonymous = (element) ->
  96     for child in document.getAnonymousNodes(element) or []
  97       continue unless child instanceof Element
  98       elements.add(child)
  99       getAllRegular(child)
 100       getAllAnonymous(child)
 101     return
 102   getAllRegular(document.documentElement)
 103   return Array.from(elements)
 104
 105 getRects = (element, viewport) ->
 106   # `element.getClientRects()` returns a list of rectangles, usually just one,
 107   # which is identical to the one returned by `element.getBoundingClientRect()`.
 108   # However, if `element` is inline and line-wrapped, then it returns one
 109   # rectangle for each line, since each line may be of different length, for
 110   # example. That allows us to properly add hints to line-wrapped links.
 111   rects = element.getClientRects()
 112   return {
 113     all: rects,
 114     insideViewport: Array.filter(
 115       rects,
 116       (rect) -> viewportUtils.isInsideViewport(rect, viewport)
 117     )
 118   }
 119
 120 # Returns the “shape” of an element:
 121 #
 122 # - `nonCoveredPoint`: The coordinates of the first point of the element that
 123 #   isn’t covered by another element (except children of the element). It also
 124 #   contains the offset needed to make those coordinates relative to the top
 125 #   frame, as well as the rectangle that the coordinates occur in. It is `null`
 126 #   if the element is outside `viewport` or entirely covered by other elements.
 127 # - `area`: The area of the part of the element that is inside the viewport.
 128 # - `width`: The width of the visible rect at `nonCoveredPoint`.
 129 # - `textOffset`: The distance between the left edge of the element and the left
 130 #   edge of its text vertically near `nonCoveredPoint`. If the element is a
 131 #   block and has several lines of text, this is set to `null` so that the
 132 #   marker is placed at the edge of the block. That’s the case for “cards” with
 133 #   an image to the left and a title as well as some text to the right (where
 134 #   the entire “card” is a link).
 135 getElementShape = (elementData, tryRight, rects = null) ->
 136   {viewport, element} = elementData
 137   result = {nonCoveredPoint: null, area: 0, width: 0, textOffset: null}
 138
 139   rects ?= getRects(element, viewport)
 140   totalArea = 0
 141   visibleRects = []
 142   for rect, index in rects.insideViewport
 143     visibleRect = viewportUtils.adjustRectToViewport(rect, viewport)
 144     continue if visibleRect.area == 0
 145     visibleRect.index = index
 146     totalArea += visibleRect.area
 147     visibleRects.push(visibleRect)
 148
 149   if visibleRects.length == 0
 150     if rects.all.length == 1 and totalArea == 0
 151       [rect] = rects.all
 152       if rect.width > 0 or rect.height > 0
 153         # If we get here, it means that everything inside `element` is floated
 154         # and/or absolutely positioned (and that `element` hasn’t been made to
 155         # “contain” the floats). For example, a link in a menu could contain a
 156         # span of text floated to the left and an icon floated to the right.
 157         # Those are still clickable. Therefore we return the shape of the first
 158         # visible child instead. At least in that example, that’s the best bet.
 159         for child in element.children
 160           childData = Object.assign({}, elementData, {element: child})
 161           shape = getElementShape(childData, tryRight)
 162           return shape if shape
 163     return result
 164
 165   result.area = totalArea
 166
 167   # Even if `element` has a visible rect, it might be covered by other elements.
 168   nonCoveredPoint = null
 169   nonCoveredPointRect = null
 170   for visibleRect in visibleRects
 171     nonCoveredPoint = getFirstNonCoveredPoint(
 172       elementData, visibleRect, tryRight
 173     )
 174     if nonCoveredPoint
 175       nonCoveredPointRect = visibleRect
 176       break
 177
 178   return result unless nonCoveredPoint
 179   result.nonCoveredPoint = nonCoveredPoint
 180
 181   result.width = nonCoveredPointRect.width
 182
 183   lefts = []
 184   smallestBottom = Infinity
 185   hasSingleRect = (rects.all.length == 1)
 186
 187   utils.walkTextNodes(element, (node) ->
 188     unless node.data.trim() == ''
 189       for {bounds} in node.getBoxQuads()
 190         if bounds.width < MIN_TEXTNODE_SIZE or bounds.height < MIN_TEXTNODE_SIZE
 191           continue
 192
 193         if utils.overlaps(bounds, nonCoveredPointRect)
 194           lefts.push(bounds.left)
 195
 196         if hasSingleRect
 197           # The element is likely a block and has several lines of text; ignore
 198           # the `textOffset` (see the description of `textOffset` at the
 199           # beginning of the function).
 200           if bounds.top > smallestBottom
 201             lefts = []
 202             return true
 203
 204           if bounds.bottom < smallestBottom
 205             smallestBottom = bounds.bottom
 206
 207     return false
 208   )
 209
 210   if lefts.length > 0
 211     result.textOffset =
 212       Math.round(Math.min(lefts...) - nonCoveredPointRect.left)
 213
 214   return result
 215
 216 getFirstNonCoveredPoint = (elementData, elementRect, tryRight) ->
 217   # Try the left-middle point, or immediately to the right of a covering element
 218   # at that point (when `tryRight == 1`). If both of those are covered the whole
 219   # element is considered to be covered. The reasoning is:
 220   #
 221   # - A marker should show up as near the left edge of its visible area as
 222   #   possible. Having it appear to the far right (for example) is confusing.
 223   # - We can’t try too many times because of performance.
 224   # - We used to try left-top first, but if the element has `border-radius`, the
 225   #   corners won’t belong to the element, so `document.elementFromPoint()` will
 226   #   return whatever is behind. One _could_ temporarily add a CSS class that
 227   #   removes `border-radius`, but that turned out to be too slow. Trying
 228   #   left-middle instead avoids the problem, and looks quite nice, actually.
 229   # - We used to try left-bottom as well, but that is so rare that it’s not
 230   #   worth it.
 231   #
 232   # It is safer to try points at least one pixel into the element from the
 233   # edges, hence the `+1`.
 234   {left, top, bottom, height} = elementRect
 235   return tryPoint(
 236     elementData, elementRect,
 237     left, +1, Math.round(top + height / 2), 0, tryRight
 238   )
 239
 240 # Tries a point `(x + dx, y + dy)`. Returns `(x, y)` (and the frame offset) if
 241 # the element passes the tests. Otherwise it tries to the right of whatever is
 242 # at `(x, y)`, `tryRight` times . If nothing succeeds, `false` is returned. `dx`
 243 # and `dy` are used to offset the wanted point `(x, y)` while trying.
 244 tryPoint = (elementData, elementRect, x, dx, y, dy, tryRight = 0) ->
 245   {window, viewport, parents, element} = elementData
 246   elementAtPoint = window.document.elementFromPoint(x + dx, y + dy)
 247   offset = {left: 0, top: 0}
 248   found = false
 249   firstLevel = true
 250
 251   # Ensure that `element`, or a child of `element` (anything inside an `<a>` is
 252   # clickable too), really is present at (x,y). Note that this is not 100%
 253   # bullet proof: Combinations of CSS can cause this check to fail, even though
 254   # `element` isn’t covered. We don’t try to temporarily reset such CSS because
 255   # of performance. (See further down for the special value `-1` of `tryRight`.)
 256   if contains(element, elementAtPoint) or tryRight == -1
 257     found = true
 258     # If we’re currently in a frame, there might be something on top of the
 259     # frame that covers `element`. Therefore we ensure that the frame really is
 260     # present at the point for each parent in `parents`.
 261     currentWindow = window
 262     for parent in parents by -1
 263       # If leaving the devtools container take the devtools zoom into account.
 264       if utils.isDevtoolsWindow(currentWindow)
 265         docShell = currentWindow
 266           .QueryInterface(Ci.nsIInterfaceRequestor)
 267           .getInterface(Ci.nsIWebNavigation)
 268           .QueryInterface(Ci.nsIDocShell)
 269         if docShell
 270           devtoolsZoom = docShell.contentViewer.fullZoom
 271           offset.left *= devtoolsZoom
 272           offset.top  *= devtoolsZoom
 273           x  *= devtoolsZoom
 274           y  *= devtoolsZoom
 275           dx *= devtoolsZoom
 276           dy *= devtoolsZoom
 277
 278       offset.left += parent.offset.left
 279       offset.top  += parent.offset.top
 280       elementAtPoint = parent.window.document.elementFromPoint(
 281         offset.left + x + dx, offset.top + y + dy
 282       )
 283       firstLevel = false
 284       unless contains(currentWindow.frameElement, elementAtPoint)
 285         found = false
 286         break
 287       currentWindow = parent.window
 288
 289   return {x, y, offset} if found
 290
 291   return false if elementAtPoint == null or tryRight <= 0
 292   rect = elementAtPoint.getBoundingClientRect()
 293
 294   # `.getBoundingClientRect()` does not include pseudo-elements that are
 295   # absolutely positioned so that they go outside of the element (which is
 296   # common for `/###\`-looking tabs), but calling `.elementAtPoint()` on the
 297   # pseudo-element _does_ return the element. This means that the covering
 298   # element’s _rect_ won’t cover the element we’re looking for. If so, it’s
 299   # better to try again, forcing the element to be considered located at this
 300   # point. That’s what `-1` for the `tryRight` argument means. This is also used
 301   # in the 'complementary' pass, to include elements considered covered in
 302   # earlier passes (which might have been false positives).
 303   if firstLevel and rect.right <= x + offset.left
 304     return tryPoint(elementData, elementRect, x, dx, y, dy, -1)
 305
 306   # If `elementAtPoint` is a parent to `element`, it most likely means that
 307   # `element` is hidden some way. It can also mean that a pseudo-element of
 308   # `elementAtPoint` covers `element` partly. Therefore, try once at the most
 309   # likely point: The center of the part of the rect to the right of `x`.
 310   if elementRect.right > x and contains(elementAtPoint, element)
 311     return tryPoint(
 312       elementData, elementRect,
 313       (x + elementRect.right) / 2, 0, y, 0, 0
 314     )
 315
 316   newX = rect.right - offset.left + 1
 317   return false if newX > viewport.right or newX > elementRect.right
 318   return tryPoint(elementData, elementRect, newX, 0, y, 0, tryRight - 1)
 319
 320 # In XUL documents there are “anonymous” elements. These are never returned by
 321 # `document.elementFromPoint` but their closest non-anonymous parents are.
 322 normalize = (element) ->
 323   normalized = element.ownerDocument.getBindingParent(element) or element
 324   normalized = normalized.parentNode while normalized.prefix?
 325   return normalized
 326
 327 # Returns whether `element` corresponds to `elementAtPoint`. This is only
 328 # complicated for browser elements in the web page content area.
 329 # `.elementAtPoint()` always returns `<tabbrowser#content>` then. The element
 330 # might be in another tab and thus invisible, but `<tabbrowser#content>` is the
 331 # same and visible in _all_ tabs, so we have to check that the element really
 332 # belongs to the current tab.
 333 contains = (element, elementAtPoint) ->
 334   return false unless elementAtPoint
 335   container = normalize(element)
 336   if elementAtPoint.localName == 'tabbrowser' and elementAtPoint.id == 'content'
 337     {gBrowser} = element.ownerGlobal.top
 338     tabpanel = gBrowser.getNotificationBox(gBrowser.selectedBrowser)
 339     return tabpanel.contains(element)
 340   else
 341     # Note that `a.contains(a)` is supposed to be true, but strangely aren’t for
 342     # `<menulist>`s in the Add-ons Manager, so do a direct comparison as well.
 343     return container == elementAtPoint or container.contains(elementAtPoint)
 344
 345 module.exports = {
 346   find
 347 }