Skip to content
Permalink
Browse files

refactor: Split 'Event' docs/types into more specific Event types (#1…

…7038)

* Event = Base event type (with preventDefault)
* IpcMainEvent = Event that ipcMain emits (with sender, reply, etc.)
* IpcRendererEvent = Event that ipcRenderer emits (with sender,
senderId, etc.)
* KeyboardEvent = Event that we emit with keyboard flags (ctrlKey,
altKey, etc.)

This will dramatically improve peoples TS experience with IPC events
  • Loading branch information...
MarshallOfSound authored and codebytere committed Feb 19, 2019
1 parent ef2e7d9 commit 3b74837020b15a6c7ef74677f78bcab01a7466a9
@@ -22,6 +22,9 @@ template("typescript_build") {
invoker.tsconfig,
"//electron/tsconfig.json",
"//electron/package-lock.json",
"//electron/typings/internal-ambient.d.ts",
"//electron/typings/internal-electron.d.ts",
"//electron/typings/internal-helpers.d.ts",
]

type_roots = "node_modules/@types,typings"
@@ -58,6 +58,8 @@ The `ipcMain` module has the following method to listen for events:

* `channel` String
* `listener` Function
* `event` IpcMainEvent
* `...args` any[]

Listens to `channel`, when a new message arrives `listener` would be called with
`listener(event, args...)`.
@@ -66,6 +68,8 @@ Listens to `channel`, when a new message arrives `listener` would be called with

* `channel` String
* `listener` Function
* `event` IpcMainEvent
* `...args` any[]

Adds a one time `listener` function for the event. This `listener` is invoked
only the next time a message is sent to `channel`, after which it is removed.
@@ -86,27 +90,5 @@ Removes listeners of the specified `channel`.

## Event object

The `event` object passed to the `callback` has the following methods:

### `event.frameId`

An `Integer` representing the ID of the renderer frame that sent this message.

### `event.returnValue`

Set this to the value to be returned in a synchronous message.

### `event.sender`

Returns the `webContents` that sent the message, you can call
`event.sender.send` to reply to the asynchronous message, see
[webContents.send][web-contents-send] for more information.

[web-contents-send]: web-contents.md#contentssendchannel-arg1-arg2-

### `event.reply`

A function that will send an IPC message to the renderer frane that sent
the original message that you are currently handling. You should use this
method to "reply" to the sent message in order to guaruntee the reply will go
to the correct process and frame.
The documentation for the `event` object passed to the `callback` can be found
in the [`ipc-main-event`](structures/ipc-main-event.md) structure docs.
@@ -20,6 +20,8 @@ The `ipcRenderer` module has the following method to listen for events and send

* `channel` String
* `listener` Function
* `event` IpcRendererEvent
* `...args` any[]

Listens to `channel`, when a new message arrives `listener` would be called with
`listener(event, args...)`.
@@ -28,6 +30,8 @@ Listens to `channel`, when a new message arrives `listener` would be called with

* `channel` String
* `listener` Function
* `event` IpcRendererEvent
* `...args` any[]

Adds a one time `listener` function for the event. This `listener` is invoked
only the next time a message is sent to `channel`, after which it is removed.
@@ -92,14 +96,5 @@ the host page instead of the main process.

## Event object

The `event` object passed to the `callback` has the following methods:

### `event.senderId`

Returns the `webContents.id` that sent the message, you can call
`event.sender.sendTo(event.senderId, ...)` to reply to the message, see
[ipcRenderer.sendTo][ipc-renderer-sendto] for more information.
This only applies to messages sent from a different renderer.
Messages sent directly from the main process set `event.senderId` to `0`.

