docs: Use NativeImage to replace Image

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)
 

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
+  * `icon` [NativeImage](native-image.md) - The window icon, when omitted on
-    executable's icon would be used as window icon
+    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.
+* `overlay` [NativeImage](native-image.md) - the icon to display on the bottom
-* `description` String - a description that will be provided to Accessibility screenreaders
+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.
 

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

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
+In atom-shell for the APIs that take images, you can pass either file paths or
-support in-memory images or remote images.
+`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
+Currently `PNG` and `JPEG` are supported, and it is recommended to use `PNG`
-Windows only `PNG` and `JPG` formats are supported.
+because it supports alpha channel and image is usually not compressed.
-
-So it is recommended to use `PNG` images for all cases.
 
 ## 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

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