extension/lib/scrollable-elements.coffee

   1 ###
   2 # Copyright Simon Lydell 2015.
   3 #
   4 # This file is part of VimFx.
   5 #
   6 # VimFx is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # VimFx is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with VimFx.  If not, see <http://www.gnu.org/licenses/>.
  18 ###
  19
  20 # This file contains an abstraction for keeping track of scrollable elements,
  21 # automatically keeping the largest scrollable element up-to-date. It stops
  22 # tracking elements that are removed from the DOM.
  23
  24 utils = require('./utils')
  25
  26 class ScrollableElements
  27   constructor: (@window, @MINIMUM_SCROLL) ->
  28     @elements = new Set()
  29     @largest  = null
  30
  31   # In quirks mode (when the page lacks a doctype), such as on Hackernews,
  32   # `<body>` is considered the root element rather than `<html>`. The 'overflow'
  33   # event is triggered for `<html>` though (_not_ `<body>`!). This method takes
  34   # care of returning the appropriate element, so we don’t need to think about
  35   # it anywhere else.
  36   quirks: (element) ->
  37     document = element.ownerDocument
  38     if element == document.documentElement and
  39        document.compatMode == 'BackCompat' and document.body?
  40       return document.body
  41     else
  42       return element
  43
  44   has: (element) -> @elements.has(@quirks(element))
  45
  46   add: (element) ->
  47     element = @quirks(element)
  48     @elements.add(element)
  49     utils.onRemoved(@window, element, @delete.bind(this, element))
  50     @largest = element if @isLargest(element)
  51
  52   delete: (element) =>
  53     element = @quirks(element)
  54     @elements.delete(element)
  55     @updateLargest() if @largest == element
  56
  57   reject: (fn) ->
  58     @elements.forEach((element) => @elements.delete(element) if fn(element))
  59     @updateLargest()
  60
  61   isScrollable: (element) ->
  62     element = @quirks(element)
  63     return element.scrollTopMax  >= @MINIMUM_SCROLL or
  64            element.scrollLeftMax >= @MINIMUM_SCROLL
  65
  66   # It makes the most sense to consider the uppermost scrollable element the
  67   # largest. In other words, if a scrollable element contains another scrollable
  68   # element (or a frame containing one), the parent should be considered largest
  69   # even if the child has greater area.
  70   isLargest: (element) ->
  71     return true  unless @largest
  72     return true  if utils.containsDeep(element, @largest)
  73     return false if utils.containsDeep(@largest, element)
  74     return utils.area(element) > utils.area(@largest)
  75
  76   updateLargest: ->
  77     # Reset `@largest` and find a new largest scrollable element (if there are
  78     # any left).
  79     @largest = null
  80     @elements.forEach((element) => @largest = element if @isLargest(element))
  81
  82   # In theory, this method could return `@largest`. In reality, it is not that
  83   # simple. Elements may overflow when zooming in or out, but the
  84   # `.scrollHeight` of the element is not correctly updated when the 'overflow'
  85   # event occurs, making it possible for unscrollable elements to slip in. So
  86   # this method has to check whether the largest element really is scrollable,
  87   # and update it if needed. In the case where there is no largest element
  88   # (left), it _should_ mean that the page hasn’t got any scrollable elements,
  89   # and the whole page itself isn’t scrollable. However, we cannot be 100% sure
  90   # that nothing is scrollable (for example, if VimFx is updated in the middle
  91   # of a session). So in that case, instead of simply returning `null`, return
  92   # the entire page (the best bet). Not being able to scroll is very annoying.
  93   filterSuitableDefault: ->
  94     if @largest and @isScrollable(@largest)
  95       return @largest
  96     else
  97       @reject((element) => not @isScrollable(element))
  98       return @largest ? @quirks(@window.document.documentElement)
  99
 100 module.exports = ScrollableElements