[ipc-renderer-sendto]: #ipcrenderersendtowindowid-channel--arg1-arg2-
The documentation for the `event` object passed to the `callback` can be found
in the [`ipc-renderer-event`](structures/ipc-renderer-event.md) structure docs.
@@ -13,7 +13,7 @@ See [`Menu`](menu.md) for examples.
`click(menuItem, browserWindow, event)` when the menu item is clicked.
* `menuItem` MenuItem
* `browserWindow` [BrowserWindow](browser-window.md)
* `event` Event
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteandmatchstyle`, `delete`, `selectall`, `reload`, `forcereload`, `toggledevtools`, `resetzoom`, `zoomin`, `zoomout`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideothers`, `unhide`, `quit`, `startspeaking`, `stopspeaking`, `close`, `minimize`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu` or `windowMenu` - Define the action of the menu item, when specified the
`click` property will be ignored. See [roles](#roles).
* `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
@@ -1,9 +1,3 @@
# Event Object extends `GlobalEvent`

* `preventDefault` VoidFunction
* `sender` WebContents
* `returnValue` any
* `ctrlKey` Boolean (optional) - whether the Control key was used in an accelerator to trigger the Event
* `metaKey` Boolean (optional) - whether a meta key was used in an accelerator to trigger the Event
* `shiftKey` Boolean (optional) - whether a Shift key was used in an accelerator to trigger the Event
* `altKey` Boolean (optional) - whether an Alt key was used in an accelerator to trigger the Event
@@ -0,0 +1,8 @@
# IpcMainEvent Object extends `Event`

* `frameId` Integer - The ID of the renderer frame that sent this message
* `returnValue` any - Set this to the value to be returned in a syncronous message
* `sender` WebContents - Returns the `webContents` that sent the message
* `reply` Function - A function that will send an IPC message to the renderer frane that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guaruntee the reply will go to the correct process and frame.
* `...args` any[]
IpcRenderer
@@ -0,0 +1,6 @@
# IpcRendererEvent Object extends `Event`

* `sender` IpcRenderer - The `IpcRenderer` instance that emitted the event originally
* `senderId` Integer - The `webContents.id` that sent the message, you can call `event.sender.sendTo(event.senderId, ...)` to reply to the message, see [ipcRenderer.sendTo][ipc-renderer-sendto] for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set `event.senderId` to `0`.

[ipc-renderer-sendto]: #ipcrenderersendtowindowid-channel--arg1-arg2-
@@ -0,0 +1,6 @@
# KeyboardEvent Object extends `Event`

* `ctrlKey` Boolean (optional) - whether the Control key was used in an accelerator to trigger the Event
* `metaKey` Boolean (optional) - whether a meta key was used in an accelerator to trigger the Event
* `shiftKey` Boolean (optional) - whether a Shift key was used in an accelerator to trigger the Event
* `altKey` Boolean (optional) - whether an Alt key was used in an accelerator to trigger the Event
@@ -70,34 +70,22 @@ The `Tray` module emits the following events:

#### Event: 'click'

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon.
* `position` [Point](structures/point.md) - The position of the event.

Emitted when the tray icon is clicked.

#### Event: 'right-click' _macOS_ _Windows_

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon.

Emitted when the tray icon is right clicked.

#### Event: 'double-click' _macOS_ _Windows_

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon.

Emitted when the tray icon is double clicked.
@@ -147,33 +135,21 @@ Emitted when a drag operation ends on the tray or ends at another location.

#### Event: 'mouse-enter' _macOS_

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `position` [Point](structures/point.md) - The position of the event.

Emitted when the mouse enters the tray icon.

#### Event: 'mouse-leave' _macOS_

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `position` [Point](structures/point.md) - The position of the event.

Emitted when the mouse exits the tray icon.

#### Event: 'mouse-move' _macOS_

* `event` Event
* `altKey` Boolean
* `shiftKey` Boolean
* `ctrlKey` Boolean
* `metaKey` Boolean
* `event` [KeyboardEvent](structures/keyboard-event.md)
* `position` [Point](structures/point.md) - The position of the event.

