From 12bbbef688626a6d66b4da28168b7b4aed50d241 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Fri, 26 Jul 2019 16:11:50 -0700 Subject: [PATCH] docs: fix type information for contents.sendInputEvent (#19479) The `event` type and keyword is reserved by the typescript generator, in the future we should throw an error from the generator if someone uses a reserved interface like that. This also splits and documents the InputEvent type way better so that TS users get strong type safety. Fixes electron/typescript-definitions#36 --- docs/api/structures/input-event.md | 6 ++++ docs/api/structures/keyboard-input-event.md | 6 ++++ docs/api/structures/mouse-input-event.md | 12 +++++++ .../api/structures/mouse-wheel-input-event.md | 11 +++++++ docs/api/web-contents.md | 32 ++----------------- docs/api/webview-tag.md | 2 +- filenames.auto.gni | 4 +++ 7 files changed, 42 insertions(+), 31 deletions(-) create mode 100644 docs/api/structures/input-event.md create mode 100644 docs/api/structures/keyboard-input-event.md create mode 100644 docs/api/structures/mouse-input-event.md create mode 100644 docs/api/structures/mouse-wheel-input-event.md diff --git a/docs/api/structures/input-event.md b/docs/api/structures/input-event.md new file mode 100644 index 000000000000..c24cb528a79d --- /dev/null +++ b/docs/api/structures/input-event.md @@ -0,0 +1,6 @@ +# InputEvent Object + +* `modifiers` String[] - An array of modifiers of the event, can + be `shift`, `control`, `alt`, `meta`, `isKeypad`, `isAutoRepeat`, + `leftButtonDown`, `middleButtonDown`, `rightButtonDown`, `capsLock`, + `numLock`, `left`, `right`. diff --git a/docs/api/structures/keyboard-input-event.md b/docs/api/structures/keyboard-input-event.md new file mode 100644 index 000000000000..96ce3bf77f45 --- /dev/null +++ b/docs/api/structures/keyboard-input-event.md @@ -0,0 +1,6 @@ +# KeyboardInputEvent Object extends `InputEvent` + +* `type` String - The type of the event, can be `keyDown`, `keyUp` or `char`. +* `keyCode` String - The character that will be sent + as the keyboard event. Should only use the valid key codes in + [Accelerator](../accelerator.md). diff --git a/docs/api/structures/mouse-input-event.md b/docs/api/structures/mouse-input-event.md new file mode 100644 index 000000000000..879f669cf2ca --- /dev/null +++ b/docs/api/structures/mouse-input-event.md @@ -0,0 +1,12 @@ +# MouseInputEvent Object extends `InputEvent` + +* `type` String - The type of the event, can be `mouseDown`, + `mouseUp`, `mouseEnter`, `mouseLeave`, `contextMenu`, `mouseWheel` or `mouseMove`. +* `x` Integer +* `y` Integer +* `button` String (optional) - The button pressed, can be `left`, `middle`, `right`. +* `globalX` Integer (optional) +* `globalY` Integer (optional) +* `movementX` Integer (optional) +* `movementY` Integer (optional) +* `clickCount` Integer (optional) diff --git a/docs/api/structures/mouse-wheel-input-event.md b/docs/api/structures/mouse-wheel-input-event.md new file mode 100644 index 000000000000..50540e7cd878 --- /dev/null +++ b/docs/api/structures/mouse-wheel-input-event.md @@ -0,0 +1,11 @@ +# MouseWheelInputEvent Object extends `MouseInputEvent` + +* `type` String - The type of the event, can be `mouseWheel`. +* `deltaX` Integer (optional) +* `deltaY` Integer (optional) +* `wheelTicksX` Integer (optional) +* `wheelTicksY` Integer (optional) +* `accelerationRatioX` Integer (optional) +* `accelerationRatioY` Integer (optional) +* `hasPreciseScrollingDeltas` Boolean (optional) +* `canScroll` Boolean (optional) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 0dc56ae34524..ab337525cc38 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1560,9 +1560,9 @@ Enable device emulation with the given parameters. Disable device emulation enabled by `webContents.enableDeviceEmulation`. -#### `contents.sendInputEvent(event)` +#### `contents.sendInputEvent(inputEvent)` -* `event` Object +* `inputEvent` [MouseInputEvent](structures/mouse-input-event.md) | [MouseWheelInputEvent](structures/mouse-wheel-input-event.md) | [KeyboardInputEvent](structures/keyboard-input-event.md) * `type` String (**required**) - The type of the event, can be `mouseDown`, `mouseUp`, `mouseEnter`, `mouseLeave`, `contextMenu`, `mouseWheel`, `mouseMove`, `keyDown`, `keyUp` or `char`. @@ -1575,34 +1575,6 @@ Sends an input `event` to the page. **Note:** The [`BrowserWindow`](browser-window.md) containing the contents needs to be focused for `sendInputEvent()` to work. -For keyboard events, the `event` object also have following properties: - -* `keyCode` String (**required**) - The character that will be sent - as the keyboard event. Should only use the valid key codes in - [Accelerator](accelerator.md). - -For mouse events, the `event` object also have following properties: - -* `x` Integer (**required**) -* `y` Integer (**required**) -* `button` String - The button pressed, can be `left`, `middle`, `right`. -* `globalX` Integer -* `globalY` Integer -* `movementX` Integer -* `movementY` Integer -* `clickCount` Integer - -For the `mouseWheel` event, the `event` object also have following properties: - -* `deltaX` Integer -* `deltaY` Integer -* `wheelTicksX` Integer -* `wheelTicksY` Integer -* `accelerationRatioX` Integer -* `accelerationRatioY` Integer -* `hasPreciseScrollingDeltas` Boolean -* `canScroll` Boolean - #### `contents.beginFrameSubscription([onlyDirty ,]callback)` * `onlyDirty` Boolean (optional) - Defaults to `false`. diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md index 4c6a77c2d366..39d5472e8ad4 100644 --- a/docs/api/webview-tag.md +++ b/docs/api/webview-tag.md @@ -599,7 +599,7 @@ Returns `Promise` Sends an input `event` to the page. -See [webContents.sendInputEvent](web-contents.md#contentssendinputeventevent) +See [webContents.sendInputEvent](web-contents.md#contentssendinputeventinputevent) for detailed description of `event` object. ### `.setZoomFactor(factor)` diff --git a/filenames.auto.gni b/filenames.auto.gni index 88c1ea5b4f5f..375c5e7a9df0 100644 --- a/filenames.auto.gni +++ b/filenames.auto.gni @@ -79,6 +79,7 @@ auto_filenames = { "docs/api/structures/file-filter.md", "docs/api/structures/file-path-with-headers.md", "docs/api/structures/gpu-feature-status.md", + "docs/api/structures/input-event.md", "docs/api/structures/io-counters.md", "docs/api/structures/ipc-main-event.md", "docs/api/structures/ipc-main-invoke-event.md", @@ -86,9 +87,12 @@ auto_filenames = { "docs/api/structures/jump-list-category.md", "docs/api/structures/jump-list-item.md", "docs/api/structures/keyboard-event.md", + "docs/api/structures/keyboard-input-event.md", "docs/api/structures/memory-info.md", "docs/api/structures/memory-usage-details.md", "docs/api/structures/mime-typed-buffer.md", + "docs/api/structures/mouse-input-event.md", + "docs/api/structures/mouse-wheel-input-event.md", "docs/api/structures/notification-action.md", "docs/api/structures/point.md", "docs/api/structures/printer-info.md",