2013-09-09 07:35:57 +00:00
|
|
|
# Quick start
|
|
|
|
|
|
2013-08-14 22:43:35 +00:00
|
|
|
## Introduction
|
|
|
|
|
|
2014-05-07 05:06:35 +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
|
2014-07-21 14:02:35 +00:00
|
|
|
a variant of the Node.js runtime which is focused on desktop applications
|
|
|
|
|
instead of web servers.
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-05-07 05:06:35 +00:00
|
|
|
It doesn't mean atom-shell is a JavaScript binding to GUI libraries. Instead,
|
2014-07-21 14:02:35 +00:00
|
|
|
atom-shell uses web pages as its GUI, so you could also see it as a minimal Chromium
|
2014-04-30 08:39:49 +00:00
|
|
|
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-07-21 14:02:35 +00:00
|
|
|
If you have experience with Node.js web applications, you will know that there
|
2014-05-07 05:06:35 +00:00
|
|
|
are two types of JavaScript scripts: the server side scripts and the client side
|
2014-07-21 14:02:35 +00:00
|
|
|
scripts. Server-side JavaScript is that which runs on the Node.js
|
|
|
|
|
runtime, while client-side JavaScript runs inside the user's browser.
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
In atom-shell we have similar concepts: Since atom-shell displays a GUI by showing
|
|
|
|
|
web pages, we have **scripts that run in the web page**, and also **scripts run by the atom-shell runtime**, which creates those web pages.
|
|
|
|
|
Like Node.js, we call them **client scripts**, and **browser scripts** (meaning the browser replaces the concept of the server here).
|
2014-04-30 08:39:49 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
In traditional Node.js applications, communication between server and
|
|
|
|
|
client is usually facilitated via web sockets. In atom-shell, we have provided
|
|
|
|
|
the [ipc](../api/ipc-renderer.md) module for browser to client
|
2014-05-05 06:24:57 +00:00
|
|
|
communication, and the [remote](../api/remote.md) module for easy RPC
|
2014-04-30 08:39:49 +00:00
|
|
|
support.
|
|
|
|
|
|
2014-05-07 05:06:35 +00:00
|
|
|
### Web page and Node.js
|
2014-04-30 08:39:49 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
Normal web pages are designed to not reach outside of the browser, which makes them
|
2014-05-07 05:06:35 +00:00
|
|
|
unsuitable for interacting with native systems. Atom-shell provides Node.js APIs
|
2014-07-21 14:02:35 +00:00
|
|
|
in web pages so you can access native resources from web pages, just like
|
2014-05-07 05:06:35 +00:00
|
|
|
[Node-Webkit](https://github.com/rogerwang/node-webkit).
|
2014-04-30 08:39:49 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
But unlike Node-Webkit, you cannot do native GUI related operations in web
|
|
|
|
|
pages. Instead you need to do them on the browser side by sending messages to it, or
|
|
|
|
|
using the easy [remote](../api/remote.md) module.
|
2014-04-30 08:39:49 +00:00
|
|
|
|
|
|
|
|
|
2014-04-30 09:28:36 +00:00
|
|
|
## Write your first atom-shell app
|
2013-08-14 22:43:35 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
Generally, an atom-shell app would be structured like this (see the [hello-atom](https://github.com/dougnukem/hello-atom) repo for reference):
|
2013-08-14 22:43:35 +00:00
|
|
|
|
|
|
|
|
```text
|
2014-05-07 19:21:13 +00:00
|
|
|
your-app/
|
2013-08-14 22:43:35 +00:00
|
|
|
├── package.json
|
|
|
|
|
├── main.js
|
|
|
|
|
└── index.html
|
|
|
|
|
```
|
|
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
The format of `package.json` is exactly the same as with Node's modules, and the
|
2013-08-29 14:37:51 +00:00
|
|
|
script specified by the `main` field is the startup script of your app, which
|
2014-07-21 14:02:35 +00:00
|
|
|
will run on the browser side. An example of your `package.json` might look like
|
2013-08-29 14:37:51 +00:00
|
|
|
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-07-21 14:02:35 +00:00
|
|
|
The `main.js` should create windows and handle system events, a typical
|
|
|
|
|
example being:
|
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
|
|
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
After you're done writing your app, you can create a distribution by
|
2014-05-04 10:32:12 +00:00
|
|
|
following the [Application distribution](./application-distribution.md) guide
|
2014-07-21 14:02:35 +00:00
|
|
|
and then execute the packaged app.
|
|
|
|
|
You can also just use the downloaded atom-shell binary to execute your app directly.
|
2014-04-30 09:28:36 +00:00
|
|
|
|
2014-05-07 05:06:35 +00:00
|
|
|
On Windows:
|
2014-04-30 09:28:36 +00:00
|
|
|
|
|
|
|
|
```cmd
|
2014-05-07 19:21:13 +00:00
|
|
|
$ .\atom-shell\atom.exe your-app\
|
2014-04-30 09:28:36 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
On Linux:
|
|
|
|
|
|
|
|
|
|
```bash
|
2014-05-07 19:21:13 +00:00
|
|
|
$ ./atom-shell/atom your-app/
|
2014-04-30 09:28:36 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
On Mac OS X:
|
|
|
|
|
|
|
|
|
|
```bash
|
2014-05-07 19:21:13 +00:00
|
|
|
$ ./Atom.app/Contents/MacOS/Atom your-app/
|
2014-04-30 09:28:36 +00:00
|
|
|
```
|
2014-07-01 09:49:08 +00:00
|
|
|
|
2014-07-21 14:02:35 +00:00
|
|
|
`Atom.app` here is part of the atom-shell's release package, you can download it from [here](https://github.com/atom/atom-shell/releases).
|
