From 8a8d3f214f3fb367c8c2624a6abc8e24d10bd62c Mon Sep 17 00:00:00 2001 From: Shalitha Suranga Date: Fri, 31 Jan 2025 17:47:43 +0530 Subject: [PATCH] Update docs for 5.6.0 --- docs/api/clipboard.md | 6 +++- docs/api/error-codes.md | 9 ++++-- docs/api/resources.md | 34 ++++++++++++++++++++-- docs/api/server.md | 43 ++++++++++++++++++++++++++++ docs/api/window.md | 11 +++++++ docs/release-notes/cli.md | 6 ++++ docs/release-notes/client-library.md | 17 +++++++++++ docs/release-notes/framework.md | 40 ++++++++++++++++++++++++++ sidebars.js | 1 + 9 files changed, 161 insertions(+), 6 deletions(-) create mode 100644 docs/api/server.md diff --git a/docs/api/clipboard.md b/docs/api/clipboard.md index 4eeb6776..7036724d 100644 --- a/docs/api/clipboard.md +++ b/docs/api/clipboard.md @@ -62,9 +62,13 @@ let clipboardText = await Neutralino.clipboard.readText(); console.log(`Text: ${clipboardText}`); ``` -## clipboard.readImage() +## clipboard.readImage(format) Reads and returns an image from system clipboard.  +### Parameters +- `format` String (optional): Pixel data format. Accepted values are `rgb`, `rgba`, `argb`, and `bgra`. By default, the function uses the default platform-specific +pixel data format. + ### Return Object (awaited): Returns [`ClipboardImage`](#input-object-clipboardimage) object that has the same properties as in the [`writeImage()`](#clipboardwriteimageimage) function. diff --git a/docs/api/error-codes.md b/docs/api/error-codes.md index 70fc8294..732d4ba0 100644 --- a/docs/api/error-codes.md +++ b/docs/api/error-codes.md @@ -19,7 +19,7 @@ The error object has the following structure: ## Native API error codes -| Error code | Message | Thrown by +| Error code | Message | Thrown from | --------------------------- | ------------------------------------------------------- | -------- | `NE_FS_DIRCRER`| Unable to create directory. | `os.createDirectory` | `NE_FS_REMVERR`| Unable to remove path. | `os.remove` @@ -50,5 +50,8 @@ The error object has the following structure: | `NE_UP_CUPDERR`| Unable to fetch update manifest | `updater.checkForUpdates` | `NE_UP_UPDNOUF`| No update manifest loaded | `updater.install` | `NE_UP_UPDINER`| Update installation error | `updater.install` -| `NE_RS_APIRQRF`| The resources API works only if the resource file is loaded | `resources.*` -| `NE_RS_FILNOTF`| Unable to find the requested path in the resources bundle | `resources.readFile`, `resources.readBinaryFile`, `resources.extractFile` +| `NE_RS_NOPATHE`| Provided path doesn't exist in resources | `resources.readFile`, `resources.readBinaryFile`, `resources.getStats` +| `NE_RS_FILEXTF`| Unable to extract the requested file | `resources.extractFile` +| `NE_RS_DIREXTF`| Unable to extract the requested directory | `resources.extractDirectory` +| `NE_SR_MPINUSE`| Mount path is already in use | `server.mount` +| `NE_SR_NOMTPTH`| Cannot unmount the provided path, the path that was not mounted | `server.unmount` diff --git a/docs/api/resources.md b/docs/api/resources.md index f95f68b8..ff6036b5 100644 --- a/docs/api/resources.md +++ b/docs/api/resources.md @@ -4,7 +4,7 @@ toc_max_heading_level: 2 --- `Neutralino.resources` namespace implements several methods to parse, read, and extract the loaded resource bundle (`resources.neu`). If the app doesn't load resources -from the resource bundle and uses the resources directory, all these methods will throw the `NE_RS_APIRQRF` error. +from the resource bundle and uses the resources directory, all these methods will use native filesystem API as a fallback. ## resources.getFiles() Returns all files and directories embedded in the resource bundle. @@ -17,8 +17,26 @@ let files = await Neutralino.resources.getFiles(); console.log('Files: ', files); ``` +## resources.getStats(path) +Returns resource file statistics for the given path. If the given path doesn't exist or is inaccessible,`NE_RS_NOPATHE` is thrown. +So, you can use this method to check for the existance of a file or directory. + +### Parameters + +- `path` String: Resource path. + +### Return Object (awaited): +- `size` Number: Size in bytes. +- `isFile` Boolean: `true` if the path represents a normal file. +- `isDirectory` Boolean: `true` if the path represents a directory. + +```js +let stats = await Neutralino.resources.getStats('/resources/icons/myIcon.png'); +console.log('Stats:', stats); +``` + ## resources.extractFile(path, destination) -Extracts a file from the resources bundle to a preferred path. +Extracts a file from the resources bundle to a preferred path. Throws `NE_RS_FILEXTF` for file extraction failures. ### Parameters @@ -29,6 +47,18 @@ Extracts a file from the resources bundle to a preferred path. await Neutralino.resources.extractFile('/resources/scripts/run.sh', './scripts/run.sh'); ``` +## resources.extractDirectory(path, destination) +Extracts a directory from the resources bundle to a preferred path. Throws `NE_RS_DIREXTF` for directory extraction failures. + + +### Parameters +- `path` String: Resource directory path, i.e., `/resources/icons`, starts with `/` similar to all Neutralinojs app resources. +- `destination` String: Path where all extracted files should be stored. + +```js +await Neutralino.resources.extractDirectory('/resources/scripts', NL_PATH + '/extracted/scripts'); +``` + ## resources.readFile(path) Reads a text file from resources. diff --git a/docs/api/server.md b/docs/api/server.md new file mode 100644 index 00000000..4ddd77d6 --- /dev/null +++ b/docs/api/server.md @@ -0,0 +1,43 @@ +--- +title: Neutralino.server +toc_max_heading_level: 2 +--- + +`Neutralino.server` namespace offers functions to map local filesystem directories to the static server as a secure alternative for the `file://` protocol. + + +## server.mount(path, target) +Mounts a local directory. Throws `NE_FS_NOPATHE` and `NE_FS_NOTADIR` for invalid targets and `NE_SR_MPINUSE` if the path is already mounted.  + +### Parameters + +- `path` String: Resource path. +- `target` String: A directory in the local filesystem. + +```js +await Neutralino.server.mount('/app-res', NL_PATH + '/app-res'); +await fetch('/app-res/myFile.txt'); // loads NL_PATH + '/app-res/myFile.txt' +``` + +## server.unmount(path) +Deactivates a mount configuration. Throws `NE_SR_NOMTPTH` if the provided path is not mounted.  + +### Parameters + +- `path` String: Resource path. + +```js +await Neutralino.server.mount('/app-res', NL_PATH + '/app-res'); +``` + +## server.getMounts() +Lists mount configurations.  + +### Return Object (awaited): +Directory mount map that stores each configuration entry as a key-value pair. + + +```js +let mounts = await Neutralino.server.getMounts(); +console.log('Mounts:', mounts); +``` diff --git a/docs/api/window.md b/docs/api/window.md index bff3bdd7..7768aea0 100644 --- a/docs/api/window.md +++ b/docs/api/window.md @@ -271,6 +271,17 @@ let position = await Neutralino.window.getPosition(); console.log(position); ``` +## window.snapshot(path) +Takes a snapshop of the current window client area (without the window frame) and stores as a PNG image file.  + +### Parameters + +- `path` String: Path where the snapshot PNG file should be stored. + +```js +await Neutralino.window.snapshot(NL_PATH + '/images/window.png'); +``` + ## window.create(url, WindowOptions) Creates a native window. You can use this method to create new window for your multi-window Neutralinojs app. Neutralinojs spawns a new process for each native window. Therefore, the new window works as an isolated app once the window is created. diff --git a/docs/release-notes/cli.md b/docs/release-notes/cli.md index 2a0cd9b1..61ced39d 100644 --- a/docs/release-notes/cli.md +++ b/docs/release-notes/cli.md @@ -4,6 +4,12 @@ title: CLI ## Unreleased +## v11.3.1 + +### Bugfixes/improvements + +- Add execution permissions for binaries after downloading them in Unix-based and Unix-like platforms. + ## v11.3.0 ### Host projects support diff --git a/docs/release-notes/client-library.md b/docs/release-notes/client-library.md index 8d527df8..af893c3e 100644 --- a/docs/release-notes/client-library.md +++ b/docs/release-notes/client-library.md @@ -4,6 +4,23 @@ title: Client Library ## Unreleased +## v5.6.0 + +### API: server +- Export `server.mount()`, `server.unmount()`, and `server.getMounts()` functions. + +### API: resources +- Export `resources.getStats()` and `resources.extractDirectory()` functions. + +### API: window +- Export `window.snapshot()` function. + +### API: clipboard +- Add the `format` parameter to the `clipboard.readImage()` function format pixel data. Accepted formats: `rgb`, `rgba`, `argb`, and `bgra`. + +### Bugfixes/improvements +- Fix the slow loading issue on Windows by using `127.0.0.1` instead of `localhost`. + ## v5.5.0 ### Core: initialization diff --git a/docs/release-notes/framework.md b/docs/release-notes/framework.md index 76d996b2..e70aa6c2 100644 --- a/docs/release-notes/framework.md +++ b/docs/release-notes/framework.md @@ -4,6 +4,46 @@ title: Framework ## Unreleased +## v5.6.0 + +### API: server +Neutralinojs doesn't support the `file://` protocol to load local resource files due to application security concerns. Because of this limitation, app developers had to read files using filesystem APIs. The new `server` namespace implements `server.mount(path, target)`, `server.unmount(path)`, and `server.getMounts()` functions to let developers load local files from the Neutralinojs static server by creating directory mappings as an alternative for the `file://` protocol. + +For example, the following function call configures the Neutralinojs static server to serve resources on the `${NL_PATH}/app-res` directory: + +```js +await Neutralino.server.mount('/app-res', NL_PATH + '/app-res'); +``` + +With the above server configuration, `NL_PATH + '/app-res/stat.txt'` can be loaded to the webview via the following URL: + +``` +http://127.0.0.1/app-res/stat.txt +``` + +This local directory mounting configuration can be deactivated as follows: + +```js +await Neutralino.server.unmount('/app-res'); +``` + +### API: resources +- Fallback to native filesystem APIs when `NL_RESMODE` is `directory`. +- Implement `resources.getStats(path)` and `resources.extractDirectory(path, destination)` functions. + + +### API: window +- Implement the `window.snapshot(path)` function to capture the window and save it as a PNG image file. + +### Improvements/bugfixes +- Fix the empty string returning issue with the `window.getTitle()` function on Windows. +- Create non-existent directories while extracting resource files using the `resources.extractFile()` function. +- Supports using large `resources.neu` files. + +### DevOps +- Fix minor string formatting issues in the BuildZri automation script. +- Fix various test suite failure scenarios. + ## v5.5.0 ### Client library and globals injection diff --git a/sidebars.js b/sidebars.js index cf74d04d..34f18fe2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -28,6 +28,7 @@ module.exports = { 'api/updater', 'api/window', 'api/resources', + 'api/server', 'api/error-codes', 'api/global-variables', ],