From 343fe1d01398e37628b90bab2a3f4b17d914dcfa Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Sun, 28 Feb 2016 16:55:23 +0100 Subject: [PATCH] Streamline `vimfx.on` events _Always_ pass an object with event-specific properties, instead of sometimes passing data directly. This is more consistent, and more future-proof since it allows passing additional data without breaking backwards compatibility. --- documentation/api.md | 48 ++++++++++++++++++++++++------------- extension/lib/button.coffee | 2 +- extension/lib/events.coffee | 4 ++-- extension/lib/main.coffee | 8 +++---- extension/lib/vim.coffee | 4 ++-- extension/lib/vimfx.coffee | 2 +- 6 files changed, 42 insertions(+), 26 deletions(-) diff --git a/documentation/api.md b/documentation/api.md index b61c669..08d5655 100644 --- a/documentation/api.md +++ b/documentation/api.md @@ -220,7 +220,8 @@ messages, and `vimfx.listen()` to listen for them.) ### `vimfx.on(eventName, listener)` and `vimfx.off(eventName, listener)` After calling `vimfx.on(eventName, listener)`, `listener(data)` will be called -when `eventName` is fired. +when `eventName` is fired, where `data` is an object. Which properties `data` +has is specific to each event. You may use `vimfx.off(eventName, listener)` if you’d like to remove your added listener for some reason. @@ -232,14 +233,15 @@ something whenever VimFx emits internal events. #### The `locationChange` event Occurs when opening a new tab, navigating to a new URL or refreshing the page, -causing a full page load. The data passed to listeners is an object with the -following properties: +causing a full page load. + +`data`: - vim: The current [vim object]. - location: A [location object]. -This can be used to enter a different mode by default on some pages (which can -be used to replace the blacklist option). +This event can be used to enter a different mode by default on some pages (which +can be used to replace the blacklist option). ```js vimfx.on('locationChange', ({vim, location}) => { @@ -257,7 +259,7 @@ that `message` should be displayed to the user. The `hideNotification` event occurs when the `vim.hideNotification()` is called, and means that the current notification is requested to be hidden. -The data passed to listeners is an object with the following properties: +`data`: - vim: The current [vim object]. - message: The message that should be notified. Only for the `notification` @@ -269,11 +271,14 @@ disabled, allowing you to display notifications in any way you want. #### The `modeChange` event Occurs whenever the current mode in any tab changes. The initial entering of the -default mode in new tabs also counts as a mode change. The data passed to -listeners is the current [vim object]. +default mode in new tabs also counts as a mode change. + +`data`: + +- vim: The current [vim object]. ```js -vimfx.on('modeChange', vim => { +vimfx.on('modeChange', ({vim}) => { let mode = vimfx.modes[vim.mode].name vim.notify(`Entering mode: ${mode}`) }) @@ -282,14 +287,20 @@ vimfx.on('modeChange', vim => { #### The `TabSelect` event Occurs whenever any tab in any window is selected. This is also fired when -Firefox starts for the currently selected tab. The data passed to listeners is -the `event` object passed to the standard Firefox [TabSelect] event. +Firefox starts for the currently selected tab. + +`data`: + +- event: The `event` object passed to the standard Firefox [TabSelect] event. #### The `modeDisplayChange` event This is basically a combination of the `modeChange` and the `TabSelect` events. -The event is useful for knowing when to update UI showing the current mode. The -data passed to listeners is the current [vim object]. +The event is useful for knowing when to update UI showing the current mode. + +`data`: + +- vim: The current [vim object]. (VimFx itself uses this event to update the toolbar [button], by setting `#main-window[vimfx-mode]` to the current mode. You may use this with custom @@ -297,10 +308,13 @@ data passed to listeners is the current [vim object]. #### The `focusTypeChange` event -Occurs when focusing or blurring any element. The data passed to listeners is -the current [vim object]. +Occurs when focusing or blurring any element. + +`data`: -`vim.focusType` has been updated just before this event fires. +- vim: The current [vim object]. + +`data.vim.focusType` has been updated just before this event fires. (VimFx itself uses this event to update the toolbar [button], by setting `#main-window[vimfx-focus-type]` to the current focus type. You may use this @@ -314,6 +328,8 @@ Occurs when: VimFx is updated. - When the config file is reloaded using the `zr` command. +`data`: No data at all is passed. + If you care about that things you do in `config.js` and `frame.js` are undone when any of the above happens, read on. diff --git a/extension/lib/button.coffee b/extension/lib/button.coffee index 828741e..9a7bbd4 100644 --- a/extension/lib/button.coffee +++ b/extension/lib/button.coffee @@ -45,7 +45,7 @@ injectButton = (vimfx) -> }) module.onShutdown(cui.destroyWidget.bind(cui, BUTTON_ID)) - vimfx.on('modeDisplayChange', (vim) -> + vimfx.on('modeDisplayChange', ({vim}) -> {window} = vim # When the browser starts, the button might not be available yet. return unless button = getButton(window) diff --git a/extension/lib/events.coffee b/extension/lib/events.coffee index 9b8e8fc..f6f918e 100644 --- a/extension/lib/events.coffee +++ b/extension/lib/events.coffee @@ -172,7 +172,7 @@ class UIEventManager ) @listen('TabSelect', (event) => - @vimfx.emit('TabSelect', event) + @vimfx.emit('TabSelect', {event}) return unless vim = @vimfx.getCurrentVim(@window) vim.hideNotification() @@ -203,7 +203,7 @@ class UIEventManager # for more details. oldVim._setBrowser(browser) @vimfx.vims.set(browser, oldVim) - @vimfx.emit('modeChange', oldVim) + @vimfx.emit('modeChange', {vim: oldVim}) callback(true) ), {messageManager: @window.messageManager}) diff --git a/extension/lib/main.coffee b/extension/lib/main.coffee index 4b84376..efb3595 100644 --- a/extension/lib/main.coffee +++ b/extension/lib/main.coffee @@ -68,20 +68,20 @@ module.exports = (data, reason) -> setWindowAttribute = (window, name, value) -> window.document.documentElement.setAttribute("vimfx-#{name}", value) - onModeDisplayChange = (vimOrEvent) -> - window = vimOrEvent.window ? vimOrEvent.originalTarget.ownerGlobal + onModeDisplayChange = (data) -> + window = data.vim?.window ? data.event.originalTarget.ownerGlobal # The 'modeChange' event provides the `vim` object that changed mode, but # it might not be the current `vim` anymore so always get the current one. return unless vim = vimfx.getCurrentVim(window) setWindowAttribute(window, 'mode', vim.mode) - vimfx.emit('modeDisplayChange', vim) + vimfx.emit('modeDisplayChange', {vim}) vimfx.on('modeChange', onModeDisplayChange) vimfx.on('TabSelect', onModeDisplayChange) - vimfx.on('focusTypeChange', (vim) -> + vimfx.on('focusTypeChange', ({vim}) -> setWindowAttribute(vim.window, 'focus-type', vim.focusType) ) diff --git a/extension/lib/vim.coffee b/extension/lib/vim.coffee index 5b05124..85c86db 100644 --- a/extension/lib/vim.coffee +++ b/extension/lib/vim.coffee @@ -113,7 +113,7 @@ class Vim @_call('onLeave') if @mode? @mode = mode result = @_call('onEnter', null, args...) - @_parent.emit('modeChange', this) + @_parent.emit('modeChange', {vim: this}) @_send('modeChange', {mode}) return result @@ -180,6 +180,6 @@ class Vim @enterMode('ignore', {type: 'focusType'}) when @mode == 'ignore' and @_storage.ignore.type == 'focusType' @enterMode('normal') - @_parent.emit('focusTypeChange', this) + @_parent.emit('focusTypeChange', {vim: this}) module.exports = Vim diff --git a/extension/lib/vimfx.coffee b/extension/lib/vimfx.coffee index f98c0d2..3ff0e20 100644 --- a/extension/lib/vimfx.coffee +++ b/extension/lib/vimfx.coffee @@ -38,7 +38,7 @@ class VimFx extends utils.EventEmitter @skipCreateKeyTrees = false @createKeyTrees() @reset() - @on('modeChange', ({mode}) => @reset(mode)) + @on('modeChange', ({vim}) => @reset(vim.mode)) SPECIAL_KEYS: { '': {} -- 2.39.3