Cleanup readme and docs
This commit is contained in:
Atul R
parent
6a20e4dc09
commit
5bc040242b
@ -10,129 +10,25 @@
|
||||
- [Hello World](tutorial/first-app.md#Hello-World)
|
||||
- [NodeGui Development in a Nutshell](tutorial/first-app.md#NodeGui-development-in-a-nutshell)
|
||||
- [Running Your App](tutorial/first-app.md#running-your-app)
|
||||
|
||||
// BOOK MARK - TODO AFTER THIS
|
||||
|
||||
- [Application Architecture](tutorial/application-architecture.md)
|
||||
- [Main and Renderer Processes](tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
- [Qode](tutorial/application-architecture.md#qode)
|
||||
- [Using NodeGui's APIs](tutorial/application-architecture.md#using-NodeGui-apis)
|
||||
- [Using Node.js APIs](tutorial/application-architecture.md#using-nodejs-apis)
|
||||
- [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
|
||||
- Adding Features to Your App
|
||||
- [Notifications](tutorial/notifications.md)
|
||||
- [Recent Documents](tutorial/recent-documents.md)
|
||||
- [Application Progress](tutorial/progress-bar.md)
|
||||
- [Custom Dock Menu](tutorial/macos-dock.md)
|
||||
- [Custom Windows Taskbar](tutorial/windows-taskbar.md)
|
||||
- [Custom Linux Desktop Actions](tutorial/linux-desktop-actions.md)
|
||||
- [Keyboard Shortcuts](tutorial/keyboard-shortcuts.md)
|
||||
- [Offline/Online Detection](tutorial/online-offline-events.md)
|
||||
- [Represented File for macOS BrowserWindows](tutorial/represented-file.md)
|
||||
- [Native File Drag & Drop](tutorial/native-file-drag-drop.md)
|
||||
- [Offscreen Rendering](tutorial/offscreen-rendering.md)
|
||||
- [Supporting macOS Dark Mode](tutorial/mojave-dark-mode-guide.md)
|
||||
// BOOK MARK - TODO AFTER THIS
|
||||
- [Testing and Debugging](tutorial/application-debugging.md)
|
||||
- [Debugging the Main Process](tutorial/debugging-main-process.md)
|
||||
- [Debugging the Main Process with Visual Studio Code](tutorial/debugging-main-process-vscode.md)
|
||||
- [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
|
||||
- [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
|
||||
- [DevTools Extension](tutorial/devtools-extension.md)
|
||||
- [Automated Testing with a Custom Driver](tutorial/automated-testing-with-a-custom-driver.md)
|
||||
- [Distribution](tutorial/application-distribution.md)
|
||||
- [Supported Platforms](tutorial/support.md#supported-platforms)
|
||||
- [Code Signing](tutorial/code-signing.md)
|
||||
- [Mac App Store](tutorial/mac-app-store-submission-guide.md)
|
||||
- [Windows Store](tutorial/windows-store-guide.md)
|
||||
- [Snapcraft](tutorial/snapcraft.md)
|
||||
- [Security](tutorial/security.md)
|
||||
- [Reporting Security Issues](tutorial/security.md#reporting-security-issues)
|
||||
- [Chromium Security Issues and Upgrades](tutorial/security.md#chromium-security-issues-and-upgrades)
|
||||
- [NodeGui Security Warnings](tutorial/security.md#NodeGui-security-warnings)
|
||||
- [Security Checklist](tutorial/security.md#checklist-security-recommendations)
|
||||
- [Updates](tutorial/updates.md)
|
||||
- [Deploying an Update Server](tutorial/updates.md#deploying-an-update-server)
|
||||
- [Implementing Updates in Your App](tutorial/updates.md#implementing-updates-in-your-app)
|
||||
- [Applying Updates](tutorial/updates.md#applying-updates)
|
||||
// Need to finish till here
|
||||
- [Getting Support](tutorial/support.md)
|
||||
|
||||
## Detailed Tutorials
|
||||
|
||||
These individual tutorials expand on topics discussed in the guide above.
|
||||
|
||||
- [Installing NodeGui](tutorial/installation.md)
|
||||
- [Proxies](tutorial/installation.md#proxies)
|
||||
- [Custom Mirrors and Caches](tutorial/installation.md#custom-mirrors-and-caches)
|
||||
- [Troubleshooting](tutorial/installation.md#troubleshooting)
|
||||
- NodeGui Releases & Developer Feedback
|
||||
- [Versioning Policy](tutorial/NodeGui-versioning.md)
|
||||
- [Release Timelines](tutorial/NodeGui-timelines.md)
|
||||
- [App Feedback Program](tutorial/app-feedback-program.md)
|
||||
- [Packaging App Source Code with asar](tutorial/application-packaging.md)
|
||||
- [Generating asar Archives](tutorial/application-packaging.md#generating-asar-archives)
|
||||
- [Using asar Archives](tutorial/application-packaging.md#using-asar-archives)
|
||||
- [Limitations](tutorial/application-packaging.md#limitations-of-the-node-api)
|
||||
- [Adding Unpacked Files to asar Archives](tutorial/application-packaging.md#adding-unpacked-files-to-asar-archives)
|
||||
- [Testing Widevine CDM](tutorial/testing-widevine-cdm.md)
|
||||
- [Using Pepper Flash Plugin](tutorial/using-pepper-flash-plugin.md)
|
||||
|
||||
---
|
||||
|
||||
- [Glossary of Terms](glossary.md)
|
||||
|
||||
## API References
|
||||
|
||||
- [Synopsis](api/synopsis.md)
|
||||
- [Process Object](api/process.md)
|
||||
- [Supported Chrome Command Line Switches](api/chrome-command-line-switches.md)
|
||||
- [Environment Variables](api/environment-variables.md)
|
||||
- [Breaking API Changes](api/breaking-changes.md)
|
||||
|
||||
### Custom DOM Elements:
|
||||
|
||||
- [`File` Object](api/file-object.md)
|
||||
- [`<webview>` Tag](api/webview-tag.md)
|
||||
- [`window.open` Function](api/window-open.md)
|
||||
- [`BrowserWindowProxy` Object](api/browser-window-proxy.md)
|
||||
|
||||
### Modules for the Main Process:
|
||||
|
||||
- [app](api/app.md)
|
||||
- [autoUpdater](api/auto-updater.md)
|
||||
- [BrowserView](api/browser-view.md)
|
||||
- [BrowserWindow](api/browser-window.md)
|
||||
- [contentTracing](api/content-tracing.md)
|
||||
- [dialog](api/dialog.md)
|
||||
- [globalShortcut](api/global-shortcut.md)
|
||||
- [inAppPurchase](api/in-app-purchase.md)
|
||||
- [ipcMain](api/ipc-main.md)
|
||||
- [Menu](api/menu.md)
|
||||
- [MenuItem](api/menu-item.md)
|
||||
- [net](api/net.md)
|
||||
- [netLog](api/net-log.md)
|
||||
- [powerMonitor](api/power-monitor.md)
|
||||
- [powerSaveBlocker](api/power-save-blocker.md)
|
||||
- [protocol](api/protocol.md)
|
||||
- [screen](api/screen.md)
|
||||
- [session](api/session.md)
|
||||
- [systemPreferences](api/system-preferences.md)
|
||||
- [TouchBar](api/touch-bar.md)
|
||||
- [Tray](api/tray.md)
|
||||
- [webContents](api/web-contents.md)
|
||||
|
||||
### Modules for the Renderer Process (Web Page):
|
||||
|
||||
- [desktopCapturer](api/desktop-capturer.md)
|
||||
- [ipcRenderer](api/ipc-renderer.md)
|
||||
- [remote](api/remote.md)
|
||||
- [webFrame](api/web-frame.md)
|
||||
|
||||
### Modules for Both Processes:
|
||||
|
||||
- [clipboard](api/clipboard.md)
|
||||
- [crashReporter](api/crash-reporter.md)
|
||||
- [nativeImage](api/native-image.md)
|
||||
- [shell](api/shell.md)
|
||||
|
||||
## Development
|
||||
|
||||
See [development/README.md](development/README.md)
|
||||
|
||||
104
extras/docs/tutorial/application-architecture.md
Normal file
104
extras/docs/tutorial/application-architecture.md
Normal file
@ -0,0 +1,104 @@
|
||||
# NodeGui Application Architecture
|
||||
|
||||
Before we can dive into NodeGui's APIs, we need to discuss how NodeGui works internally. This would give a clear picture on why the APIs are the way they are.
|
||||
|
||||
## Qode
|
||||
|
||||
NodeGui uses Qt for creating Windows and other UI element. Hence it exports thin wrappers of native C++ widgets from Qt into Javascript world. Now, every Qt application needs to initialize an instance of `QApplication` before creating widgets. The way we do it in C++ Qt application is (dont worry if it doesnt make sense right now):
|
||||
|
||||
```cpp
|
||||
#include <QApplication>
|
||||
#include <QPushButton>
|
||||
|
||||
int main(int argc, char *argv[])
|
||||
{
|
||||
QApplication app(argc, argv); // Important
|
||||
|
||||
QPushButton hello("Hello world!");
|
||||
hello.resize(100, 30);
|
||||
hello.show();
|
||||
|
||||
return app.exec(); // Important
|
||||
}
|
||||
```
|
||||
|
||||
Like many Gui libraries Qt uses an event/message loop to handle events from widgets. Hence, when we call `app.exec()` Qt starts its message loop and blocks on that line. This is all good when there is only one message loop in the entire app. But since we want to use Qt with NodeJS and NodeJs has its own event loop, we cannot run both Qt and NodeJs on the same thread easily.
|
||||
|
||||
Then following questions arise:
|
||||
|
||||
- **What if we run Qt on a separate thread?** : No this is not possible since Qt has a requirement that it needs to run on the main thread.
|
||||
- **What if we run Node on a separate thread?** : This would mean we need to build a complex bridge between Node and Qt threads to make them communicate. A strict no no.
|
||||
|
||||
So inorder to make both NodeJs and Qt work together we need to find a way to merge these two event loop into one. This is achieved by a custom NodeJs binary we call as `Qode`.
|
||||
|
||||
Qode is a lightly modified fork of Node.js that merges Node's event loop with Qt's event loop. The idea of merging event loops is inspired by Electron and [other](https://github.com/yue) Gui libraries developed by [zcbenz (Cheng Zhao)](https://github.com/zcbenz). It has been detailed in a post here: [Electron internals](https://electronjs.org/blog/electron-internals-node-integration). Hence, we reused the logic from electron to achieve smooth integration between Qt and NodeJs.
|
||||
|
||||
The idea is to release a corresponding Qode binary for every NodeJs version that comes out after Node v12.6.
|
||||
The source code of Qode can be found [here](https://github.com/master-atul/qode).
|
||||
|
||||
_\*PS: Qode is a fork of [Yode](https://github.com/yue/yode)_
|
||||
|
||||
## Using NodeGui APIs
|
||||
|
||||
NodeGui offers a number of APIs that support the development of a desktop
|
||||
application. You'd access NodeGui's APIs by requiring its included module:
|
||||
|
||||
```javascript
|
||||
require("@nodegui/nodegui");
|
||||
```
|
||||
|
||||
A window in NodeGui is for instance created using the `QMainWindow`
|
||||
class.
|
||||
|
||||
```javascript
|
||||
const { QMainWindow } = require("@nodegui/nodegui");
|
||||
|
||||
const win = new QMainWindow();
|
||||
```
|
||||
|
||||
## Using Nodejs APIs
|
||||
|
||||
NodeGui exposes full access to Node.js. This has two important implications:
|
||||
|
||||
1. All APIs available in Node.js are available in NodeGui. Calling the
|
||||
following code from an NodeGui app works:
|
||||
|
||||
```javascript
|
||||
const fs = require("fs");
|
||||
|
||||
const root = fs.readdirSync("/");
|
||||
|
||||
// This will print all files at the root-level of the disk,
|
||||
// either '/' or 'C:\'.
|
||||
console.log(root);
|
||||
```
|
||||
|
||||
2. You can use Node.js modules in your application. Pick your favorite npm
|
||||
module. npm offers currently the world's biggest repository of open-source
|
||||
code – the ability to use well-maintained and tested code that used to be
|
||||
reserved for server applications is one of the key features of NodeGui.
|
||||
|
||||
As an example, to use the official AWS SDK in your application, you'd first
|
||||
install it as a dependency:
|
||||
|
||||
```sh
|
||||
npm install --save aws-sdk
|
||||
```
|
||||
|
||||
Then, in your NodeGui app, require and use the module as if you were
|
||||
building a Node.js application:
|
||||
|
||||
```javascript
|
||||
// A ready-to-use S3 Client
|
||||
const S3 = require("aws-sdk/clients/s3");
|
||||
```
|
||||
|
||||
There is one important caveat: Native Node.js modules (that is, modules that
|
||||
require compilation of native code before they can be used) will need to be
|
||||
compiled with Qode or a compatible Node version to be used with NodeGui.
|
||||
|
||||
The vast majority of Node.js modules are _not_ native. Only 400 out of the
|
||||
~650.000 modules are native. However, if you do need native modules, please
|
||||
consult [this guide on how to recompile them for NodeGui][native-node].
|
||||
|
||||
[native-node]: ./using-native-node-modules.md
|
||||
34
extras/docs/tutorial/support.md
Normal file
34
extras/docs/tutorial/support.md
Normal file
@ -0,0 +1,34 @@
|
||||
# NodeGui Support
|
||||
|
||||
## Finding Support
|
||||
|
||||
If you're looking for programming help or for answers to questions please file an issue on the NodeGui's Github project issues and we will try our best to answer and help out.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
Following platforms are supported by NodeGui:
|
||||
|
||||
### macOS
|
||||
|
||||
Only 64bit binaries are provided for macOS, and the minimum macOS version
|
||||
supported is macOS 10.10 (Yosemite).
|
||||
|
||||
### Windows
|
||||
|
||||
Windows 7 and later are supported, older operating systems are not supported
|
||||
(and might not work).
|
||||
|
||||
Only `x64` (`amd64`) binaries are provided for Windows at this point of time.
|
||||
|
||||
### Linux
|
||||
|
||||
The prebuilt `x64` (`amd64`) binaries of NodeGui are built on Ubuntu 12.04.
|
||||
|
||||
Whether the prebuilt binary can run on a distribution depends on whether the
|
||||
distribution includes the libraries that NodeGui is linked to on the building
|
||||
platform, so only Ubuntu 12.04 is guaranteed to work, but following platforms
|
||||
are also verified to be able to run the prebuilt binaries of NodeGui:
|
||||
|
||||
- Ubuntu 12.04 and newer
|
||||
- Fedora 21
|
||||
- Debian 8
|
||||
52
extras/docs/tutorial/using-native-node-modules.md
Normal file
52
extras/docs/tutorial/using-native-node-modules.md
Normal file
@ -0,0 +1,52 @@
|
||||
# Using Native Node Modules
|
||||
|
||||
Native Node modules are supported by NodeGui, but since NodeGui is very
|
||||
likely to use a different V8 version from the Node binary installed on your
|
||||
system, the modules you use will need to be recompiled for NodeGui's node/v8 version. Otherwise,
|
||||
you will get the following class of error when you try to run your app:
|
||||
|
||||
```sh
|
||||
Error: The module '/path/to/native/module.node'
|
||||
was compiled against a different Node.js version using
|
||||
NODE_MODULE_VERSION $XYZ. This version of Node.js requires
|
||||
NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
|
||||
the module (for instance, using `npm rebuild` or `npm install`).
|
||||
```
|
||||
|
||||
## How to install native modules
|
||||
|
||||
To compile native Node modules against a build of NodeGui that doesn't
|
||||
match a public release, instruct `npm` to use the version of Qode (NodeJs) you have bundled
|
||||
with your custom build.
|
||||
|
||||
```sh
|
||||
npm rebuild --nodedir=/path/to/nodegui/vendor/qode
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
qode /path/to/npm rebuild
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you installed a native module and found it was not working, you need to check
|
||||
the following things:
|
||||
|
||||
- When in doubt, rebuild native modules with qode first.
|
||||
- Make sure the native module is compatible with the target platform and
|
||||
architecture for your NodeGui app.
|
||||
- After you upgrade NodeGui, you usually need to rebuild the modules.
|
||||
|
||||
## Modules that rely on `node-pre-gyp`
|
||||
|
||||
The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node
|
||||
modules with prebuilt binaries, and many popular modules are using it.
|
||||
|
||||
Usually those modules work fine under NodeGui, but sometimes when NodeGui uses
|
||||
a newer version of V8 than Node and/or there are ABI changes, bad things may
|
||||
happen. So in general, it is recommended to always build native modules from
|
||||
source code.
|
||||
|
||||
[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
|
||||
Loading…
Reference in New Issue
Block a user