From 8093300a439f1aaf7890ae1f70324a8150e35a1f Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 12 Feb 2015 13:52:28 +0800 Subject: [PATCH] docs: Use NativeImage to replace Image --- docs/README.md | 1 + docs/api/browser-window.md | 15 ++++--- docs/api/dialog.md | 2 +- docs/api/{image.md => native-image.md} | 60 +++++++++++++++++++++++--- docs/api/tray.md | 8 ++-- 5 files changed, 68 insertions(+), 18 deletions(-) rename docs/api/{image.md => native-image.md} (56%) diff --git a/docs/README.md b/docs/README.md index 0d00200def5c..474883f9ef35 100644 --- a/docs/README.md +++ b/docs/README.md @@ -46,6 +46,7 @@ Modules for both sides: * [clipboard](api/clipboard.md) * [crash-reporter](api/crash-reporter.md) +* [native-image](api/native-image.md) * [screen](api/screen.md) * [shell](api/shell.md) diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 24865e25c229..74452282ce24 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -43,13 +43,13 @@ You can also create a window without chrome by using other windows * `fullscreen` Boolean - Whether the window should show in fullscreen, when set to `false` the fullscreen button would also be hidden on OS X - * `skip-taskbar` Boolean - Do not show window in taskbar + * `skip-taskbar` Boolean - Do not show window in Taskbar * `zoom-factor` Number - The default zoom factor of the page, zoom factor is zoom percent / 100, so `3.0` represents `300%` * `kiosk` Boolean - The kiosk mode * `title` String - Default window title - * `icon` [Image](image.md) - The window icon, when omitted on Windows the - executable's icon would be used as window icon + * `icon` [NativeImage](native-image.md) - The window icon, when omitted on + Windows the executable's icon would be used as window icon * `show` Boolean - Whether window should be shown when created * `frame` Boolean - Specify `false` to create a [Frameless Window](frameless-window.md) @@ -415,7 +415,7 @@ Starts or stops flashing the window to attract user's attention. * `skip` Boolean -Makes the window do not show in taskbar. +Makes the window do not show in Taskbar. ### BrowserWindow.setKiosk(flag) @@ -545,8 +545,11 @@ it will assume `app.getName().desktop`. ### BrowserWindow.setOverlayIcon(overlay, description) -* `overlay` [Image](image.md) - the icon to display on the bottom right corner of the Taskbar icon. If this parameter is `null`, the overlay is cleared. -* `description` String - a description that will be provided to Accessibility screenreaders +* `overlay` [NativeImage](native-image.md) - the icon to display on the bottom +right corner of the Taskbar icon. If this parameter is `null`, the overlay is +cleared +* `description` String - a description that will be provided to Accessibility +screen readers Sets a 16px overlay onto the current Taskbar icon, usually used to convey some sort of application status or to passively notify the user. diff --git a/docs/api/dialog.md b/docs/api/dialog.md index a0e29f4fd9a1..f7ba10245204 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -76,7 +76,7 @@ would be passed via `callback(filename)` * `title` String - Title of the message box, some platforms will not show it * `message` String - Content of the message box * `detail` String - Extra information of the message - * `icon` [Image](image.md) + * `icon` [NativeImage](native-image.md) * `callback` Function Shows a message box, it will block until the message box is closed. It returns diff --git a/docs/api/image.md b/docs/api/native-image.md similarity index 56% rename from docs/api/image.md rename to docs/api/native-image.md index d7cf8aeea733..6ce260e89932 100644 --- a/docs/api/image.md +++ b/docs/api/native-image.md @@ -1,7 +1,7 @@ -# Image +# NativeImage -In atom-shell images are represented by their file paths, we currently do not -support in-memory images or remote images. +In atom-shell for the APIs that take images, you can pass either file paths or +`NativeImage` instances. When passing `null`, an empty image will be used. For example when creating tray or setting window's icon, you can pass image's file path as `String` to represent an image: @@ -11,12 +11,18 @@ var appIcon = new Tray('/Users/somebody/images/icon.png'); var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'}); ``` +Or read the image from clipboard: + +```javascript +var clipboard = require('clipboard'); +var image = clipboard.readImage(); +var appIcon = new Tray(image); +``` + ## Supported formats -On Mac all formats supported by the system can be used, while on Linux and -Windows only `PNG` and `JPG` formats are supported. - -So it is recommended to use `PNG` images for all cases. +Currently `PNG` and `JPEG` are supported, and it is recommended to use `PNG` +because it supports alpha channel and image is usually not compressed. ## High resolution image @@ -73,3 +79,43 @@ To mark an image as template image, its filename should end with the word * `xxxTemplate.png` * `xxxTemplate@2x.png` + +## nativeImage.createFromPng(buffer) + +* `buffer` [Buffer][buffer] + +Creates a new `NativeImage` instance from `buffer` with `PNG` format. + +## nativeImage.createFromPng(buffer) + +* `buffer` [Buffer][buffer] + +Creates a new `NativeImage` instance from `buffer` with `JPEG` format. + +## nativeImage.createFromPath(path) + +* `path` String + +Creates a new `NativeImage` instance from file located at `path`. + +## Class: NativeImage + +This class is used to represent an image. + +### NativeImage.toPng() + +Returns a [Buffer][buffer] that contains image's `PNG` encoded data. + +### NativeImage.isJpeg() + +Returns a [Buffer][buffer] that contains image's `JPEG` encoded data. + +### NativeImage.isEmpty() + +Returns whether the image is empty. + +### NativeImage.getSize() + +Returns the size of the image. + +[buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer diff --git a/docs/api/tray.md b/docs/api/tray.md index d18b3b8ff1a2..64193d7ad05f 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -40,7 +40,7 @@ rely on `clicked` event and always attach a context menu to the tray icon. ### new Tray(image) -* `image` [Image](image.md) +* `image` [NativeImage](native-image.md) Creates a new tray icon associated with the `image`. @@ -79,13 +79,13 @@ Destroys the tray icon immediately. ### Tray.setImage(image) -* `image` [Image](image.md) +* `image` [NativeImage](native-image.md) Sets the `image` associated with this tray icon. ### Tray.setPressedImage(image) -* `image` [Image](image.md) +* `image` [NativeImage](native-image.md) Sets the `image` associated with this tray icon when pressed. @@ -114,7 +114,7 @@ This is only implmented on OS X. ### Tray.displayBalloon(options) * `options` Object - * `icon` [Image](image.md) + * `icon` [NativeImage](native-image.md) * `title` String * `content` String