extension/lib/utils.coffee

   1 ###
   2 # Copyright Anton Khodakivskiy 2012, 2013, 2014.
   3 # Copyright Simon Lydell 2013, 2014, 2015, 2016.
   4 # Copyright Wang Zhuochun 2013.
   5 #
   6 # This file is part of VimFx.
   7 #
   8 # VimFx is free software: you can redistribute it and/or modify
   9 # it under the terms of the GNU General Public License as published by
  10 # the Free Software Foundation, either version 3 of the License, or
  11 # (at your option) any later version.
  12 #
  13 # VimFx is distributed in the hope that it will be useful,
  14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 # GNU General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with VimFx.  If not, see <http://www.gnu.org/licenses/>.
  20 ###
  21
  22 # This file contains lots of different helper functions.
  23
  24 nsIClipboardHelper = Cc['@mozilla.org/widget/clipboardhelper;1']
  25   .getService(Ci.nsIClipboardHelper)
  26 nsIDomUtils = Cc['@mozilla.org/inspector/dom-utils;1']
  27   .getService(Ci.inIDOMUtils)
  28 nsIEventListenerService = Cc['@mozilla.org/eventlistenerservice;1']
  29   .getService(Ci.nsIEventListenerService)
  30 nsIFocusManager = Cc['@mozilla.org/focus-manager;1']
  31   .getService(Ci.nsIFocusManager)
  32 nsIStyleSheetService = Cc['@mozilla.org/content/style-sheet-service;1']
  33   .getService(Ci.nsIStyleSheetService)
  34 nsIWindowMediator = Cc['@mozilla.org/appshell/window-mediator;1']
  35   .getService(Ci.nsIWindowMediator)
  36
  37 HTMLAnchorElement = Ci.nsIDOMHTMLAnchorElement
  38 HTMLButtonElement = Ci.nsIDOMHTMLButtonElement
  39 HTMLInputElement = Ci.nsIDOMHTMLInputElement
  40 HTMLTextAreaElement = Ci.nsIDOMHTMLTextAreaElement
  41 HTMLSelectElement = Ci.nsIDOMHTMLSelectElement
  42 HTMLBodyElement = Ci.nsIDOMHTMLBodyElement
  43 XULDocument = Ci.nsIDOMXULDocument
  44 XULButtonElement = Ci.nsIDOMXULButtonElement
  45 XULControlElement = Ci.nsIDOMXULControlElement
  46 XULMenuListElement = Ci.nsIDOMXULMenuListElement
  47 XULTextBoxElement = Ci.nsIDOMXULTextBoxElement
  48
  49 # Full chains of events for different mouse actions. ('command' is for XUL
  50 # elements.)
  51 EVENTS_CLICK       = ['mousedown', 'mouseup', 'click', 'command']
  52 EVENTS_HOVER_START = ['mouseover', 'mouseenter', 'mousemove']
  53 EVENTS_HOVER_END   = ['mouseout',  'mouseleave']
  54
  55
  56
  57 # Element classification helpers
  58
  59 isActivatable = (element) ->
  60   return element instanceof HTMLAnchorElement or
  61          element instanceof HTMLButtonElement or
  62          (element instanceof HTMLInputElement and element.type in [
  63            'button', 'submit', 'reset', 'image'
  64          ]) or
  65          element instanceof XULButtonElement
  66
  67 isAdjustable = (element) ->
  68   return element instanceof HTMLInputElement and element.type in [
  69            'checkbox', 'radio', 'file', 'color'
  70            'date', 'time', 'datetime', 'datetime-local', 'month', 'week'
  71          ] or
  72          element instanceof XULControlElement or
  73          # Youtube special case.
  74          element.classList?.contains('html5-video-player') or
  75          element.classList?.contains('ytp-button')
  76
  77 isContentEditable = (element) ->
  78   return element.isContentEditable or
  79          isIframeEditor(element) or
  80          # Google.
  81          element.getAttribute?('g_editable') == 'true' or
  82          element.ownerDocument?.body?.getAttribute('g_editable') == 'true' or
  83          # Codeacademy terminals.
  84          element.classList?.contains('real-terminal')
  85
  86 isIframeEditor = (element) ->
  87   return false unless element instanceof HTMLBodyElement
  88   return \
  89          # Etherpad.
  90          element.id == 'innerdocbody' or
  91          # XpressEditor.
  92          (element.classList.contains('xe_content') and
  93           element.classList.contains('editable')) or
  94          # vBulletin.
  95          element.classList.contains('wysiwyg')
  96
  97 isProperLink = (element) ->
  98   # `.getAttribute` is used below instead of `.hasAttribute` to exclude `<a
  99   # href="">`s used as buttons on some sites.
 100   return element.getAttribute('href') and
 101          (element instanceof HTMLAnchorElement or
 102           element.ownerDocument instanceof XULDocument) and
 103          not element.href.endsWith('#') and
 104          not element.href.endsWith('#?') and
 105          not element.href.startsWith('javascript:')
 106
 107 isTextInputElement = (element) ->
 108   return (element instanceof HTMLInputElement and element.type in [
 109            'text', 'search', 'tel', 'url', 'email', 'password', 'number'
 110          ]) or
 111          element instanceof HTMLTextAreaElement or
 112          element instanceof XULTextBoxElement or
 113          isContentEditable(element)
 114
 115 isTypingElement = (element) ->
 116   return isTextInputElement(element) or
 117          # `<select>` elements can also receive text input: You may type the
 118          # text of an item to select it.
 119          element instanceof HTMLSelectElement or
 120          element instanceof XULMenuListElement
 121
 122
 123
 124 # Active/focused element helpers
 125
 126 # NOTE: In frame scripts, `document.activeElement` may be `null` when the page
 127 # is loading. Therefore always check if anything was returned, such as:
 128 #
 129 #     return unless activeElement = utils.getActiveElement(window)
 130 getActiveElement = (window) ->
 131   {activeElement} = window.document
 132   return null unless activeElement
 133   # If the active element is a frame, recurse into it. The easiest way to detect
 134   # a frame that works both in browser UI and in web page content is to check
 135   # for the presence of `.contentWindow`. However, in non-multi-process
 136   # `<browser>` (sometimes `<xul:browser>`) elements have a `.contentWindow`
 137   # pointing to the web page content `window`, which we don’t want to recurse
 138   # into. `.localName` is `.nodeName` without `xul:` (if it exists). This seems
 139   # to be the only way to detect such elements.
 140   if activeElement.localName != 'browser' and activeElement.contentWindow
 141     return getActiveElement(activeElement.contentWindow)
 142   else
 143     return activeElement
 144
 145 blurActiveElement = (window) ->
 146   # Blurring a frame element also blurs any active elements inside it. Recursing
 147   # into the frames and blurring the “real” active element directly would give
 148   # focus to the `<body>` of its containing frame, while blurring the top-most
 149   # frame gives focus to the top-most `<body>`. This allows to blur fancy text
 150   # editors which use an `<iframe>` as their text area.
 151   window.document.activeElement?.blur()
 152
 153 blurActiveBrowserElement = (vim) ->
 154   # - Blurring in the next tick allows to pass `<escape>` to the location bar to
 155   #   reset it, for example.
 156   # - Focusing the current browser afterwards allows to pass `<escape>` as well
 157   #   as unbound keys to the page. However, focusing the browser also triggers
 158   #   focus events on `document` and `window` in the current page. Many pages
 159   #   re-focus some text input on those events, making it impossible to blur
 160   #   those! Therefore we tell the frame script to suppress those events.
 161   {window} = vim
 162   activeElement = getActiveElement(window)
 163   vim._send('browserRefocus')
 164   nextTick(window, ->
 165     activeElement.blur()
 166     window.gBrowser.selectedBrowser.focus()
 167   )
 168
 169 # Focus an element and tell Firefox that the focus happened because of a user
 170 # action (not just because some random programmatic focus). `.FLAG_BYKEY` might
 171 # look more appropriate, but it unconditionally selects all text, which
 172 # `.FLAG_BYMOUSE` does not.
 173 focusElement = (element, options = {}) ->
 174   nsIFocusManager.setFocus(element, options.flag ? 'FLAG_BYMOUSE')
 175   element.select?() if options.select
 176
 177 getFocusType = (element) -> switch
 178   when isTypingElement(element)
 179     'editable'
 180   when isActivatable(element)
 181     'activatable'
 182   when isAdjustable(element)
 183     'adjustable'
 184   else
 185     null
 186
 187
 188
 189 # Event helpers
 190
 191 listen = (element, eventName, listener, useCapture = true) ->
 192   element.addEventListener(eventName, listener, useCapture)
 193   module.onShutdown(->
 194     element.removeEventListener(eventName, listener, useCapture)
 195   )
 196
 197 listenOnce = (element, eventName, listener, useCapture = true) ->
 198   fn = (event) ->
 199     listener(event)
 200     element.removeEventListener(eventName, fn, useCapture)
 201   listen(element, eventName, fn, useCapture)
 202
 203 onRemoved = (window, element, fn) ->
 204   mutationObserver = new window.MutationObserver((changes) ->
 205     for change in changes then for removedElement in change.removedNodes
 206       if removedElement == element
 207         mutationObserver.disconnect()
 208         fn()
 209         return
 210   )
 211   mutationObserver.observe(element.parentNode, {childList: true})
 212   module.onShutdown(mutationObserver.disconnect.bind(mutationObserver))
 213
 214 suppressEvent = (event) ->
 215   event.preventDefault()
 216   event.stopPropagation()
 217
 218 simulateMouseEvents = (element, sequenceType) ->
 219   window = element.ownerGlobal
 220   rect = element.getBoundingClientRect()
 221
 222   eventSequence = switch sequenceType
 223     when 'click'
 224       EVENTS_CLICK
 225     when 'hover-start'
 226       EVENTS_HOVER_START
 227     when 'hover-end'
 228       EVENTS_HOVER_END
 229
 230   for type in eventSequence
 231     buttonNum = if type in EVENTS_CLICK then 1 else 0
 232     mouseEvent = new window.MouseEvent(type, {
 233       # Let the event bubble in order to trigger delegated event listeners.
 234       bubbles: type not in ['mouseenter', 'mouseleave']
 235       # Make the event cancelable so that `<a href="#">` can be used as a
 236       # JavaScript-powered button without scrolling to the top of the page.
 237       cancelable: type not in ['mouseenter', 'mouseleave']
 238       # These properties are just here for mimicing a real click as much as
 239       # possible.
 240       buttons: buttonNum
 241       detail: buttonNum
 242       view: window
 243       # `page{X,Y}` are set automatically to the correct values when setting
 244       # `client{X,Y}`. `{offset,layer,movement}{X,Y}` are not worth the trouble
 245       # to set.
 246       clientX: rect.left
 247       clientY: rect.top
 248       # To exactly calculate `screen{X,Y}` one has to to check where the web
 249       # page content area is inside the browser chrome and go through all parent
 250       # frames as well. This is good enough. YAGNI for now.
 251       screenX: window.screenX + rect.left
 252       screenY: window.screenY + rect.top
 253     })
 254     element.dispatchEvent(mouseEvent)
 255
 256   return
 257
 258
 259
 260 # DOM helpers
 261
 262 area = (element) ->
 263   return element.clientWidth * element.clientHeight
 264
 265 containsDeep = (parent, element) ->
 266   parentWindow = parent.ownerGlobal
 267   elementWindow = element.ownerGlobal
 268
 269   # Owner windows might be missing when opening the devtools.
 270   while elementWindow and parentWindow and
 271         elementWindow != parentWindow and elementWindow.top != elementWindow
 272     element = elementWindow.frameElement
 273     elementWindow = element.ownerGlobal
 274
 275   return parent.contains(element)
 276
 277 createBox = (document, className = '', parent = null, text = null) ->
 278   box = document.createElement('box')
 279   box.className = "#{className} vimfx-box"
 280   box.textContent = text if text?
 281   parent.appendChild(box) if parent?
 282   return box
 283
 284 injectTemporaryPopup = (document, contents) ->
 285   popup = document.createElement('menupopup')
 286   popup.appendChild(contents)
 287   document.getElementById('mainPopupSet').appendChild(popup)
 288   listenOnce(popup, 'popuphidden', popup.remove.bind(popup))
 289   return popup
 290
 291 insertText = (input, value) ->
 292   {selectionStart, selectionEnd} = input
 293   input.value =
 294     input.value[0...selectionStart] + value + input.value[selectionEnd..]
 295   input.selectionStart = input.selectionEnd = selectionStart + value.length
 296
 297 querySelectorAllDeep = (window, selector) ->
 298   elements = Array.from(window.document.querySelectorAll(selector))
 299   for frame in window.frames
 300     elements.push(querySelectorAllDeep(frame, selector)...)
 301   return elements
 302
 303 scroll = (element, args) ->
 304   {method, type, directions, amounts, properties, adjustment, smooth} = args
 305   options = {}
 306   for direction, index in directions
 307     amount = amounts[index]
 308     options[direction] = -Math.sign(amount) * adjustment + switch type
 309       when 'lines'
 310         amount
 311       when 'pages'
 312         amount * element[properties[index]]
 313       when 'other'
 314         Math.min(amount, element[properties[index]])
 315   options.behavior = 'smooth' if smooth
 316   element[method](options)
 317
 318 setAttributes = (element, attributes) ->
 319   for attribute, value of attributes
 320     element.setAttribute(attribute, value)
 321   return
 322
 323 setHover = (element, hover) ->
 324   method = if hover then 'addPseudoClassLock' else 'removePseudoClassLock'
 325   while element.parentElement
 326     nsIDomUtils[method](element, ':hover')
 327     element = element.parentElement
 328   return
 329
 330
 331
 332 # Language helpers
 333
 334 class Counter
 335   constructor: ({start: @value = 0, @step = 1}) ->
 336   tick: -> @value += @step
 337
 338 class EventEmitter
 339   constructor: ->
 340     @listeners = {}
 341
 342   on: (event, listener) ->
 343     (@listeners[event] ?= []).push(listener)
 344
 345   emit: (event, data) ->
 346     for listener in @listeners[event] ? []
 347       listener(data)
 348     return
 349
 350 has = (obj, prop) -> Object::hasOwnProperty.call(obj, prop)
 351
 352 # Check if `search` exists in `string` (case insensitively). Returns `false` if
 353 # `string` doesn’t exist or isn’t a string, such as `<SVG element>.className`.
 354 includes = (string, search) ->
 355   return false unless typeof string == 'string'
 356   return string.toLowerCase().includes(search)
 357
 358
 359 nextTick = (window, fn) -> window.setTimeout((-> fn()) , 0)
 360
 361 regexEscape = (s) -> s.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
 362
 363 removeDuplicates = (array) -> Array.from(new Set(array))
 364
 365 # Remove duplicate characters from string (case insensitive).
 366 removeDuplicateCharacters = (str) ->
 367   return removeDuplicates( str.toLowerCase().split('') ).join('')
 368
 369 # Calls `fn` repeatedly, with at least `interval` ms between each call.
 370 interval = (window, interval, fn) ->
 371   stopped = false
 372   currentIntervalId = null
 373   next = ->
 374     return if stopped
 375     currentIntervalId = window.setTimeout((-> fn(next)), interval)
 376   clearInterval = ->
 377     stopped = true
 378     window.clearTimeout(currentIntervalId)
 379   next()
 380   return clearInterval
 381
 382
 383
 384 # Misc helpers
 385
 386 formatError = (error) ->
 387   stack = String(error.stack?.formattedStack ? error.stack ? '')
 388     .split('\n')
 389     .filter((line) -> line.includes('.xpi!'))
 390     .map((line) -> '  ' + line.replace(/(?:\/<)*@.+\.xpi!/g, '@'))
 391     .join('\n')
 392   return "#{error}\n#{stack}"
 393
 394 getCurrentLocation = ->
 395   window = getCurrentWindow()
 396   return new window.URL(window.gBrowser.selectedBrowser.currentURI.spec)
 397
 398 getCurrentWindow = -> nsIWindowMediator.getMostRecentWindow('navigator:browser')
 399
 400 hasEventListeners = (element, type) ->
 401   for listener in nsIEventListenerService.getListenerInfoFor(element)
 402     if listener.listenerObject and listener.type == type
 403       return true
 404   return false
 405
 406 loadCss = (name) ->
 407   uri = Services.io.newURI("#{ADDON_PATH}/skin/#{name}.css", null, null)
 408   method = nsIStyleSheetService.AUTHOR_SHEET
 409   unless nsIStyleSheetService.sheetRegistered(uri, method)
 410     nsIStyleSheetService.loadAndRegisterSheet(uri, method)
 411   module.onShutdown(->
 412     nsIStyleSheetService.unregisterSheet(uri, method)
 413   )
 414
 415 observe = (topic, observer) ->
 416   observer = {observe: observer} if typeof observer == 'function'
 417   Services.obs.addObserver(observer, topic, false)
 418   module.onShutdown(->
 419     Services.obs.removeObserver(observer, topic, false)
 420   )
 421
 422 openPopup = (popup) ->
 423   window = popup.ownerGlobal
 424   # Show the popup so it gets a height and width.
 425   popup.openPopupAtScreen(0, 0)
 426   # Center the popup inside the window.
 427   popup.moveTo(
 428     window.screenX + window.outerWidth  / 2 - popup.clientWidth  / 2,
 429     window.screenY + window.outerHeight / 2 - popup.clientHeight / 2
 430   )
 431
 432 openTab = (window, url, options) ->
 433   {gBrowser} = window
 434   window.TreeStyleTabService?.readyToOpenChildTab(gBrowser.selectedTab)
 435   gBrowser.loadOneTab(url, options)
 436
 437 writeToClipboard = (text) -> nsIClipboardHelper.copyString(text)
 438
 439
 440
 441 module.exports = {
 442   isActivatable
 443   isAdjustable
 444   isContentEditable
 445   isProperLink
 446   isTextInputElement
 447   isTypingElement
 448
 449   getActiveElement
 450   blurActiveElement
 451   blurActiveBrowserElement
 452   focusElement
 453   getFocusType
 454
 455   listen
 456   listenOnce
 457   onRemoved
 458   suppressEvent
 459   simulateMouseEvents
 460
 461   area
 462   containsDeep
 463   createBox
 464   injectTemporaryPopup
 465   insertText
 466   querySelectorAllDeep
 467   scroll
 468   setAttributes
 469   setHover
 470
 471   Counter
 472   EventEmitter
 473   has
 474   includes
 475   nextTick
 476   regexEscape
 477   removeDuplicates
 478   removeDuplicateCharacters
 479   interval
 480
 481   formatError
 482   getCurrentLocation
 483   getCurrentWindow
 484   hasEventListeners
 485   loadCss
 486   observe
 487   openPopup
 488   openTab
 489   writeToClipboard
 490 }