Merge pull request #5605 from preco21/document-fixes-5
docs: Improve docs
This commit is contained in:
commit
8fd9957453
7 changed files with 114 additions and 45 deletions
|
@ -34,10 +34,12 @@ Emitted when Electron has finished initialization.
|
|||
|
||||
Emitted when all windows have been closed.
|
||||
|
||||
If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app; however, if you subscribe, you control whether the app quits or not. If the
|
||||
user pressed `Cmd + Q`, or the developer called `app.quit()`, Electron will
|
||||
first try to close all the windows and then emit the `will-quit` event, and in
|
||||
this case the `window-all-closed` event would not be emitted.
|
||||
If you do not subscribe to this event and all windows are closed, the default
|
||||
behavior is to quit the app; however, if you subscribe, you control whether the
|
||||
app quits or not. If the user pressed `Cmd + Q`, or the developer called
|
||||
`app.quit()`, Electron will first try to close all the windows and then emit the
|
||||
`will-quit` event, and in this case the `window-all-closed` event would not be
|
||||
emitted.
|
||||
|
||||
### Event: 'before-quit'
|
||||
|
||||
|
@ -87,7 +89,8 @@ handle this case (even before the `ready` event is emitted).
|
|||
|
||||
You should call `event.preventDefault()` if you want to handle this event.
|
||||
|
||||
On Windows, you have to parse `process.argv` (in the main process) to get the filepath.
|
||||
On Windows, you have to parse `process.argv` (in the main process) to get the
|
||||
filepath.
|
||||
|
||||
### Event: 'open-url' _OS X_
|
||||
|
||||
|
@ -108,8 +111,8 @@ Returns:
|
|||
* `event` Event
|
||||
* `hasVisibleWindows` Boolean
|
||||
|
||||
Emitted when the application is activated, which usually happens when the user clicks on
|
||||
the application's dock icon.
|
||||
Emitted when the application is activated, which usually happens when the user
|
||||
clicks on the application's dock icon.
|
||||
|
||||
### Event: 'continue-activity' _OS X_
|
||||
|
||||
|
@ -251,7 +254,8 @@ Emitted when the gpu process crashes.
|
|||
|
||||
The `app` object has the following methods:
|
||||
|
||||
**Note:** Some methods are only available on specific operating systems and are labeled as such.
|
||||
**Note:** Some methods are only available on specific operating systems and are
|
||||
labeled as such.
|
||||
|
||||
### `app.quit()`
|
||||
|
||||
|
@ -283,7 +287,8 @@ Hides all application windows without minimizing them.
|
|||
|
||||
### `app.show()` _OS X_
|
||||
|
||||
Shows application windows after they were hidden. Does not automatically focus them.
|
||||
Shows application windows after they were hidden. Does not automatically focus
|
||||
them.
|
||||
|
||||
### `app.getAppPath()`
|
||||
|
||||
|
@ -397,8 +402,8 @@ The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally
|
|||
|
||||
* `protocol` String - The name of your protocol, without `://`.
|
||||
|
||||
This method checks if the current executable as the default handler for a protocol
|
||||
(aka URI scheme). If so, it will remove the app as the default handler.
|
||||
This method checks if the current executable as the default handler for a
|
||||
protocol (aka URI scheme). If so, it will remove the app as the default handler.
|
||||
|
||||
### `app.isDefaultProtocolClient(protocol)` _OS X_ _Windows_
|
||||
|
||||
|
@ -407,8 +412,11 @@ This method checks if the current executable as the default handler for a protoc
|
|||
This method checks if the current executable is the default handler for a protocol
|
||||
(aka URI scheme). If so, it will return true. Otherwise, it will return false.
|
||||
|
||||
**Note:** On OS X, you can use this method to check if the app has been registered as the default protocol handler for a protocol. You can also verify this by checking `~/Library/Preferences/com.apple.LaunchServices.plist` on the OS X machine.
|
||||
Please refer to [Apple's documentation][LSCopyDefaultHandlerForURLScheme] for details.
|
||||
**Note:** On OS X, you can use this method to check if the app has been
|
||||
registered as the default protocol handler for a protocol. You can also verify
|
||||
this by checking `~/Library/Preferences/com.apple.LaunchServices.plist` on the
|
||||
OS X machine. Please refer to
|
||||
[Apple's documentation][LSCopyDefaultHandlerForURLScheme] for details.
|
||||
|
||||
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
|
||||
|
||||
|
|
|
@ -2,7 +2,8 @@
|
|||
|
||||
> Enable apps to automatically update themselves.
|
||||
|
||||
The `autoUpdater` module provides an interface for the [Squirrel](https://github.com/Squirrel) framework.
|
||||
The `autoUpdater` module provides an interface for the
|
||||
[Squirrel](https://github.com/Squirrel) framework.
|
||||
|
||||
You can quickly launch a multi-platform release server for distributing your
|
||||
application by using one of these projects:
|
||||
|
|
|
@ -92,7 +92,8 @@ will be passed via `callback(filename)`
|
|||
* `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or
|
||||
`"warning"`. On Windows, "question" displays the same icon as "info", unless
|
||||
you set an icon using the "icon" option.
|
||||
* `buttons` Array - Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".
|
||||
* `buttons` Array - Array of texts for buttons. On Windows, an empty array
|
||||
will result in one button labeled "OK".
|
||||
* `defaultId` Integer - Index of the button in the buttons array which will
|
||||
be selected by default when the message box opens.
|
||||
* `title` String - Title of the message box, some platforms will not show it.
|
||||
|
|
|
@ -74,4 +74,3 @@ const BrowserWindow = electron.BrowserWindow;
|
|||
|
||||
[gui]: https://en.wikipedia.org/wiki/Graphical_user_interface
|
||||
[destructuring-assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
|
||||
[issue-387]: https://github.com/electron/electron/issues/387
|
||||
|
|
|
@ -1,11 +1,21 @@
|
|||
# Electron Versioning
|
||||
|
||||
If you are a seasoned Node developer, you are surely aware of `semver` - and might be used to giving your dependency management systems only rough guidelines rather than fixed version numbers. Due to the hard dependency on Node and Chromium, Electron is in a slightly more difficult position and does not follow semver. You should therefor always reference a specific version of Electron.
|
||||
If you are a seasoned Node developer, you are surely aware of `semver` - and
|
||||
might be used to giving your dependency management systems only rough guidelines
|
||||
rather than fixed version numbers. Due to the hard dependency on Node and
|
||||
Chromium, Electron is in a slightly more difficult position and does not follow
|
||||
semver. You should therefor always reference a specific version of Electron.
|
||||
|
||||
Version numbers are bumped using the following rules:
|
||||
|
||||
* Major: For breaking changes in Electron's API - if you upgrade from `0.37.0` to `1.0.0`, you will have to update your app.
|
||||
* Minor: For major Chrome and minor Node upgrades; or significant Electron changes - if you upgrade from `1.0.0` to `1.1.0`, your app is supposed to still work, but you might have to work around small changes.
|
||||
* Patch: For new features and bug fixes - if you upgrade from `1.0.0` to `1.0.1`, your app will continue to work as-is.
|
||||
|
||||
If you are using `electron-prebuilt`, we recommend that you set a fixed version number (`1.1.0` instead of `^1.1.0`) to ensure that all upgrades of Electron are a manual operation made by you, the developer.
|
||||
* Major: For breaking changes in Electron's API - if you upgrade from `0.37.0`
|
||||
to `1.0.0`, you will have to update your app.
|
||||
* Minor: For major Chrome and minor Node upgrades; or significant Electron
|
||||
changes - if you upgrade from `1.0.0` to `1.1.0`, your app is supposed to
|
||||
still work, but you might have to work around small changes.
|
||||
* Patch: For new features and bug fixes - if you upgrade from `1.0.0` to
|
||||
`1.0.1`, your app will continue to work as-is.
|
||||
|
||||
If you are using `electron-prebuilt`, we recommend that you set a fixed version
|
||||
number (`1.1.0` instead of `^1.1.0`) to ensure that all upgrades of Electron are
|
||||
a manual operation made by you, the developer.
|
||||
|
|
|
@ -22,9 +22,9 @@ Apple. You can follow these [existing guides][nwjs-guide] on web.
|
|||
### Get Team ID
|
||||
|
||||
Before signing your app, you need to know the Team ID of your account. To locate
|
||||
your Team ID, Sign in to https://developer.apple.com/account/, and click
|
||||
Membership in the sidebar. Your Team ID appears in the Membership Information
|
||||
section under the team name.
|
||||
your Team ID, Sign in to [Apple Developer Center](https://developer.apple.com/account/),
|
||||
and click Membership in the sidebar. Your Team ID appears in the Membership
|
||||
Information section under the team name.
|
||||
|
||||
### Sign Your App
|
||||
|
||||
|
|
|
@ -1,22 +1,42 @@
|
|||
# Windows Store Guide
|
||||
|
||||
With Windows 8, the good old win32 exectuable got a new sibling: The Universial Windows Platform. The new `.appx` format does not only enable a number of new powerful APIs like Cortana or Push Notifications, but through the Windows Store, also simplifies installation and updating.
|
||||
With Windows 8, the good old win32 executable got a new sibling: The Universal
|
||||
Windows Platform. The new `.appx` format does not only enable a number of new
|
||||
powerful APIs like Cortana or Push Notifications, but through the Windows Store,
|
||||
also simplifies installation and updating.
|
||||
|
||||
Microsoft [developed a tool that compiles Electron apps as `.appx` packages](http://github.com/catalystcode/electron-windows-store), enabling developers to use some of the goodies found in the new application model. This guide explains how to use it - and what the capabilities and limitations of an Electron AppX package are.
|
||||
Microsoft [developed a tool that compiles Electron apps as `.appx` packages](http://github.com/catalystcode/electron-windows-store),
|
||||
enabling developers to use some of the goodies found in the new application
|
||||
model. This guide explains how to use it - and what the capabilities and
|
||||
limitations of an Electron AppX package are.
|
||||
|
||||
## Background and Requirements
|
||||
|
||||
Windows 10 "Anniversary Update" is able to run win32 `.exe` binaries by launching them together with a virtualized filesystem and registry. Both are created during compilation by running app and installer inside a Windows Container, allowing Windows to identify exactly which modifications to the operating system are done during installation. Pairing the executable with a virtual filesystem and a virtual registry allows Windows to enable one-click installation and uninstallation.
|
||||
Windows 10 "Anniversary Update" is able to run win32 `.exe` binaries by
|
||||
launching them together with a virtualized filesystem and registry. Both are
|
||||
created during compilation by running app and installer inside a Windows
|
||||
Container, allowing Windows to identify exactly which modifications to the
|
||||
operating system are done during installation. Pairing the executable with a
|
||||
virtual filesystem and a virtual registry allows Windows to enable one-click
|
||||
installation and uninstallation.
|
||||
|
||||
In addition, the exe is launched inside the appx model - meaning that it can use many of the APIs available to the Universial Windows Platform. To gain even more capabilities, an Electron app can pair up with an invisible UWP app launched together with the `exe` - sort of launched as a sidekick to run tasks in the background, receive push notifications, or to communicate with other UWP applications.
|
||||
In addition, the exe is launched inside the appx model - meaning that it can use
|
||||
many of the APIs available to the Universal Windows Platform. To gain even more
|
||||
capabilities, an Electron app can pair up with an invisible UWP app launched
|
||||
together with the `exe` - sort of launched as a sidekick to run tasks in the
|
||||
background, receive push notifications, or to communicate with other UWP
|
||||
applications.
|
||||
|
||||
To compile any existing Electron app, ensure that you have the following requirements:
|
||||
To compile any existing Electron app, ensure that you have the following
|
||||
requirements:
|
||||
|
||||
* Windows 10 Anniversary Update - Enterprise Edition (This is build 14316 and up
|
||||
- as of May 2016, it's part of the Windows Insiders Preview)
|
||||
* A machine with 64 bit (x64) processor, Hardware-Assisted Virtualization, and
|
||||
Second Level Address Translation (SLAT)
|
||||
* The Windows 10 SDK, [downloadable here](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
|
||||
* At least Node 4 (to check, run `node -v`)
|
||||
|
||||
* Windows 10 Anniversary Update - Enterprise Edition (This is build 14316 and up - as of May 2016, it's part of the Windows Insiders Preview)
|
||||
* A machine with 64 bit (x64) processor, Hardware-Assisted Virtualization, and Second Level Address Translation (SLAT)
|
||||
* The Windows 10 SDK, [downloadable here](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
|
||||
* At least Node 4 (to check, run `node -v`)
|
||||
|
||||
Then, go and install the `electron-windows-store` CLI:
|
||||
|
||||
```
|
||||
|
@ -25,17 +45,30 @@ npm install -g electron-windows-store
|
|||
|
||||
## Setup and Preparation
|
||||
|
||||
Before running the CLI for the first time, you will have to setup the "Windows Desktop App Converter". This will take a few minutes, but don't worry - you only have to do this once. Download and Desktop App Converter from [here](https://www.microsoft.com/en-us/download/details.aspx?id=51691). You will receive two files: `DesktopAppConverter.zip` and `BaseImage-14316.wim`.
|
||||
Before running the CLI for the first time, you will have to setup the "Windows
|
||||
Desktop App Converter". This will take a few minutes, but don't worry - you only
|
||||
have to do this once. Download and Desktop App Converter from
|
||||
[here](https://www.microsoft.com/en-us/download/details.aspx?id=51691). You will
|
||||
receive two files: `DesktopAppConverter.zip` and `BaseImage-14316.wim`.
|
||||
|
||||
1. Unzip `DesktopAppConverter.zip`. From an elevated PowerShell (opened with "run as Administrator", ensure that your systems execution policy allows us to run everything we intend to run by calling `Set-ExecutionPolicy bypass`.
|
||||
2. Then, run the installation of the Desktop App Converter, passing in the location of the Windows base Image (downloaded as `BaseImage-14316.wim`), by calling `.\DesktopAppConverter.ps1 -Setup -BaseImage .\BaseImage-14316.wim`.
|
||||
3. If running the above command prompts you for a reboot, please restart your machine and run the above command again after a successful restart.
|
||||
1. Unzip `DesktopAppConverter.zip`. From an elevated PowerShell (opened with
|
||||
"run as Administrator", ensure that your systems execution policy allows us to
|
||||
run everything we intend to run by calling `Set-ExecutionPolicy bypass`.
|
||||
2. Then, run the installation of the Desktop App Converter, passing in the
|
||||
location of the Windows base Image (downloaded as `BaseImage-14316.wim`), by
|
||||
calling `.\DesktopAppConverter.ps1 -Setup -BaseImage .\BaseImage-14316.wim`.
|
||||
3. If running the above command prompts you for a reboot, please restart your
|
||||
machine and run the above command again after a successful restart.
|
||||
|
||||
Once installation succeeded, you can move on to compiling your Electron app.
|
||||
|
||||
## Package Your Electron Application
|
||||
|
||||
Package the application using [electron-packager](https://github.com/electron-userland/electron-packager) (or a similar tool). Make sure to remove `node_modules` that you don't need in your final application, since any module you don't actually need will just increase your application's size.
|
||||
Package the application using
|
||||
[electron-packager](https://github.com/electron-userland/electron-packager)
|
||||
(or a similar tool). Make sure to remove `node_modules` that you don't need in
|
||||
your final application, since any module you don't actually need will just
|
||||
increase your application's size.
|
||||
|
||||
The output should look roughly like this:
|
||||
|
||||
|
@ -70,7 +103,10 @@ The output should look roughly like this:
|
|||
|
||||
## Running the Command Line Tool
|
||||
|
||||
From an elevated PowerShell (run it "as Administrator"), run `electron-windows-store` with the required parameters, passing both the input and output directories, the app's name and version, and confirmation that `node_modules` should be flattened.
|
||||
From an elevated PowerShell (run it "as Administrator"), run
|
||||
`electron-windows-store` with the required parameters, passing both the input
|
||||
and output directories, the app's name and version, and confirmation that
|
||||
`node_modules` should be flattened.
|
||||
|
||||
```
|
||||
electron-windows-store `
|
||||
|
@ -81,12 +117,26 @@ electron-windows-store `
|
|||
--package-name myelectronapp
|
||||
```
|
||||
|
||||
Once executed, the tool goes to work: It accepts your Electron app as an input, flattening the `node_modules`. Then, it archives your application as `app.zip`. Using an installer and a Windows Container, the tool creates an "expanded" AppX package - including the Windows Application Manifest (`AppXManifest.xml`) as well as the virtual file system and the virtual registry inside your output folder.
|
||||
Once executed, the tool goes to work: It accepts your Electron app as an input,
|
||||
flattening the `node_modules`. Then, it archives your application as `app.zip`.
|
||||
Using an installer and a Windows Container, the tool creates an "expanded" AppX
|
||||
package - including the Windows Application Manifest (`AppXManifest.xml`) as
|
||||
well as the virtual file system and the virtual registry inside your output
|
||||
folder.
|
||||
|
||||
Once the expanded AppX files are created, the tool uses the Windows App Packager (`MakeAppx.exe`) to create a single-file AppX package from those files on disk. Finally, the tool can be used to create a trusted certificate on your computer to sign the new AppX pacakge. With the signed AppX package, the CLI can also automatically install the package on your machine.
|
||||
Once the expanded AppX files are created, the tool uses the Windows App Packager
|
||||
(`MakeAppx.exe`) to create a single-file AppX package from those files on disk.
|
||||
Finally, the tool can be used to create a trusted certificate on your computer
|
||||
to sign the new AppX pacakge. With the signed AppX package, the CLI can also
|
||||
automatically install the package on your machine.
|
||||
|
||||
## Using the AppX Package
|
||||
|
||||
Since the Windows Anniversary Update (codenamed Windows Redstone) has not been released to consumers yet, you won't be able to release your app to the Windows Store until later this year - but you can already use the `Add-AppxPackage` [PowerShell Cmdlet to install it on machines](https://technet.microsoft.com/en-us/library/hh856048.aspx) in developer or enterprise environments.
|
||||
Since the Windows Anniversary Update (codenamed Windows Redstone) has not been
|
||||
released to consumers yet, you won't be able to release your app to the Windows
|
||||
Store until later this year - but you can already use the `Add-AppxPackage`
|
||||
[PowerShell Cmdlet to install it on machines](https://technet.microsoft.com/en-us/library/hh856048.aspx)
|
||||
in developer or enterprise environments.
|
||||
|
||||
Another important limitation is that the compiled AppX package still contains a win32 executable - and will therefore not run on Xbox, HoloLens, or Phones.
|
||||
Another important limitation is that the compiled AppX package still contains a
|
||||
win32 executable - and will therefore not run on Xbox, HoloLens, or Phones.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue