Skip to content

Commit

Permalink
Merge pull request #71 from atom/78-chars-or-death
Browse files Browse the repository at this point in the history
Indent all the files to 78-characters so that doc diffs are usable
  • Loading branch information
Paul Betts committed Aug 29, 2013
2 parents f7de0e8 + 38b37f2 commit 132eb09
Show file tree
Hide file tree
Showing 18 changed files with 307 additions and 118 deletions.
43 changes: 31 additions & 12 deletions docs/app.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,22 +23,30 @@ Do final startup like creating browser window here.

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.

Expand All @@ -47,19 +55,25 @@ 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()

Expand All @@ -69,7 +83,8 @@ Returns the version of current bundle or executable.

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)

Expand All @@ -79,11 +94,15 @@ Append an argument to Chromium's command line. The argument will quoted properly

## 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.

Expand Down
8 changes: 6 additions & 2 deletions docs/atom-delegate.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
## 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:

Expand All @@ -24,4 +27,5 @@ delegate.browserMainParts.preMainMessageLoopRun = function() {

## atom-delegate.browserMainParts.preMainMessageLoopRun()

Called when atom-shell has done everything initialization and ready for creating browser windows.
Called when atom-shell has done everything initialization and ready for
creating browser windows.
13 changes: 9 additions & 4 deletions docs/auto-updater.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,29 @@
## 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

* `event` Event
* `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

* `event` Event
* `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)

Expand Down
60 changes: 43 additions & 17 deletions docs/browser-window.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
## 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');
Expand All @@ -18,7 +19,8 @@ win.show();

## 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)

Expand All @@ -37,13 +39,16 @@ win.show();
* `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: 'loading-state-changed'

Expand All @@ -56,9 +61,14 @@ Emitted when the window is starting or is done loading a page.

* `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) {
Expand All @@ -74,11 +84,14 @@ 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()

Expand All @@ -95,11 +108,16 @@ Find a window according to its `processId` and `routingId`.

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()

Expand Down Expand Up @@ -127,7 +145,8 @@ Unmaximizes the window.

### 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()

Expand Down Expand Up @@ -190,7 +209,9 @@ Returns whether the window can be manually resized by user.

* `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()

Expand Down Expand Up @@ -221,7 +242,8 @@ Changes the title of native window to `title`.

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()

Expand Down Expand Up @@ -268,25 +290,29 @@ Returns whether web page is still loading resources.

### 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()

Stops any pending navigation.

### 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()

Expand Down
4 changes: 3 additions & 1 deletion docs/build-instructions-mac.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ $ git clone https://github.com/atom/atom-shell.git

## 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
Expand Down
18 changes: 13 additions & 5 deletions docs/build-instructions-windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,17 @@
* [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

Expand All @@ -20,7 +26,9 @@ $ git clone https://github.com/atom/atom-shell.git

## 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
Expand All @@ -47,4 +55,4 @@ After building is done, you can find `atom.exe` under `out\Debug`.

```bash
$ python script/test.py
```
```
22 changes: 16 additions & 6 deletions docs/build-native-modules.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,37 @@
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
```
```
Loading

0 comments on commit 132eb09

Please sign in to comment.