Emitted when the mouse moves in the tray icon.
@@ -75,8 +75,11 @@ auto_filenames = {
"docs/api/structures/file-filter.md",
"docs/api/structures/gpu-feature-status.md",
"docs/api/structures/io-counters.md",
"docs/api/structures/ipc-main-event.md",
"docs/api/structures/ipc-renderer-event.md",
"docs/api/structures/jump-list-category.md",
"docs/api/structures/jump-list-item.md",
"docs/api/structures/keyboard-event.md",
"docs/api/structures/memory-info.md",
"docs/api/structures/memory-usage-details.md",
"docs/api/structures/mime-typed-buffer.md",
@@ -3,7 +3,7 @@ import * as errorUtils from '@electron/internal/common/error-utils'

type IPCHandler = (...args: any[]) => any

const callHandler = async function (handler: IPCHandler, event: Electron.Event, args: any[], reply: (args: any[]) => void) {
const callHandler = async function (handler: IPCHandler, event: ElectronInternal.IpcMainInternalEvent, args: any[], reply: (args: any[]) => void) {
try {
const result = await handler(event, ...args)
reply([null, result])
@@ -5,4 +5,4 @@ const emitter = new EventEmitter()
// Do not throw exception when channel name is "error".
emitter.on('error', () => {})

export const ipcMainInternal = emitter
export const ipcMainInternal = emitter as ElectronInternal.IpcMainInternal
@@ -84,7 +84,7 @@ const injectContentScript = function (extensionId: string, script: Electron.Cont

// Handle the request of chrome.tabs.executeJavaScript.
ipcRendererInternal.on('CHROME_TABS_EXECUTESCRIPT', function (
event: Electron.Event,
event,
senderWebContentsId: number,
requestId: number,
extensionId: string,
@@ -7,7 +7,7 @@ export function invoke<T> (command: string, ...args: any[]) {
return new Promise<T>((resolve, reject) => {
const requestId = ++nextId
ipcRendererInternal.once(`${command}_RESPONSE_${requestId}`, (
_event: Electron.Event, error: Electron.SerializedError, result: any
_event, error: Electron.SerializedError, result: any
) => {
if (error) {
reject(errorUtils.deserialize(error))
@@ -11,7 +11,7 @@ type WebFrameMethod = {
export const webFrameInit = () => {
// Call webFrame method
ipcRendererInternal.on('ELECTRON_INTERNAL_RENDERER_WEB_FRAME_METHOD', (
_event: Electron.Event, method: keyof WebFrameMethod, args: any[]
_event, method: keyof WebFrameMethod, args: any[]
) => {
// The TypeScript compiler cannot handle the sheer number of
// call signatures here and simply gives up. Incorrect invocations
@@ -20,7 +20,7 @@ export const webFrameInit = () => {
})

ipcRendererInternal.on('ELECTRON_INTERNAL_RENDERER_ASYNC_WEB_FRAME_METHOD', (
event: Electron.Event, requestId: number, method: keyof WebFrameMethod, args: any[]
event, requestId: number, method: keyof WebFrameMethod, args: any[]
) => {
new Promise(resolve =>
// The TypeScript compiler cannot handle the sheer number of
@@ -206,7 +206,7 @@ export const windowSetup = (
}

ipcRendererInternal.on('ELECTRON_GUEST_WINDOW_POSTMESSAGE', function (
_event: Electron.Event, sourceId: number, message: any, sourceOrigin: string
_event, sourceId: number, message: any, sourceOrigin: string
) {
// Manually dispatch event instead of using postMessage because we also need to
// set event.source.
@@ -253,7 +253,7 @@ export const windowSetup = (
let cachedVisibilityState = isHiddenPage ? 'hidden' : 'visible'

// Subscribe to visibilityState changes.
ipcRendererInternal.on('ELECTRON_GUEST_INSTANCE_VISIBILITY_CHANGE', function (_event: Electron.Event, visibilityState: VisibilityState) {
ipcRendererInternal.on('ELECTRON_GUEST_INSTANCE_VISIBILITY_CHANGE', function (_event, visibilityState: VisibilityState) {
if (cachedVisibilityState !== visibilityState) {
cachedVisibilityState = visibilityState
document.dispatchEvent(new Event('visibilitychange'))
Oops, something went wrong.

0 comments on commit 3b74837

Please sign in to comment.
You can’t perform that action at this time.