From affbf1b3e6b0f21bd190d38d1899a38b3e5500d9 Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Tue, 2 Feb 2021 22:57:33 -0800 Subject: [PATCH] docs: remove v5 and v6 modernization docs (#27498) * docs: remove v5 and v6 modernization docs * typo * run script/gen-filenames.ts --- docs/api/modernization/overview.md | 10 --- docs/api/modernization/promisification.md | 42 ----------- docs/api/modernization/property-updates.md | 41 ---------- docs/breaking-changes.md | 87 ++++++++++++++++++---- filenames.auto.gni | 1 - 5 files changed, 74 insertions(+), 107 deletions(-) delete mode 100644 docs/api/modernization/overview.md delete mode 100644 docs/api/modernization/promisification.md delete mode 100644 docs/api/modernization/property-updates.md diff --git a/docs/api/modernization/overview.md b/docs/api/modernization/overview.md deleted file mode 100644 index ad2df400b10e..000000000000 --- a/docs/api/modernization/overview.md +++ /dev/null @@ -1,10 +0,0 @@ -## Modernization - -The Electron team is currently undergoing an initiative to modernize our API in a few concrete ways. These include: updating our modules to use idiomatic JS properties instead of separate `getPropertyX` and `setPropertyX`, converting callbacks to promises, and removing some other anti-patterns present in our APIs. The current status of the Promise initiative can be tracked in the [promisification](promisification.md) tracking file. - -As we work to perform these updates, we seek to create the least disruptive amount of change at any given time, so as many changes as possible will be introduced in a backward compatible manner and deprecated after enough time has passed to give users a chance to upgrade their API calls. - -This document and its child documents will be updated to reflect the latest status of our API changes. - -* [Promisification](promisification.md) -* [Property Updates](property-updates.md) diff --git a/docs/api/modernization/promisification.md b/docs/api/modernization/promisification.md deleted file mode 100644 index 333b978c97c3..000000000000 --- a/docs/api/modernization/promisification.md +++ /dev/null @@ -1,42 +0,0 @@ -## Promisification - -The Electron team recently underwent an initiative to convert callback-based APIs to Promise-based ones. See converted functions below: - -- [app.getFileIcon(path[, options], callback)](https://github.com/electron/electron/blob/master/docs/api/app.md#getFileIcon) -- [contents.capturePage([rect, ]callback)](https://github.com/electron/electron/blob/master/docs/api/web-contents.md#capturePage) -- [contents.executeJavaScript(code[, userGesture, callback])](https://github.com/electron/electron/blob/master/docs/api/web-contents.md#executeJavaScript) -- [contents.printToPDF(options, callback)](https://github.com/electron/electron/blob/master/docs/api/web-contents.md#printToPDF) -- [contents.savePage(fullPath, saveType, callback)](https://github.com/electron/electron/blob/master/docs/api/web-contents.md#savePage) -- [contentTracing.getCategories(callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#getCategories) -- [contentTracing.startRecording(options, callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#startRecording) -- [contentTracing.stopRecording(resultFilePath, callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#stopRecording) -- [contentTracing.getTraceBufferUsage(callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#getTraceBufferUsage) -- [cookies.flushStore(callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#flushStore) -- [cookies.get(filter, callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#get) -- [cookies.remove(url, name, callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#remove) -- [cookies.set(details, callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#set) -- [debugger.sendCommand(method[, commandParams, callback])](https://github.com/electron/electron/blob/master/docs/api/debugger.md#sendCommand) -- [desktopCapturer.getSources(options, callback)](https://github.com/electron/electron/blob/master/docs/api/desktop-capturer.md#getSources) -- [dialog.showOpenDialog([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showOpenDialog) -- [dialog.showSaveDialog([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showSaveDialog) -- [inAppPurchase.purchaseProduct(productID, quantity, callback)](https://github.com/electron/electron/blob/master/docs/api/in-app-purchase.md#purchaseProduct) -- [inAppPurchase.getProducts(productIDs, callback)](https://github.com/electron/electron/blob/master/docs/api/in-app-purchase.md#getProducts) -- [dialog.showMessageBox([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showMessageBox) -- [dialog.showCertificateTrustDialog([browserWindow, ]options, callback)](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showCertificateTrustDialog) -- [netLog.stopLogging([callback])](https://github.com/electron/electron/blob/master/docs/api/net-log.md#stopLogging) -- [protocol.isProtocolHandled(scheme, callback)](https://github.com/electron/electron/blob/master/docs/api/protocol.md#isProtocolHandled) -- [ses.clearHostResolverCache([callback])](https://github.com/electron/electron/blob/master/docs/api/session.md#clearHostResolverCache) -- [ses.clearStorageData([options, callback])](https://github.com/electron/electron/blob/master/docs/api/session.md#clearStorageData) -- [ses.setProxy(config, callback)](https://github.com/electron/electron/blob/master/docs/api/session.md#setProxy) -- [ses.resolveProxy(url, callback)](https://github.com/electron/electron/blob/master/docs/api/session.md#resolveProxy) -- [ses.getCacheSize(callback)](https://github.com/electron/electron/blob/master/docs/api/session.md#getCacheSize) -- [ses.clearAuthCache(options[, callback])](https://github.com/electron/electron/blob/master/docs/api/session.md#clearAuthCache) -- [ses.clearCache(callback)](https://github.com/electron/electron/blob/master/docs/api/session.md#clearCache) -- [ses.getBlobData(identifier, callback)](https://github.com/electron/electron/blob/master/docs/api/session.md#getBlobData) -- [shell.openExternal(url[, options, callback])](https://github.com/electron/electron/blob/master/docs/api/shell.md#openExternal) -- [webFrame.executeJavaScript(code[, userGesture, callback])](https://github.com/electron/electron/blob/master/docs/api/web-frame.md#executeJavaScript) -- [webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])](https://github.com/electron/electron/blob/master/docs/api/web-frame.md#executeJavaScriptInIsolatedWorld) -- [webviewTag.capturePage([rect, ]callback)](https://github.com/electron/electron/blob/master/docs/api/webview-tag.md#capturePage) -- [webviewTag.executeJavaScript(code[, userGesture, callback])](https://github.com/electron/electron/blob/master/docs/api/webview-tag.md#executeJavaScript) -- [webviewTag.printToPDF(options, callback)](https://github.com/electron/electron/blob/master/docs/api/webview-tag.md#printToPDF) -- [win.capturePage([rect, ]callback)](https://github.com/electron/electron/blob/master/docs/api/browser-window.md#capturePage) diff --git a/docs/api/modernization/property-updates.md b/docs/api/modernization/property-updates.md deleted file mode 100644 index cf3c7c1c35a9..000000000000 --- a/docs/api/modernization/property-updates.md +++ /dev/null @@ -1,41 +0,0 @@ -## Property Updates - -The Electron team is currently undergoing an initiative to convert separate getter and setter functions in Electron to bespoke properties with `get` and `set` functionality. During this transition period, both the new properties and old getters and setters of these functions will work correctly and be documented. - -## Candidates - -* `BrowserWindow` - * `menubarVisible` -* `crashReporter` module - * `uploadToServer` -* `webFrame` modules - * `zoomFactor` - * `zoomLevel` - * `audioMuted` -* `` - * `zoomFactor` - * `zoomLevel` - * `audioMuted` - -## Converted Properties - -* `app` module - * `accessibilitySupport` - * `applicationMenu` - * `badgeCount` - * `name` -* `DownloadItem` class - * `savePath` -* `BrowserWindow` module - * `autoHideMenuBar` - * `resizable` - * `maximizable` - * `minimizable` - * `fullscreenable` - * `movable` - * `closable` - * `backgroundThrottling` -* `NativeImage` - * `isMacTemplateImage` -* `SystemPreferences` module - * `appLevelAppearance` diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index b78a915b2dc2..6e8be97abaab 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -722,6 +722,55 @@ Note that `webkitdirectory` no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the `dialog.showOpenDialog` API ([link](https://github.com/electron/electron/blob/master/docs/api/dialog.md#dialogshowopendialogbrowserwindow-options)). +### API Changed: Callback-based versions of promisified APIs + +Electron 5 and Electron 6 introduced Promise-based versions of existing +asynchronous APIs and deprecated their older, callback-based counterparts. +In Electron 7, all deprecated callback-based APIs are now removed. + +These functions now only return Promises: + +* `app.getFileIcon()` [#15742](https://github.com/electron/electron/pull/15742) +* `app.dock.show()` [#16904](https://github.com/electron/electron/pull/16904) +* `contentTracing.getCategories()` [#16583](https://github.com/electron/electron/pull/16583) +* `contentTracing.getTraceBufferUsage()` [#16600](https://github.com/electron/electron/pull/16600) +* `contentTracing.startRecording()` [#16584](https://github.com/electron/electron/pull/16584) +* `contentTracing.stopRecording()` [#16584](https://github.com/electron/electron/pull/16584) +* `contents.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312) +* `cookies.flushStore()` [#16464](https://github.com/electron/electron/pull/16464) +* `cookies.get()` [#16464](https://github.com/electron/electron/pull/16464) +* `cookies.remove()` [#16464](https://github.com/electron/electron/pull/16464) +* `cookies.set()` [#16464](https://github.com/electron/electron/pull/16464) +* `debugger.sendCommand()` [#16861](https://github.com/electron/electron/pull/16861) +* `dialog.showCertificateTrustDialog()` [#17181](https://github.com/electron/electron/pull/17181) +* `inAppPurchase.getProducts()` [#17355](https://github.com/electron/electron/pull/17355) +* `inAppPurchase.purchaseProduct()`[#17355](https://github.com/electron/electron/pull/17355) +* `netLog.stopLogging()` [#16862](https://github.com/electron/electron/pull/16862) +* `session.clearAuthCache()` [#17259](https://github.com/electron/electron/pull/17259) +* `session.clearCache()` [#17185](https://github.com/electron/electron/pull/17185) +* `session.clearHostResolverCache()` [#17229](https://github.com/electron/electron/pull/17229) +* `session.clearStorageData()` [#17249](https://github.com/electron/electron/pull/17249) +* `session.getBlobData()` [#17303](https://github.com/electron/electron/pull/17303) +* `session.getCacheSize()` [#17185](https://github.com/electron/electron/pull/17185) +* `session.resolveProxy()` [#17222](https://github.com/electron/electron/pull/17222) +* `session.setProxy()` [#17222](https://github.com/electron/electron/pull/17222) +* `shell.openExternal()` [#16176](https://github.com/electron/electron/pull/16176) +* `webContents.loadFile()` [#15855](https://github.com/electron/electron/pull/15855) +* `webContents.loadURL()` [#15855](https://github.com/electron/electron/pull/15855) +* `webContents.hasServiceWorker()` [#16535](https://github.com/electron/electron/pull/16535) +* `webContents.printToPDF()` [#16795](https://github.com/electron/electron/pull/16795) +* `webContents.savePage()` [#16742](https://github.com/electron/electron/pull/16742) +* `webFrame.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312) +* `webFrame.executeJavaScriptInIsolatedWorld()` [#17312](https://github.com/electron/electron/pull/17312) +* `webviewTag.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312) +* `win.capturePage()` [#15743](https://github.com/electron/electron/pull/15743) + +These functions now have two forms, synchronous and Promise-based asynchronous: + +* `dialog.showMessageBox()`/`dialog.showMessageBoxSync()` [#17298](https://github.com/electron/electron/pull/17298) +* `dialog.showOpenDialog()`/`dialog.showOpenDialogSync()` [#16973](https://github.com/electron/electron/pull/16973) +* `dialog.showSaveDialog()`/`dialog.showSaveDialogSync()` [#17054](https://github.com/electron/electron/pull/17054) + ## Planned Breaking API Changes (6.0) ### API Changed: `win.setMenu(null)` is now `win.removeMenu()` @@ -733,19 +782,6 @@ win.setMenu(null) win.removeMenu() ``` -### API Changed: `contentTracing.getTraceBufferUsage()` is now a promise - -```js -// Deprecated -contentTracing.getTraceBufferUsage((percentage, value) => { - // do something -}) -// Replace with -contentTracing.getTraceBufferUsage().then(infoObject => { - // infoObject has percentage and value fields -}) -``` - ### API Changed: `electron.screen` in the renderer process should be accessed via `remote` ```js @@ -884,6 +920,31 @@ webFrame.setSpellCheckProvider('en-US', { }) ``` +### API Changed: `webContents.getZoomLevel` and `webContents.getZoomFactor` are now synchronous + +`webContents.getZoomLevel` and `webContents.getZoomFactor` no longer take callback parameters, +instead directly returning their number values. + +```js +// Deprecated +webContents.getZoomLevel((level) => { + console.log(level) +}) +// Replace with +const level = webContents.getZoomLevel() +console.log(level) +``` + +```js +// Deprecated +webContents.getZoomFactor((factor) => { + console.log(factor) +}) +// Replace with +const factor = webContents.getZoomFactor() +console.log(factor) +``` + ## Planned Breaking API Changes (4.0) The following list includes the breaking API changes made in Electron 4.0. diff --git a/filenames.auto.gni b/filenames.auto.gni index c9b219d38bbd..7d09066af7f3 100644 --- a/filenames.auto.gni +++ b/filenames.auto.gni @@ -34,7 +34,6 @@ auto_filenames = { "docs/api/menu.md", "docs/api/message-channel-main.md", "docs/api/message-port-main.md", - "docs/api/modernization", "docs/api/native-image.md", "docs/api/native-theme.md", "docs/api/net-log.md",