Emitted when all windows have been closed.
-This event is only emitted when the application is not going to quit. If a user pressed `Cmd + Q`, or the developer called `app.quit()`, atom-shell would first try to close all windows and then emit the `will-quit` event, and in this case the `window-all-closed` would not be emitted.
+This event is only emitted when the application is not going to quit. If a
+user pressed `Cmd + Q`, or the developer called `app.quit()`, atom-shell would
+first try to close all windows and then emit the `will-quit` event, and in
+this case the `window-all-closed` would not be emitted.
## Event: will-quit
* `event` Event
-Emitted when all windows have been closed and the application will quit. Calling `event.preventDefault()` will prevent the default behaviour, which is terminating the application.
+Emitted when all windows have been closed and the application will quit.
+Calling `event.preventDefault()` will prevent the default behaviour, which is
+terminating the application.
-See description of `window-all-closed` for the differences between `will-quit` and it.
+See description of `window-all-closed` for the differences between `will-quit`
+and it.
## Event: open-file
* `event` Event
* `path` String
-Emitted when user wants to open a file with the application, it usually happens when the application is already opened and then OS wants to reuse the application to open file.
+Emitted when user wants to open a file with the application, it usually
+happens when the application is already opened and then OS wants to reuse the
+application to open file.
You should call `event.preventDefault()` if you want to handle this event.
* `event` Event
* `url` String
-Emitted when user wants to open a URL with the application, this URL scheme must be registered to be opened by your application.
+Emitted when user wants to open a URL with the application, this URL scheme
+must be registered to be opened by your application.
You should call `event.preventDefault()` if you want to handle this event.
## app.quit()
-Try to close all windows. If all windows are successfully closed, the `will-quit` event will be emitted and by default the application would be terminated.
+Try to close all windows. If all windows are successfully closed, the
+`will-quit` event will be emitted and by default the application would be
+terminated.
-This method guarantees all `beforeunload` and `unload` handlers are correctly executed. It is possible that a window cancels the quitting by returning `false` in `beforeunload` handler.
+This method guarantees all `beforeunload` and `unload` handlers are correctly
+executed. It is possible that a window cancels the quitting by returning
+`false` in `beforeunload` handler.
## app.terminate()
-Quit the application directly, it will not try to close all windows so cleanup code will not run.
+Quit the application directly, it will not try to close all windows so cleanup
+code will not run.
## app.getVersion()
Append a switch [with optional value] to Chromium's command line.
-**Note:** This will not affect `process.argv`, and is mainly used by developers to control some low-level Chromium behaviors.
+**Note:** This will not affect `process.argv`, and is mainly used by
+**developers to control some low-level Chromium behaviors.
## app.commandLine.appendArgument(value)
## app.dock.bounce([type])
-* `type` String - Can be `critical` or `informational`, the default is `informational`
+* `type` String - Can be `critical` or `informational`, the default is
+* `informational`
-When `critical` is passed, the dock icon will bounce until either the application becomes active or the request is canceled.
+When `critical` is passed, the dock icon will bounce until either the
+application becomes active or the request is canceled.
-When `informational` is passed, the dock icon will bounce for one second. The request, though, remains active until either the application becomes active or the request is canceled.
+When `informational` is passed, the dock icon will bounce for one second. The
+request, though, remains active until either the application becomes active or
+the request is canceled.
An ID representing the request would be returned.
## Synopsis
-The `atom-delegate` returns the delegate object for Chrome Content API. The atom-shell would call methods of the delegate object when the corresponding C++ code is called. Developers can override methods of it to control the underlying behaviour of the browser.
+The `atom-delegate` returns the delegate object for Chrome Content API. The
+atom-shell would call methods of the delegate object when the corresponding
+C++ code is called. Developers can override methods of it to control the
+underlying behaviour of the browser.
An example of creating a new window when the browser is initialized:
## atom-delegate.browserMainParts.preMainMessageLoopRun()
-Called when atom-shell has done everything initialization and ready for creating browser windows.
\ No newline at end of file
+Called when atom-shell has done everything initialization and ready for
+creating browser windows.
## Synopsis
-`auto-upater` module is a simple wrap around the Sparkle framework, it provides auto update service for the application.
+`auto-updater` module is a simple wrap around the Sparkle framework, it
+provides auto update service for the application.
-Before using this module, you should edit the `Info.plist` following https://github.com/andymatuschak/Sparkle/wiki.
+Before using this module, you should edit the `Info.plist` following
+https://github.com/andymatuschak/Sparkle/wiki.
## Event: will-install-update
* `version` String
* `continueUpdate` Function
-This event is emitted when the update is found and going to be installed. Calling `event.preventDefault()` would pause it, and you can call `continueUpdate` to continue the update.
+This event is emitted when the update is found and going to be installed.
+Calling `event.preventDefault()` would pause it, and you can call
+`continueUpdate` to continue the update.
## Event: ready-for-update-on-quit
* `version` String
* `quitAndUpdate` Function
-This event is emitted when user chose to delay the update until the quit. Calling `quitAndUpdate()` would quit the application and install the update.
+This event is emitted when user chose to delay the update until the quit.
+Calling `quitAndUpdate()` would quit the application and install the update.
## autoUpdater.setFeedUrl(url)
## Synopsis
-The `BrowserWindow` class gives you ability to create a browser window, an example is:
+The `BrowserWindow` class gives you ability to create a browser window, an
+example is:
```javascript
var BrowserWindow = require('browser-window');
## Class: BrowserWindow
-`BrowserWindow` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
+`BrowserWindow` is an
+[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
### new BrowserWindow(options)
* `title` String - Default window title
* `show` Boolean - Whether window should be shown when created
-Creates a new `BrowserWindow` with native properties set by the `options`. Usually you only need to set the `width` and `height`, other properties will have decent default values.
+Creates a new `BrowserWindow` with native properties set by the `options`.
+Usually you only need to set the `width` and `height`, other properties will
+have decent default values.
### Event: 'page-title-updated'
* `event` Event
-Emitted when the document changed its title, calling `event.preventDefault()` would prevent the native window's title to change.
+Emitted when the document changed its title, calling `event.preventDefault()`
+would prevent the native window's title to change.
### Event: 'close'
* `event` Event
-Emitted when the window is going to be closed. It's emitted before the `beforeunload` and `unload` event of DOM, calling `event.preventDefault()` would cancel the close.
+Emitted when the window is going to be closed. It's emitted before the
+`beforeunload` and `unload` event of DOM, calling `event.preventDefault()`
+would cancel the close.
-Usually you would want to use the `beforeunload` handler to decide whether the window should be closed, which will also be called when the window is reloaded. In atom-shell, returning an empty string or `false` would cancel the close. An example is:
+Usually you would want to use the `beforeunload` handler to decide whether the
+window should be closed, which will also be called when the window is
+reloaded. In atom-shell, returning an empty string or `false` would cancel the
+close. An example is:
```javascript
window.onbeforeunload = function(e) {
### Event: 'closed'
-Emitted when the window is closed. At the time of this event, window is not destroyed yet so you can still do some operations to the window (but you shouldn't!).
+Emitted when the window is closed. At the time of this event, window is not
+destroyed yet so you can still do some operations to the window (but you
+shouldn't!).
### Event: 'destroyed'
-Emitted when the memory taken by the native window is released. Usually you should dereference the javascript object when received this event.
+Emitted when the memory taken by the native window is released. Usually you
+should dereference the javascript object when received this event.
### Class Method: BrowserWindow.getFocusedWindow()
Destroy the window and free the memory without closing it.
-**Note:** Usually you should always call `Window.close()` to close the window, which will emit `beforeunload` and `unload` events for DOM. Only use `Window.destroy()` when the window gets into a very bad state and you want to force closing it.
+**Note:** Usually you should always call `Window.close()` to close the window,
+**which will emit `beforeunload` and `unload` events for DOM. Only use
+**`Window.destroy()` when the window gets into a very bad state and you want
+**to force closing it.
### BrowserWindow.close()
-Try to close the window, this has the same effect with user manually clicking the close button of the window. The web page may cancel the close though, see the [close event](window#event-close).
+Try to close the window, this has the same effect with user manually clicking
+the close button of the window. The web page may cancel the close though, see
+the [close event](window#event-close).
### BrowserWindow.focus()
### BrowserWindow.minimize()
-Minimizes the window. On some platforms the minimized window will be shown in the Dock.
+Minimizes the window. On some platforms the minimized window will be shown in
+the Dock.
### BrowserWindow.restore()
* `flag` Boolean
-Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.
+Sets whether the window should show always on top of other windows. After
+setting this, the window is still a normal window, not a toolbox window which
+can not be focused on.
### BrowserWindow.isAlwaysOnTop()
Returns the title of the native window.
-**Note:** The title of web page can be different from the title of the native window.
+**Note:** The title of web page can be different from the title of the native
+**window.
### BrowserWindow.flashFlame()
### BrowserWindow.isWaitingForResponse()
-Returns whether web page is waiting for a first-response for the main resource of the page.
+Returns whether web page is waiting for a first-response for the main resource
+of the page.
### BrowserWindow.stop()
### BrowserWindow.getProcessId()
-Returns window's process ID. The process ID and routing ID can be used together to locate a window.
+Returns window's process ID. The process ID and routing ID can be used
+together to locate a window.
### BrowserWindow.getRoutingId()
-Returns window's routing ID. The process ID and routing ID can be used together to locate a window.
+Returns window's routing ID. The process ID and routing ID can be used
+together to locate a window.
### BrowserWindow.loadUrl(url)
* `url` URL
-Loads the `url` in the window, the `url` must contains the protocol prefix, e.g. the `http://` or `file://`.
+Loads the `url` in the window, the `url` must contains the protocol prefix,
+e.g. the `http://` or `file://`.
### BrowserWindow.getUrl()
### BrowserWindow.reloadIgnoringCache()
-Reloads current window and ignores cache.
\ No newline at end of file
+Reloads current window and ignores cache.
## Bootstrapping
-The bootstrap script will download all necessary build dependencies and create build project files. Notice that we're using `ninja` to build `atom-shell` so there is no Xcode project generated.
+The bootstrap script will download all necessary build dependencies and create
+build project files. Notice that we're using `ninja` to build `atom-shell` so
+there is no Xcode project generated.
```bash
$ cd atom-shell
* [node.js](http://nodejs.org/)
* [git](http://git-scm.com)
-The instructions bellow are executed under [cygwin](http://www.cygwin.com), but it's not a requirement, you can also build atom-shell under Windows's console or other terminals.
+The instructions bellow are executed under [cygwin](http://www.cygwin.com),
+but it's not a requirement, you can also build atom-shell under Windows's
+console or other terminals.
-The building of atom-shell is done entirely with command line scripts, so you can use any editor you like to develop atom-shell, but it also means you can not use Visual Studio for the development. Support of building with Visual Studio will come in future.
+The building of atom-shell is done entirely with command line scripts, so you
+can use any editor you like to develop atom-shell, but it also means you can
+not use Visual Studio for the development. Support of building with Visual
+Studio will come in future.
-**Note:** Even though Visual Studio is not used for building, it's still required because we need the build toolchains it provided.
+**Note:** Even though Visual Studio is not used for building, it's still
+**required because we need the build toolchains it provided.
## Getting the code
## Bootstrapping
-The bootstrap script will download all necessary build dependencies and create build project files. Notice that we're using `ninja` to build atom-shell so there is no Visual Studio project generated.
+The bootstrap script will download all necessary build dependencies and create
+build project files. Notice that we're using `ninja` to build atom-shell so
+there is no Visual Studio project generated.
```bash
$ cd atom-shell
```bash
$ python script/test.py
-```
\ No newline at end of file
+```
-Since atom-shell is using a different V8 version from the official node, you need to build native module against atom-shell's headers to use them.
+Since atom-shell is using a different V8 version from the official node, you
+need to build native module against atom-shell's headers to use them.
-You need to use node-gyp to compile native modules, you can install node-gyp via npm if you hadn't:
+You need to use node-gyp to compile native modules, you can install node-gyp
+via npm if you hadn't:
```bash
$ npm install -g node-gyp
```
-First you need to check which node release atom-shell is carrying via `process.version` (at the time of writing it is v0.10.5), then you can configure and build native modules via following commands:
+First you need to check which node release atom-shell is carrying via
+`process.version` (at the time of writing it is v0.10.5), then you can
+configure and build native modules via following commands:
```bash
$ cd /path-to-module/
$ HOME=~/.atom-shell-gyp node-gyp rebuild --target=0.10.5 --arch=ia32 --dist-url=https://gh-contractor-zcbenz.s3.amazonaws.com/atom-shell/dist
```
-The `HOME=~/.atom-shell-gyp` changes where to find development headers. The `--target=0.10.5` is specifying node's version. The `--dist-url=...` specifies where to download the headers.
+The `HOME=~/.atom-shell-gyp` changes where to find development headers. The
+`--target=0.10.5` is specifying node's version. The `--dist-url=...` specifies
+where to download the headers.
## Use npm to build native modules
-Under most circumstances you would want to use npm to install modules, if you're using npm >= v1.2.19 (because [a patch](https://github.com/TooTallNate/node-gyp/commit/afbcdea1ffd25c02bc88d119b10337852c44d400) is needed to make `npm_config_disturl` work) you can use following code to download and build native modules against atom-shell's headers:
+Under most circumstances you would want to use npm to install modules, if
+you're using npm >= v1.2.19 (because [a
+patch](https://github.com/TooTallNate/node-gyp/commit/afbcdea1ffd25c02bc88d119b10337852c44d400)
+is needed to make `npm_config_disturl` work) you can use following code to
+download and build native modules against atom-shell's headers:
```bash
export npm_config_disturl=https://gh-contractor-zcbenz.s3.amazonaws.com/atom-shell/dist
export npm_config_target=0.10.5
export npm_config_arch=ia32
HOME=~/.atom-shell-gyp npm install module-name
-```
\ No newline at end of file
+```
## C++ and Python
-For C++ and Python, we just follow Chromium's [Coding Style](http://www.chromium.org/developers/coding-style), there is also a script `script/cpplint.py` to check whether all files confirm.
+For C++ and Python, we just follow Chromium's [Coding
+Style](http://www.chromium.org/developers/coding-style), there is also a
+script `script/cpplint.py` to check whether all files confirm.
The python's version we are using now is Python 2.7.
## CoffeeScript
-For CoffeeScript, we follow GitHub's [Style Guide](https://github.com/styleguide/javascript), and also following rules:
+For CoffeeScript, we follow GitHub's [Style
+Guide](https://github.com/styleguide/javascript), and also following rules:
-* Files should **NOT** end with new line, because we want to match Google's styles.
-* File names should be concatenated with `-` instead of `_`, e.g. `file-name.coffee` rather than `file_name.coffee`, because in [github/atom](https://github.com/github/atom) module names are usually in the `module-name` form, this rule only apply to `.coffee` files.
+* Files should **NOT** end with new line, because we want to match Google's
+ styles.
+* File names should be concatenated with `-` instead of `_`, e.g.
+ `file-name.coffee` rather than `file_name.coffee`, because in
+ [github/atom](https://github.com/github/atom) module names are usually in
+ the `module-name` form, this rule only apply to `.coffee` files.
## API Names
-When creating a new API, we should prefer getters and setters instead of jQuery's one-function style, for example, `.getText()` and `.setText(text)` are preferred to `.text([text])`. There is a [discussion](https://github.com/atom/atom-shell/issues/46) of this.
\ No newline at end of file
+When creating a new API, we should prefer getters and setters instead of
+jQuery's one-function style, for example, `.getText()` and `.setText(text)`
+are preferred to `.text([text])`. There is a
+[discussion](https://github.com/atom/atom-shell/issues/46) of this.
## Synopsis
-The `dialog` module provides functions to show system dialogs, so web applications can get the same user experience with native applications.
+The `dialog` module provides functions to show system dialogs, so web
+applications can get the same user experience with native applications.
An example of showing a dialog to select multiple files and directories:
* `options` Object
* `title` String
- * `defaultPath` String
- * `properties` Array - Contains which features the dialog should use, can contain `openFile`, `openDirectory`, `multiSelections` and `createDirectory`
+ * `defaultPath` String
+ * `properties` Array - Contains which features the dialog should use, can
+ contain `openFile`, `openDirectory`, `multiSelections` and
+ `createDirectory`
-On success, returns an array of file paths chosen by the user, otherwise returns `undefined`.
+On success, returns an array of file paths chosen by the user, otherwise
+returns `undefined`.
**Note:** The `dialog.showOpenDialog` API is synchronous and blocks all windows.
* `title` String
* `defaultPath` String
-On success, returns the path of file chosen by the user, otherwise returns `undefined`.
+On success, returns the path of file chosen by the user, otherwise returns
+`undefined`.
**Note:** The `dialog.showSaveDialog` API is synchronous and blocks all windows.
* `message` String - Content of the message box
* `detail` String - Extra information of the message
-Shows a message box, it will block until the message box is closed. It returns the index of the clicked button.
+Shows a message box, it will block until the message box is closed. It returns
+the index of the clicked button.
-**Note:** The `dialog.showMessageBox` API is synchronous and blocks all windows.
\ No newline at end of file
+**Note:** The `dialog.showMessageBox` API is synchronous and blocks all windows.
## Synopsis
-The `ipc` module allows developers to send asynchronous messages to renderers. To avoid possible dead-locks, it's not allowed to send synchronous messages in browser.
+The `ipc` module allows developers to send asynchronous messages to renderers.
+To avoid possible dead-locks, it's not allowed to send synchronous messages in
+browser.
## Event: 'message'
* `processId` Integer
* `routingId` Integer
-Emitted when renderer sent a synchronous message to the browser. The receiver should store the result in `event.result`.
+Emitted when renderer sent a synchronous message to the browser. The receiver
+should store the result in `event.result`.
-**Note:** Due to the limitation of `EventEmitter`, returning value in the event handler has no effect, so we have to store the result by using the `event` parameter.
+**Note:** Due to the limitation of `EventEmitter`, returning value in the
+event handler has no effect, so we have to store the result by using the
+`event` parameter.
## ipc.send(processId, routingId, [args...])
* `processId` Integer
* `routingId` Integer
-Send `args...` to the renderer specified by `processId` and `routingId` and return immediately, the renderer should handle the message by listening to the `message` event.
+Send `args...` to the renderer specified by `processId` and `routingId` and
+return immediately, the renderer should handle the message by listening to the
+`message` event.
## ipc.sendChannel(processId, routingId, channel, [args...])
* `routingId` Integer
* `channel` String
-This is the same with ipc.send, except that the renderer should listen to the `channel` event. The ipc.send(processId, routingId, args...) can be seen as ipc.sendChannel(processId, routingId, 'message', args...).
+This is the same with ipc.send, except that the renderer should listen to the
+`channel` event. The ipc.send(processId, routingId, args...) can be seen as
+ipc.sendChannel(processId, routingId, 'message', args...).
-**Note:** If the the first argument (e.g. `processId`) is a `BrowserWindow`, `ipc.sendChannel` would automatically get the `processId` and `routingId` from it, so you can send a message to window like this:
+**Note:** If the the first argument (e.g. `processId`) is a `BrowserWindow`,
+`ipc.sendChannel` would automatically get the `processId` and `routingId`
+from it, so you can send a message to window like this:
```javascript
ipc.sendChannel(browserWindow, 'message', ...);
-```
\ No newline at end of file
+```
## Synopsis
-The `ipc` module provides a few methods so you can send synchronous and asynchronous messages to the browser, and also receive messages sent from browser. If you want to make use of modules of browser from renderer, you might consider using the [remote](remote.md) module.
+The `ipc` module provides a few methods so you can send synchronous and
+asynchronous messages to the browser, and also receive messages sent from
+browser. If you want to make use of modules of browser from renderer, you
+might consider using the [remote](remote.md) module.
An example of echoing messages between browser and renderer:
## ipc.send([args...])
-Send all arguments to the browser and return immediately, the browser should handle the message by listening to the `message` event.
+Send all arguments to the browser and return immediately, the browser should
+handle the message by listening to the `message` event.
## ipc.sendSync([args...])
-Send all arguments to the browser synchronously, and returns the result sent from browser. The browser should handle the message by listening to the `sync-message` event.
+Send all arguments to the browser synchronously, and returns the result sent
+from browser. The browser should handle the message by listening to the
+`sync-message` event.
-**Note:** Usually developers should never use this API, since sending synchronous message would block the browser.
+**Note:** Usually developers should never use this API, since sending
+synchronous message would block the browser.
## ipc.sendChannel(channel, [args...])
* `channel` String
-This is the same with `ipc.send`, except that the browser should listen to the `channel` event. The `ipc.send(args...)` can be seen as `ipc.sendChannel('message', args...)`.
+This is the same with `ipc.send`, except that the browser should listen to the
+`channel` event. The `ipc.send(args...)` can be seen as
+`ipc.sendChannel('message', args...)`.
## ipc.sendChannelSync(channel, [args...])
* `channel` String
-This is the same with `ipc.sendSync`, except that the browser should listen to the `channel` event. The `ipc.sendSync(args...)` can be seen as `ipc.sendChannelSync('sync-message', args...)`.
+This is the same with `ipc.sendSync`, except that the browser should listen to
+the `channel` event. The `ipc.sendSync(args...)` can be seen as
+`ipc.sendChannelSync('sync-message', args...)`.
-**Note:** Usually developers should never use this API, since sending synchronous message would block the browser.
\ No newline at end of file
+**Note:** Usually developers should never use this API, since sending
+synchronous message would block the browser.
* `options` Object
* `click` Function - Callback when the menu item is clicked
- * `selector` String - Call the selector of first responder when clicked (OS X only)
- * `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or `radio`
+ * `selector` String - Call the selector of first responder when clicked (OS
+ X only)
+ * `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or
+ `radio`
* `label` String
* `sublabel` String
- * `accelerator` String - In the form of `Command+R`, `Ctrl+C`, `Shift+Command+D`, `D`, etc.
+ * `accelerator` String - In the form of `Command+R`, `Ctrl+C`,
+ `Shift+Command+D`, `D`, etc.
* `enabled` Boolean
* `visible` Boolean
* `checked` Boolean
* `groupId` Boolean - Should be specified for `radio` type menu item
- * `submenu` Menu - Should be specified for `submenu` type menu item, when it's specified the `type: 'submenu'` can be omitted for the menu item
+ * `submenu` Menu - Should be specified for `submenu` type menu item, when
+ it's specified the `type: 'submenu'` can be omitted for the menu item
## Notes on accelerator
-On OS X, the `Ctrl` would automatically translated to `Command`, if you really want `Ctrl` on OS X, you should use `MacCtrl`.
\ No newline at end of file
+On OS X, the `Ctrl` would automatically translated to `Command`, if you really
+want `Ctrl` on OS X, you should use `MacCtrl`.
## Synopsis
-The `Menu` class is used to create native menus that can be used as application menu and context menu. Each menu is consisted of multiple menu items, and each menu item can have a submenu.
+The `Menu` class is used to create native menus that can be used as
+application menu and context menu. Each menu is consisted of multiple menu
+items, and each menu item can have a submenu.
-An example of creating a menu dynamically and show it when user right clicks the page:
+An example of creating a menu dynamically and show it when user right clicks
+the page:
```javascript
var Menu = require('menu');
* `action` String
-Sends the `action` to the first responder of application, this is used for emulating default Cocoa menu behaviors, usually you would just use the `selector` property of `MenuItem`.
+Sends the `action` to the first responder of application, this is used for
+emulating default Cocoa menu behaviors, usually you would just use the
+`selector` property of `MenuItem`.
**Note:** This method is OS X only.
* `template` Array
-Generally, the `template` is just an array of `options` for constructing `MenuItem`, the usage can be referenced above.
+Generally, the `template` is just an array of `options` for constructing
+`MenuItem`, the usage can be referenced above.
-You can also attach other fields to element of the `template`, and they will become properties of the constructed menu items.
+You can also attach other fields to element of the `template`, and they will
+become properties of the constructed menu items.
### Menu.popup(browserWindow)
### Menu.items
-Get the array containing the menu's items.
\ No newline at end of file
+Get the array containing the menu's items.
## Synopsis
-The `power-monitor` module is used to monitor the power state change, you can only use it on the browser side.
+The `power-monitor` module is used to monitor the power state change, you can
+only use it on the browser side.
An example is:
## Event: resume
-Emitted when system is resuming.
\ No newline at end of file
+Emitted when system is resuming.
## Introduction
-Generally, atom-shell lets you create a web-based desktop application in pure javascript. Unlike CEF, which requires you to use C++ to write underlying code, or node-webkit, which only allows you to write everything in the web page, atom-shell gives you the power to use javascript to control the browser side.
+Generally, atom-shell lets you create a web-based desktop application in pure
+javascript. Unlike CEF, which requires you to use C++ to write underlying
+code, or node-webkit, which only allows you to write everything in the web
+page, atom-shell gives you the power to use javascript to control the browser
+side.
## Browser and renderer
-Atom-shell is built upon Chromium's Content API, so it has the same multi-processes architecture with the Chrome browser. In summary, things about UI are done in the browser process, and each web page instance would start a new renderer process.
+Atom-shell is built upon Chromium's Content API, so it has the same
+multi-processes architecture with the Chrome browser. In summary, things about
+UI are done in the browser process, and each web page instance would start a
+new renderer process.
-In atom-shell, you can just put everything in a simpler way: when you are executing javascript in browser side, you can control the application's life, create UI widget, deal with system events, and create windows which contain web pages; while on the renderer side, you can only control the web page you are showing, if you want something more like creating a new window, you should use IPC API to tell the browser to do that.
+In atom-shell, you can just put everything in a simpler way: when you are
+executing javascript in browser side, you can control the application's life,
+create UI widget, deal with system events, and create windows which contain
+web pages; while on the renderer side, you can only control the web page you
+are showing, if you want something more like creating a new window, you should
+use IPC API to tell the browser to do that.
## The architecture of an app
└── index.html
```
-The format of `package.json` is exactly the same with node's modules, and the script specified by the `main` field is the startup script of your app, which will run under the browser side. An example of your `package.json` is like this:
+The format of `package.json` is exactly the same with node's modules, and the
+script specified by the `main` field is the startup script of your app, which
+will run under the browser side. An example of your `package.json` is like
+this:
```json
{
}
```
-The `main.js` will be executed, and in which you should do the initialization work. To give the developers more power, atom-shell works by exposing necessary Content APIs in javascript, so developers can precisely control every piece of the app. An example of `main.js` is:
+The `main.js` will be executed, and in which you should do the initialization
+work. To give the developers more power, atom-shell works by exposing
+necessary Content APIs in javascript, so developers can precisely control
+every piece of the app. An example of `main.js` is:
```javascript
var app = require('app'); // Module to control application life.
}
```
-Finally the `index.html` is the web page you want to show, in fact you actually don't need to provide it, you can just make the window load url of a remote page.
+Finally the `index.html` is the web page you want to show, in fact you
+actually don't need to provide it, you can just make the window load url of a
+remote page.
## Package your app in atom-shell
-To make atom-shell run your app, you should name the folder of your app as `app`, and put it under `Atom.app/Contents/Resources/`, like this:
+To make atom-shell run your app, you should name the folder of your app as
+`app`, and put it under `Atom.app/Contents/Resources/`, like this:
```text
Atom.app/Contents/Resources/app/
└── index.html
```
-Then atom-shell will automatically read your `package.json`. If there is no `Atom.app/Contents/Resources/app/`, atom-shell will load the default empty app, which is `Atom.app/Contents/Resources/browser/default_app/`.
+Then atom-shell will automatically read your `package.json`. If there is no
+`Atom.app/Contents/Resources/app/`, atom-shell will load the default empty
+app, which is `Atom.app/Contents/Resources/browser/default_app/`.
## IPC between browser and renderer
-Atom-shell provides a set of javascript APIs for developers to communicate between browser and renderers. There are two types of message: asynchronous messages and synchronous messages, the former one is quite similar with node's IPC APIs, while the latter one is mainly used for implement the RPC API. Details can be found in the `ipc` module reference.
\ No newline at end of file
+Atom-shell provides a set of javascript APIs for developers to communicate
+between browser and renderers. There are two types of message: asynchronous
+messages and synchronous messages, the former one is quite similar with node's
+IPC APIs, while the latter one is mainly used for implement the RPC API.
+Details can be found in the `ipc` module reference.
## Synopsis
-It's common that the developers want to use modules in browsers from the renderer, like closing current window, opening file dialogs, etc. Instead of writing IPC code for every operation you want to do, atom-shell provides the `remote` module to let you do RPC call just like using normal javascript objects.
+It's common that the developers want to use modules in browsers from the
+renderer, like closing current window, opening file dialogs, etc. Instead of
+writing IPC code for every operation you want to do, atom-shell provides the
+`remote` module to let you do RPC call just like using normal javascript
+objects.
An example of creating a window in renderer:
## Lifetime of remote objects
-Every object returned by `remote` module represents an object in browser (e.g. a remote object), so when you call methods of an object, or call a returned function, or even create a object with the returned constructor, you are indeed making a synchronous RPC call. And when the renderer releases the last reference to the remote object, the browser would release the corresponding reference too.
+Every object returned by `remote` module represents an object in browser (e.g.
+a remote object), so when you call methods of an object, or call a returned
+function, or even create a object with the returned constructor, you are
+indeed making a synchronous RPC call. And when the renderer releases the last
+reference to the remote object, the browser would release the corresponding
+reference too.
-This also means that, if the renderer keeps a reference to an object in browser, the object would never be released. So be careful to never leak the remote objects.
+This also means that, if the renderer keeps a reference to an object in
+browser, the object would never be released. So be careful to never leak the
+remote objects.
## Passing callbacks
-Many APIs in browser accepts callbacks, so the `remote` module also supports passing callbacks when calling remote functions, and the callbacks passed would become remote functions in the browser.
+Many APIs in browser accepts callbacks, so the `remote` module also supports
+passing callbacks when calling remote functions, and the callbacks passed
+would become remote functions in the browser.
-But in order to avoid possible dead locks, the callbacks passed to browser would be called asynchronously in browser, so you should never expect the browser to get the return value of the passed callback.
+But in order to avoid possible dead locks, the callbacks passed to browser
+would be called asynchronously in browser, so you should never expect the
+browser to get the return value of the passed callback.
-Another thing is the lifetime of the remote callbacks in browser, it might be very tempting to do things like following:
+Another thing is the lifetime of the remote callbacks in browser, it might be
+very tempting to do things like following:
```javascript
var remote = require('remote');
});
```
-Yes it will work correctly, but when you reload the window, the callback you setup on the object in browser will not be erased, resources are leaked and there is no magic in javascript to release a referenced object.
+Yes it will work correctly, but when you reload the window, the callback you
+setup on the object in browser will not be erased, resources are leaked and
+there is no magic in javascript to release a referenced object.
-So if you really need to keep a reference of callbacks in browser, you should write the callback in browser and send messages to renderer. And also make use of DOM's events like `unload` and `beforeunload`, they will work perfectly.
+So if you really need to keep a reference of callbacks in browser, you should
+write the callback in browser and send messages to renderer. And also make use
+of DOM's events like `unload` and `beforeunload`, they will work perfectly.
## remote.require(module)
Return the `BrowserWindow` object that represents current window.
-`Note:` it doesn't return the `window` object which represents the global scope, instead it returns an instance of the `BrowserWindow` class which is created with `browser-window` module in browser.
+`Note:` it doesn't return the `window` object which represents the global
+scope, instead it returns an instance of the `BrowserWindow` class which is
+created with `browser-window` module in browser.
## remote.getGlobal(name)
## remote.process
-Getter to return the `process` object in browser, this is the same with `remote.getGlobal('process')` but gets cached.
\ No newline at end of file
+Getter to return the `process` object in browser, this is the same with
+`remote.getGlobal('process')` but gets cached.
* `url` String
-Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the default mail user agent.)
+Open the given external protocol URL in the desktop's default manner. (For
+example, mailto: URLs in the default mail user agent.)
## shell.moveItemToTrash(fullPath)
## shell.beep()
-Play the beep sound.
\ No newline at end of file
+Play the beep sound.
## Overview
-The source code of atom-shell is separated into a few parts, and we are mostly following Chromium on the separation conventions.
+The source code of atom-shell is separated into a few parts, and we are mostly
+following Chromium on the separation conventions.
-You may need to become familiar with [Chromium's multi-process architecture](http://dev.chromium.org/developers/design-documents/multi-process-architecture) to understand the source code better.
+You may need to become familiar with [Chromium's multi-process
+architecture](http://dev.chromium.org/developers/design-documents/multi-process-architecture)
+to understand the source code better.
## Structure of source code
-* **app** - Contains system entry code, this is the most basic level of the program.
-* **browser** - The frontend including the main window, UI, and all browser side things. This talks to the renderer to manage web pages.
+* **app** - Contains system entry code, this is the most basic level of the
+ program.
+* **browser** - The frontend including the main window, UI, and all browser
+ side things. This talks to the renderer to manage web pages.
* **atom** - Initializes the javascript environment of browser.
- * **default_app** - The default page to show when atom-shell is started without providing an app.
+ * **default_app** - The default page to show when atom-shell is started
+ without providing an app.
* **api** - The implementation of browser side APIs.
* **lib** - Javascript part of the API implementation.
* **renderer** - Code that runs in renderer.
* **api** - The implementation of renderer side APIs.
* **lib** - Javascript part of the API implementation.
-* **common** - Code that used by both browser and renderer, including some utility functions and code to integrate node's message loop into Chromium's message loop.
- * **api** - The implementation of common APIs, and foundations of atom-shell's built-in modules.
+* **common** - Code that used by both browser and renderer, including some
+ utility functions and code to integrate node's message loop into Chromium's message loop.
+ * **api** - The implementation of common APIs, and foundations of
+ atom-shell's built-in modules.
* **lib** - Javascript part of the API implementation.
* **spec** - Automatic tests.
* **script** - Scripts for building atom-shell.
* **vendor** - Build dependencies.
* **tools** - Helper scripts to build atom-shell.
-* **node_modules** - Third party node modules used for building or running specs.
+* **node_modules** - Third party node modules used for building or running
+ specs.
* **out** - Output directory for `ninja`.
-* **dist** - Temporary directory created by `script/create-dist.py` script when creating an distribution.
-* **node** - Downloaded node binary, it's built from https://github.com/atom/node/tree/chromium-v8.
-* **frameworks** - Downloaded third-party binaries of frameworks (only on Mac).
\ No newline at end of file
+* **dist** - Temporary directory created by `script/create-dist.py` script
+ when creating an distribution.
+* **node** - Downloaded node binary, it's built from
+ https://github.com/atom/node/tree/chromium-v8.
+* **frameworks** - Downloaded third-party binaries of frameworks (only on
+ Mac).
projects / platform / framework / web / crosswalk-tizen.git / commitdiff