From ae65316a46679bda027c0230ae43df391d96201f Mon Sep 17 00:00:00 2001 From: Atul R Date: Fri, 2 Aug 2019 00:12:00 +0200 Subject: [PATCH] Adds more documentation --- docs/README.md | 16 +++++- docs/api/FlexLayout.md | 0 docs/api/NodeLayout.md | 0 docs/api/NodeWidget.md | 0 docs/api/QMainWindow.md | 57 ++++++++++++++++++ docs/api/QWidget.md | 35 ++++++++++++ docs/api/process.md | 21 +++++++ docs/api/synopsis.md | 70 +++++++++++++++++++++++ docs/faq.md | 62 ++++++++++++++++++++ docs/tutorial/about.md | 2 + docs/tutorial/application-architecture.md | 2 +- 11 files changed, 262 insertions(+), 3 deletions(-) create mode 100644 docs/api/FlexLayout.md create mode 100644 docs/api/NodeLayout.md create mode 100644 docs/api/NodeWidget.md create mode 100644 docs/api/QMainWindow.md create mode 100644 docs/api/QWidget.md create mode 100644 docs/api/process.md create mode 100644 docs/api/synopsis.md create mode 100644 docs/faq.md diff --git a/docs/README.md b/docs/README.md index 3d57dae0f..39681bdd0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,7 @@ # Guides and Tutorials - [About NodeGui](tutorial/about.md) +- [FAQ](faq.md) - [Setting up the Development Environment](tutorial/development-environment.md) - [Setting up macOS](tutorial/development-environment.md#setting-up-macos) - [Setting up Windows](tutorial/development-environment.md#setting-up-windows) @@ -18,16 +19,27 @@ - [Testing and Debugging](tutorial/debugging-app.md) - [Debugging Qode/NodeGui Process](tutorial/debugging-qode-process.md) - [Debugging a NodeGui app with Visual Studio Code](tutorial/debugging-app-vscode.md) - // BOOK MARK - TODO AFTER THIS - [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) - // Need to finish till here - [Getting Support](tutorial/support.md) +## API References + +- [Synopsis](api/synopsis.md) +- [Process Object](api/process.md) + +### Modules from NodeGui: + +- [QMainWindow (Window)](api/QMainWindow.md) +- [QWidget (View)](api/QWidget.md) +- [NodeWidget](api/NodeWidget.md) +- [NodeLayout](api/NodeLayout.md) +- [FlexLayout](api/FlexLayout.md) + ## Development See [development/README.md](development/README.md) diff --git a/docs/api/FlexLayout.md b/docs/api/FlexLayout.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/api/NodeLayout.md b/docs/api/NodeLayout.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/api/NodeWidget.md b/docs/api/NodeWidget.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/api/QMainWindow.md b/docs/api/QMainWindow.md new file mode 100644 index 000000000..c7b25f5a0 --- /dev/null +++ b/docs/api/QMainWindow.md @@ -0,0 +1,57 @@ +## Class: QMainWindow + +> Create and control windows. + +**This class is a JS wrapper around Qt's [QMainWindow class](https://doc.qt.io/qt-5/qmainwindow.html)** + +A `QMainWindow` provides a main application window. Every widget in NodeGui should be a child/nested child of QMainWindow. QMainWindow in NodeGui is also responsible for FlexLayout calculations of its children. + +**QMainWindow inherits from [NodeWidget](api/NodeWidget.md)** + +### Example + +```javascript +const { QMainWindow, QWidget } = require("@nodegui/nodegui"); + +const win = new QMainWindow(); + +const centralWidget = new QWidget(); +win.setCentralWidget(centralWidget); + +win.show(); + +global.win = win; // prevent's gc of win +``` + +QMainWindow needs to have a central widget set before other widgets can be added as a children/nested children. +Once a central widget is set you can add children/layout to the central widget. + +### Static Methods + +QMainWindow can access all the static methods defined in [NodeWidget](api/NodeWidget.md) + +### Instance Properties + +QMainWindow can access all the instance properties defined in [NodeWidget](api/NodeWidget.md) + +Additionally it also has the following instance properties: + +#### `win.layout` + +A `NodeLayout` representing current layout that is set on the window. If a centralWidget is set then the layout of central widget is returned. + +#### `win.centralWidget` + +A `NodeWidget` representing currently set central widget on the window. + +### Instance Methods + +QMainWindow can access all the instance methods defined in [NodeWidget](api/NodeWidget.md) + +Additionally it also has the following instance methods: + +#### `win.setCentralWidget(widget)` + +Sets the given widget to be the main window's central widget. + +- `widget` NodeWidget - Any widget that inherits from NodeWidget class. diff --git a/docs/api/QWidget.md b/docs/api/QWidget.md new file mode 100644 index 000000000..c3284846a --- /dev/null +++ b/docs/api/QWidget.md @@ -0,0 +1,35 @@ +## Class: QWidget + +> Create and control views. + +**This class is a JS wrapper around Qt's [QWidget class](https://doc.qt.io/qt-5/qwidget.html)** + +A `QWidget` can be used to encapsulate other widgets and provide structure. It functions similar to a `div` in the web world. + +**QWidget inherits from [NodeWidget](api/NodeWidget.md)** + +### Example + +```javascript +const { QWidget } = require("@nodegui/nodegui"); + +const view = new QWidget(); +view.setObjectName("container"); //Similar to setting `id` on the web +view.setLayout(new FlexLayout()); +``` + +### `new QWidget([parent])` + +- `parent` NodeWidget (optional). Any widget inheriting from NodeWidget can be passed as a parent. This will make this widget, the child of the parent widget. + +### Static Methods + +QWidget can access all the static methods defined in [NodeWidget](api/NodeWidget.md) + +### Instance Properties + +QWidget can access all the instance properties defined in [NodeWidget](api/NodeWidget.md) + +### Instance Methods + +QWidget can access all the instance methods defined in [NodeWidget](api/NodeWidget.md) diff --git a/docs/api/process.md b/docs/api/process.md new file mode 100644 index 000000000..57361451a --- /dev/null +++ b/docs/api/process.md @@ -0,0 +1,21 @@ +# process + +> Extensions to process object. + +Qode's `process` object is extended from the +[Node.js `process` object](https://nodejs.org/api/process.html). +It adds the following properties : + +## Properties + +### `process.versions.qode` _Readonly_ + +A `String` representing Qode's version string. Qode is a lightly modified version of NodeJs that allows running Qt and NodeJs under a single process. + +### `process.versions.qt(compiled)` _Readonly_ + +A `String` representing Qt version used when compile Qode binary. This can be useful to know which version of Qt is binary compatible with the version of Qode you are running. This is useful when running qode with a different version of Qt than what it was compiled with. + +### `process.versions.qt(runtime)` _Readonly_ + +A `String` representing Qt version of the Qt library loaded during runtime. This can be useful to know which version of Qt you are using at runtime as compared to the version of Qt used when Qode was compiled.This is possible since Qt is dynamically linked to Qode and you could replace the Qt dynamic libraries with any binary compatible library. Hence, this is useful when running qode with a different version of Qt than what it was compiled with. diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md new file mode 100644 index 000000000..4438144aa --- /dev/null +++ b/docs/api/synopsis.md @@ -0,0 +1,70 @@ +# Synopsis + +> How to use Node.js and NodeGui's APIs. + +All of [Node.js's built-in modules](https://nodejs.org/api/) are available in +NodeGui and third-party node modules also fully supported as well (including +the [native modules](../tutorial/using-native-node-modules.md)). + +NodeGui also provides some extra built-in modules for developing native +desktop applications. + +The app script is like a normal Node.js script: + +```javascript +const { QMainWindow } = require("@nodegui/nodegui"); + +const win = new QMainWindow(); + +win.show(); + +global.win = win; // To prevent win from being garbage collected. +``` + +To run your app, read [Run your app](../tutorial/first-app.md#running-your-app). + +## Destructuring assignment + +You can use +[destructuring assignment][destructuring-assignment] to make it easier to use +built-in modules. + +```javascript +const { + QMainWindow, + QWidget, + QLabel, + FlexLayout +} = require("@nodegui/nodegui"); + +const win = new QMainWindow(); + +const centralWidget = new QWidget(); +centralWidget.setObjectName("myroot"); +const rootLayout = new FlexLayout(); +centralWidget.setLayout(rootLayout); + +const label = new QLabel(); +label.setObjectName("mylabel"); +label.setText("Hello World"); + +rootLayout.addWidget(label); +win.setCentralWidget(centralWidget); +win.setStyleSheet( + ` + #myroot { + background-color: #009688; + } + #mylabel { + font-size: 16px; + font-weight: bold; + } + ` +); +win.show(); + +global.win = win; +``` + +[gui]: https://en.wikipedia.org/wiki/Graphical_user_interface +[destructuring-assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..49fac6201 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,62 @@ +# NodeGui FAQ + +## Why am I having trouble installing Qode? + +When running `npm install @nodegui/qode`, some users occasionally encounter +installation errors. + +In almost all cases, these errors are the result of network problems and not +actual issues with the `@nodegui/qode` npm package. Errors like `ELIFECYCLE`, +`EAI_AGAIN`, `ECONNRESET`, and `ETIMEDOUT` are all indications of such +network problems. The best resolution is to try switching networks, or +wait a bit and try installing again. + +You can also attempt to download Qode directly from +[nodegui/qode/releases](https://github.com/nodegui/qode/releases) +if installing via `npm` is failing. + +## Javascript widgets are missing methods and properties as compared to QT widget? + +As you would have noticed, the list of methods and properties are less compared to what is present in the Qt's corresponding widget class. This is because we havent written wrappers for them yet. You can help add more methods by following the development guide for contributors. Overtime this gap would reduce. + +## When will Qode upgrade to latest Node.js / Qt version? + +When a new version of Node.js/Qt gets released, we usually wait for about a month +before upgrading the one in Qode. So we can avoid getting affected by bugs +introduced in new Node.js/Qt versions, which happens very often. + +## My app's window/widgets/tray disappeared after a few minutes. + +This happens when the variable which is used to store the window/tray gets +garbage collected. + +If you encounter this problem, the following articles may prove helpful: + +- [Memory Management][memory-management] +- [Variable Scope][variable-scope] + +If you want a quick fix, you can make the variables global by changing your +code from this: + +```javascript +const { QWidget } = require("@nodegui/nodegui"); + +const view = new QWidget(); +view.setObjectName("container"); +view.setLayout(new FlexLayout()); +``` + +to this: + +```javascript +const { QWidget } = require("@nodegui/nodegui"); + +const view = new QWidget(); +view.setObjectName("container"); +view.setLayout(new FlexLayout()); + +global.view = view; //prevent GC +``` + +[memory-management]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management +[variable-scope]: https://msdn.microsoft.com/library/bzt2dkta(v=vs.94).aspx diff --git a/docs/tutorial/about.md b/docs/tutorial/about.md index 473b6e924..e81e7786e 100644 --- a/docs/tutorial/about.md +++ b/docs/tutorial/about.md @@ -4,6 +4,8 @@ NodeGui began in 2019 as part of frustrations related to Electron and other chromium based cross platform Gui solutions. Electron is a great framework for building cross platform apps but suffers from performance and energy related issues due to heavy reliance on Chromium. NodeGui wants to incorporate everything that is good about Electron: The ease of development, freedom of styling, Native APIs, great documentation, etc. At the same time NodeGui aims to be memory and CPU efficient. +Also, NodeGui is built with Typescript which means you get autocomplete and strong typechecking support from the IDE even when used in a Javascript project. + Get started building with NodeGui in the [First NodeGui app](first-app.md). ### Updating Dependencies diff --git a/docs/tutorial/application-architecture.md b/docs/tutorial/application-architecture.md index eff6fc26d..4b03f4547 100644 --- a/docs/tutorial/application-architecture.md +++ b/docs/tutorial/application-architecture.md @@ -101,4 +101,4 @@ 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 +[native-node]: tutorial/using-native-node-modules.md