From a8c0ed890f61664156886356ecb6ab9f73c69cf1 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Wed, 3 May 2023 03:14:29 +0200 Subject: [PATCH] feat: surface more `webContents` text selection commands (#37978) * feat: surface more text selection commands * refactor: use options argument * docs: correct for review --- docs/api/web-contents.md | 44 +++++++++++++++++++ docs/api/webview-tag.md | 23 ++++++++++ lib/common/web-view-methods.ts | 4 ++ .../browser/api/electron_api_web_contents.cc | 33 ++++++++++++++ shell/browser/api/electron_api_web_contents.h | 4 ++ 5 files changed, 108 insertions(+) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 0ee39da9a594..2206c8d19977 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1389,6 +1389,10 @@ Executes the editing command `cut` in web page. Executes the editing command `copy` in web page. +#### `contents.centerSelection()` + +Centers the current text selection in web page. + #### `contents.copyImageAt(x, y)` * `x` Integer @@ -1416,6 +1420,46 @@ Executes the editing command `selectAll` in web page. Executes the editing command `unselect` in web page. +#### `contents.scrollToTop()` + +Scrolls to the top of the current `webContents`. + +#### `contents.scrollToBottom()` + +Scrolls to the bottom of the current `webContents`. + +#### `contents.adjustSelection(options)` + +* `options` Object + * `start` Number (optional) - Amount to shift the start index of the current selection. + * `end` Number (optional) - Amount to shift the end index of the current selection. + +Adjusts the current text selection starting and ending points in the focused frame by the given amounts. A negative amount moves the selection towards the beginning of the document, and a positive amount moves the selection towards the end of the document. + +Example: + +```js +const win = new BrowserWindow() + +// Adjusts the beginning of the selection 1 letter forward, +// and the end of the selection 5 letters forward. +win.webContents.adjustSelection({ start: 1, end: 5 }) + +// Adjusts the beginning of the selection 2 letters forward, +// and the end of the selection 3 letters backward. +win.webContents.adjustSelection({ start: 2, end: -3 }) +``` + +For a call of `win.webContents.adjustSelection({ start: 1, end: 5 })` + +Before: + +Image Before Text Selection Adjustment + +After: + +Image After Text Selection Adjustment + #### `contents.replace(text)` * `text` string diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md index 85db4084f7e2..63229a0b8583 100644 --- a/docs/api/webview-tag.md +++ b/docs/api/webview-tag.md @@ -463,6 +463,10 @@ Executes editing command `cut` in page. Executes editing command `copy` in page. +#### `.centerSelection()` + +Centers the current text selection in page. + ### `.paste()` Executes editing command `paste` in page. @@ -483,6 +487,25 @@ Executes editing command `selectAll` in page. Executes editing command `unselect` in page. +#### `.scrollToTop()` + +Scrolls to the top of the current ``. + +#### `.scrollToBottom()` + +Scrolls to the bottom of the current ``. + +#### `.adjustSelection(options)` + +* `options` Object + * `start` Number (optional) - Amount to shift the start index of the current selection. + * `end` Number (optional) - Amount to shift the end index of the current selection. + +Adjusts the current text selection starting and ending points in the focused frame by the given amounts. A negative amount moves the selection towards the beginning of the document, and a positive amount moves the selection towards the end of the document. + +See [`webContents.adjustSelection`](web-contents.md#contentsadjustselectionoptions) for +examples. + ### `.replace(text)` * `text` string diff --git a/lib/common/web-view-methods.ts b/lib/common/web-view-methods.ts index baae378ddc02..81fc88f1f8e8 100644 --- a/lib/common/web-view-methods.ts +++ b/lib/common/web-view-methods.ts @@ -31,11 +31,15 @@ export const syncMethods = new Set([ 'redo', 'cut', 'copy', + 'centerSelection', 'paste', 'pasteAndMatchStyle', 'delete', 'selectAll', 'unselect', + 'scrollToTop', + 'scrollToBottom', + 'adjustSelection', 'replace', 'replaceMisspelling', 'findInPage', diff --git a/shell/browser/api/electron_api_web_contents.cc b/shell/browser/api/electron_api_web_contents.cc index be0ddd6b232f..9fe4cc882c72 100644 --- a/shell/browser/api/electron_api_web_contents.cc +++ b/shell/browser/api/electron_api_web_contents.cc @@ -3095,6 +3095,10 @@ void WebContents::Copy() { web_contents()->Copy(); } +void WebContents::CenterSelection() { + web_contents()->CenterSelection(); +} + void WebContents::Paste() { web_contents()->Paste(); } @@ -3115,6 +3119,30 @@ void WebContents::Unselect() { web_contents()->CollapseSelection(); } +void WebContents::ScrollToTopOfDocument() { + web_contents()->ScrollToTopOfDocument(); +} + +void WebContents::ScrollToBottomOfDocument() { + web_contents()->ScrollToBottomOfDocument(); +} + +void WebContents::AdjustSelectionByCharacterOffset(gin::Arguments* args) { + int start_adjust = 0; + int end_adjust = 0; + + gin_helper::Dictionary dict; + if (args->GetNext(&dict)) { + dict.Get("start", &start_adjust); + dict.Get("matchCase", &end_adjust); + } + + // The selection menu is a Chrome-specific piece of UI. + // TODO(codebytere): maybe surface as an event in the future? + web_contents()->AdjustSelectionByCharacterOffset( + start_adjust, end_adjust, false /* show_selection_menu */); +} + void WebContents::Replace(const std::u16string& word) { web_contents()->Replace(word); } @@ -4148,11 +4176,16 @@ void WebContents::FillObjectTemplate(v8::Isolate* isolate, .SetMethod("redo", &WebContents::Redo) .SetMethod("cut", &WebContents::Cut) .SetMethod("copy", &WebContents::Copy) + .SetMethod("centerSelection", &WebContents::CenterSelection) .SetMethod("paste", &WebContents::Paste) .SetMethod("pasteAndMatchStyle", &WebContents::PasteAndMatchStyle) .SetMethod("delete", &WebContents::Delete) .SetMethod("selectAll", &WebContents::SelectAll) .SetMethod("unselect", &WebContents::Unselect) + .SetMethod("scrollToTop", &WebContents::ScrollToTopOfDocument) + .SetMethod("scrollToBottom", &WebContents::ScrollToBottomOfDocument) + .SetMethod("adjustSelection", + &WebContents::AdjustSelectionByCharacterOffset) .SetMethod("replace", &WebContents::Replace) .SetMethod("replaceMisspelling", &WebContents::ReplaceMisspelling) .SetMethod("findInPage", &WebContents::FindInPage) diff --git a/shell/browser/api/electron_api_web_contents.h b/shell/browser/api/electron_api_web_contents.h index a1006d1386e8..bcd01b9c3f51 100644 --- a/shell/browser/api/electron_api_web_contents.h +++ b/shell/browser/api/electron_api_web_contents.h @@ -241,11 +241,15 @@ class WebContents : public ExclusiveAccessContext, void Redo(); void Cut(); void Copy(); + void CenterSelection(); void Paste(); void PasteAndMatchStyle(); void Delete(); void SelectAll(); void Unselect(); + void ScrollToTopOfDocument(); + void ScrollToBottomOfDocument(); + void AdjustSelectionByCharacterOffset(gin::Arguments* args); void Replace(const std::u16string& word); void ReplaceMisspelling(const std::u16string& word); uint32_t FindInPage(gin::Arguments* args);