2013-09-09 07:35:57 +00:00
|
|
|
# Quick start
|
|
|
|
|
|
2013-08-14 22:43:35 +00:00
|
|
|
## Introduction
|
|
|
|
|
|
2014-04-30 08:39:49 +00:00
|
|
|
Generally, atom-shell enables you to create desktop applications with pure
|
|
|
|
|
JavaScript by providing a runtime with rich native APIs, you could see it as
|
|
|
|
|
an variant of node.js runtime that focused on desktop applications instead of
|
|
|
|
|
web server.
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 08:39:49 +00:00
|
|
|
But it doesn't mean atom-shell is a JavaScript binding to GUI libraries, instead
|
|
|
|
|
atom-shell uses web pages as GUI, so you could also see it as a minimal Chromium
|
|
|
|
|
browser, controlled by JavaScript.
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 08:39:49 +00:00
|
|
|
### The browser side
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 08:39:49 +00:00
|
|
|
If you had experience with node.js web applications, you would notice that there
|
|
|
|
|
are types of JavaScript scripts: the server side scripts and the client side
|
|
|
|
|
scripts. The server side JavaScript, is the scrips that run on the node.js
|
|
|
|
|
runtime, and the client side JavaScript, is the ones that run on user's browser.
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 08:39:49 +00:00
|
|
|
In atom-shell we have similar concepts, since atom-shell displays GUI by showing
|
|
|
|
|
web pages, we would have scripts that run in the web page, and also have scripts
|
|
|
|
|
ran by the atom-shell runtime, which created those web pages. Like node.js, we
|
|
|
|
|
call the former ones client client scripts, and the latter one browser side
|
|
|
|
|
scripts.
|
|
|
|
|
|
|
|
|
|
In traditional node.js applications, communication between server side and
|
|
|
|
|
client side are usually done by web sockets. In atom-shell, we have provided
|
|
|
|
|
the [ipc](../api/renderer/ipc-renderer.md) module for browser side to client
|
|
|
|
|
communication, and the [remote](../api/renderer/remote.md) module for easy RPC
|
|
|
|
|
support.
|
|
|
|
|
|
|
|
|
|
### Web page and node.js
|
|
|
|
|
|
|
|
|
|
Normal web pages are designed to not touch outside world, which makes them not
|
|
|
|
|
suitable for interacting with native systems, atom-shell provides node.js APIs
|
|
|
|
|
in web pages so you could access native resources in web pages, just like
|
|
|
|
|
[node-webkit](https://github.com/rogerwang/node-webkit).
|
|
|
|
|
|
|
|
|
|
But unlike node-webkit, you could not do native GUI related operations in web
|
|
|
|
|
pages, instead you need to do them on the browser side by sending messages or
|
|
|
|
|
use the easy [remote](../api/renderer/remote.md) module.
|
|
|
|
|
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
## Write your first atom-shell app
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
Generally, an atom-shell app would be like this:
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
app/
|
|
|
|
|
├── package.json
|
|
|
|
|
├── main.js
|
|
|
|
|
└── index.html
|
|
|
|
|
```
|
|
|
|
|
|
2013-08-29 14:37:51 +00:00
|
|
|
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:
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
2014-04-30 09:28:36 +00:00
|
|
|
"name" : "your-app",
|
2013-08-14 22:43:35 +00:00
|
|
|
"version" : "0.1.0",
|
|
|
|
|
"main" : "main.js"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
The `main.js` should create windows and handle system events, and an typical
|
|
|
|
|
example is:
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
var app = require('app'); // Module to control application life.
|
2014-04-30 09:28:36 +00:00
|
|
|
var BrowserWindow = require('browser-window'); // Module to create native browser window.
|
|
|
|
|
|
|
|
|
|
// Report crashes to our server.
|
|
|
|
|
require('crash-reporter').start();
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
// Keep a global reference of the window object, if you don't, the window will
|
|
|
|
|
// be closed automatically when the javascript object is GCed.
|
|
|
|
|
var mainWindow = null;
|
|
|
|
|
|
|
|
|
|
// Quit when all windows are closed.
|
|
|
|
|
app.on('window-all-closed', function() {
|
2014-04-30 09:28:36 +00:00
|
|
|
if (process.platform != 'darwin')
|
|
|
|
|
app.quit();
|
2013-08-14 22:43:35 +00:00
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// This method will be called when atom-shell has done everything
|
|
|
|
|
// initialization and ready for creating browser windows.
|
2013-12-27 03:08:26 +00:00
|
|
|
app.on('ready', function() {
|
2014-04-30 09:28:36 +00:00
|
|
|
// Create the browser window.
|
|
|
|
|
mainWindow = new BrowserWindow({width: 800, height: 600});
|
|
|
|
|
|
2013-08-14 22:43:35 +00:00
|
|
|
// and load the index.html of the app.
|
|
|
|
|
mainWindow.loadUrl('file://' + __dirname + '/index.html');
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
// Emitted when the window is closed.
|
2013-08-14 22:43:35 +00:00
|
|
|
mainWindow.on('closed', function() {
|
|
|
|
|
// Dereference the window object, usually you would store windows
|
|
|
|
|
// in an array if your app supports multi windows, this is the time
|
|
|
|
|
// when you should delete the corresponding element.
|
|
|
|
|
mainWindow = null;
|
|
|
|
|
});
|
2013-12-17 14:08:45 +00:00
|
|
|
});
|
2013-08-14 22:43:35 +00:00
|
|
|
```
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
Finally the `index.html` is the web page you want to show:
|
|
|
|
|
|
|
|
|
|
```html
|
|
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Hello World!</title>
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
<h1>Hello World!</h1>
|
|
|
|
|
We are using node.js <script>document.write(process.version)</script>
|
|
|
|
|
and atom-shell <script>document.write(process.versions['atom-shell'])</script>.
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Run your app
|
|
|
|
|
|
|
|
|
|
After done writing your app, you could create a distribution of your app by
|
|
|
|
|
following next section and then execute the packaged binary, or you can just
|
|
|
|
|
use the downloaded atom-shell binary to execute your app.
|
|
|
|
|
|
|
|
|
|
On Window:
|
|
|
|
|
|
|
|
|
|
```cmd
|
|
|
|
|
$ .\atom-shell\atom.exe app
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
On Linux:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ ./atom-shell/atom app
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
On Mac OS X:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ ./Atom.app/Contents/MacOS/Atom app
|
|
|
|
|
```
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
## Distribute your app
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
To distribute your app with atom-shell, you should name the folder of your app
|
|
|
|
|
as `app`, and put it under atom-shell's resources directory (on OS X it is
|
|
|
|
|
`Atom.app/Contents/Resources/`, and on Linux and Windows it is `resources/`),
|
|
|
|
|
like this:
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
Atom.app/Contents/Resources/app/
|
|
|
|
|
├── package.json
|
|
|
|
|
├── main.js
|
|
|
|
|
└── index.html
|
|
|
|
|
```
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
Then execute `Atom.app` (or `atom` on Linux, and `atom.exe` on Window), and
|
|
|
|
|
atom-shell will start as your app.
|
