removes old docs
This commit is contained in:
Atul R
parent
ea046e7d7c
commit
90d927df0a
@ -1 +0,0 @@
|
||||
docs.nodegui.org
|
||||
@ -1,75 +0,0 @@
|
||||
# main doc
|
||||
|
||||
> Looking for React NodeGUI docs? [React NodeGUI docs](react/README.md)
|
||||
|
||||
# Guides and Tutorials
|
||||
|
||||
- [About NodeGui](tutorial/about.md)
|
||||
- [React NodeGUI](react/README.md)
|
||||
- [Examples](https://github.com/nodegui/nodegui/tree/master/examples)
|
||||
- [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)
|
||||
- [Setting up Linux](tutorial/development-environment.md#setting-up-linux)
|
||||
- [Choosing an Editor](tutorial/development-environment.md#a-good-editor)
|
||||
- [Creating your First App](tutorial/first-app.md)
|
||||
- [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)
|
||||
- [Application Architecture](tutorial/application-architecture.md)
|
||||
- [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)
|
||||
- [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)
|
||||
- [Distribution](http://github.com/nodegui/packer)
|
||||
- [Getting Support](tutorial/support.md)
|
||||
|
||||
## API References
|
||||
|
||||
- [Synopsis](api/synopsis.md)
|
||||
- [Process Object](api/process.md)
|
||||
|
||||
### Modules from NodeGui:
|
||||
|
||||
- [QApplication (Application)](api/QApplication.md)
|
||||
- [QMainWindow (Window)](api/QMainWindow.md)
|
||||
- [QWidget (View)](api/QWidget.md)
|
||||
- [QSpinBox ()](api/QSpinBox.md)
|
||||
- [QAbstractScrollArea ()](api/QAbstractScrollArea.md)
|
||||
- [QAbstractSlider ()](api/QAbstractSlider.md)
|
||||
- [QDial ()](api/QDial.md)
|
||||
- [QScrollArea ()](api/QScrollArea.md)
|
||||
- [QPlainTextEdit (TextEdit)](api/QPlainTextEdit.md)
|
||||
- [QLabel (Text/Image)](api/QLabel.md)
|
||||
- [QPushButton (Button)](api/QPushButton.md)
|
||||
- [QRadioButton (RadioButton)](api/QRadioButton.md)
|
||||
- [QCheckBox (CheckBox)](api/QCheckBox.md)
|
||||
- [QLineEdit (LineEdit)](api/QLineEdit.md)
|
||||
- [QProgressBar (ProgressBar)](api/QProgressBar.md)
|
||||
- [FlexLayout](api/FlexLayout.md)
|
||||
- [QPixmap](api/QPixmap.md)
|
||||
- [QIcon](api/QIcon.md)
|
||||
- [QCursor](api/QCursor.md)
|
||||
- [QClipboard](api/QClipboard.md)
|
||||
- [Qt Enums](api/QtEnums.md)
|
||||
|
||||
### Internal Modules
|
||||
|
||||
- [NodeWidget](api/NodeWidget.md)
|
||||
- [NodeLayout](api/NodeLayout.md)
|
||||
- [EventWidget](api/EventWidget.md)
|
||||
- [Component](api/Component.md)
|
||||
- [YogaWidget](api/YogaWidget.md)
|
||||
|
||||
## Usage
|
||||
|
||||
- [Events usage](todo)
|
||||
- [Yoga properties using stylesheet usage](todo)
|
||||
|
||||
## Development/Contributor's Guide
|
||||
|
||||
See [development](development/README.md)
|
||||
@ -1,11 +0,0 @@
|
||||
<div style="display: flex; align-items:center;justify-content:center;margin-left:-120px;">
|
||||
<img src="images/nodegui.svg" style="height:90px; margin-right:10px;" />
|
||||
<h1 style="display:inline;"> NodeGui / React NodeGUI </h1>
|
||||
</div>
|
||||
<p style="font-weight:300; font-size:1.5em; margin: 0;">An open source library for building cross-platform native desktop applications with JavaScript and CSS like styling.</p>
|
||||
<p style="font-weight:500; font-size:1em;">
|
||||
NodeGui is based on Qt5 and <strong><i>NOT</i></strong> chromium, hence it is memory and cpu efficient. <strong>React NodeGui</strong> is a React renderer for NodeGui.
|
||||
</p>
|
||||
<img src="images/demo.png" alt="demo" style="width: 100%;"/>
|
||||
|
||||
<a href="#/?id=main-doc"><p style="font-size: 1.3em;">↓</p></a>
|
||||
@ -1,48 +0,0 @@
|
||||
# Contributor's guide
|
||||
|
||||
This guide is for everyone who want's to contribute to the development of NodeGui.
|
||||
|
||||
Please make sure you have read the [User's guides](/) before reading this guide.
|
||||
|
||||
- [Setting up the NodeGui Contributor's Environment](development/setting-up.md)
|
||||
- [Setting up macOS](development/setting-up.md#macosx)
|
||||
- [Setting up Windows](development/setting-up.md#windows)
|
||||
- [Setting up Linux](development/setting-up.md#linux)
|
||||
- [Getting started](development/getting-started.md)
|
||||
- [Code Structure](development/getting-started.md#Code-Structure)
|
||||
- [Wrapping a widget: TLDR version](development/getting-started.md#Wrapping-a-widget)
|
||||
- [Learning Materials](development/getting-started.md#Learning-Materials)
|
||||
- [Styling](development/styling.md)
|
||||
- [Painting](development/styling.md#painting)
|
||||
- [Layout](development/styling.md#layout)
|
||||
- [Signal and Event Handling](development/signal_and_event_handling.md)
|
||||
- [Debugging](development/debugging.md)
|
||||
- [Common Errors](development/common_errors.md)
|
||||
- [Wrapping a Widget: Detailed](development/wrapping_widgets.md)
|
||||
- [Getting Support](tutorial/support.md)
|
||||
|
||||
|
||||
# Where to start or How can you help?
|
||||
|
||||
You can follow the contributors guide above to get a gist.
|
||||
|
||||
It is fairly straightforward to get started. I would start with a project of my own and start adding missing functionalities.
|
||||
|
||||
Or simply put I would recommend you start by adding an unexported method to an existing widget.
|
||||
|
||||
**For example:**
|
||||
|
||||
You could add the corresponding Qt method to QProgressbar
|
||||
https://doc.qt.io/qt-5/qprogressbar.html#textVisible-prop to get a grip on it.
|
||||
|
||||
This PR can be used as a guide
|
||||
|
||||
https://github.com/nodegui/nodegui/issues/36
|
||||
|
||||
https://github.com/nodegui/nodegui/pull/39
|
||||
|
||||
You can also take a look at few bugs or the issue board here to know what you can pick up if you are out of ideas.
|
||||
|
||||
https://github.com/nodegui/nodegui/projects/
|
||||
|
||||
https://github.com/nodegui/react-nodegui/projects/
|
||||
@ -1,7 +0,0 @@
|
||||
# Common errors
|
||||
|
||||
1. **Segmentation fault:** Segmentation fault occurs when you access a Pointer that is pointing to an invalid memory address. One major reason for this can be that JS garbage collector would have garbage collected the addon generated value and you try accessing it after a while. This is mostly the case if you see seg fault happening randomly after some time of startup.
|
||||
|
||||
2. **Widget not visible in Flex layout** Widget might have gotten zero height/width. This can occur if yoga was not able to get the default height/width of the widget. Make sure you have implemented
|
||||
`YGNodeSetMeasureFunc(this->instance->getFlexNode(), &extrautils::measureQtWidget);`
|
||||
if its a leaf node widget(doesnt contain any children).
|
||||
@ -1,11 +0,0 @@
|
||||
# debugging
|
||||
|
||||
## Debugging JS
|
||||
|
||||
// TODO
|
||||
|
||||
## Debugging C++
|
||||
|
||||
https://medium.com/@atulanand94/debugging-nodejs-c-addons-using-vs-code-27e9940fc3ad
|
||||
|
||||
https://medium.com/cameron-nokes/how-to-debug-native-node-addons-in-mac-osx-66f69f81afcb
|
||||
@ -1,113 +0,0 @@
|
||||
## Getting started
|
||||
|
||||
This library aims to be a nodejs addon which can export Qt Widgets to the Javascript world. By doing so one can develop fully fledged cross platform native GUI applications using only Javascript.
|
||||
|
||||
The library depends on `qode` which is a lightly modified version of NodeJS. The slight modification was needed to make it work with this addon. In essense, we will do `qode your_file.js` instead of `node your_file.js`.
|
||||
|
||||
Qode is inspired by this post by [Cheng Zhao](https://github.com/zcbenz): https://electronjs.org/blog/electron-internals-node-integration
|
||||
|
||||
This library does not modify Qt in any way and only use it as it is. This library also dynamically links to Qt. So it needs Qt libs to be installed in your system to work (This is done to keep in compliance with open source LGPL license of Qt). We can think of exporting the required libs later.
|
||||
|
||||
## Code Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── binding.gyp
|
||||
├── config
|
||||
├── demo.ts
|
||||
├── package.json
|
||||
├── src
|
||||
│ ├── cpp <-- C++ source code
|
||||
│ └── lib <-- Typescript source code
|
||||
├── tsconfig.json
|
||||
└── yarn.lock
|
||||
```
|
||||
|
||||
The main folder is `src`. It contains
|
||||
|
||||
- `cpp` : This folder contains all the C++ source code. Basically all the wrapper code using NAPI to export Qt Widgets and other helper functions to Javascript.
|
||||
- `lib` : This folder contains all the Typescript code of the library. This is used to add additonal helper methods and types to exported addon.
|
||||
|
||||
**Detailed version:**
|
||||
|
||||
```
|
||||
.
|
||||
├── binding.gyp
|
||||
├── config
|
||||
│ ├── application.gypi
|
||||
│ ├── common.gypi
|
||||
│ └── yoga.gypi
|
||||
├── demo.ts
|
||||
├── package.json
|
||||
├── src
|
||||
│ ├── cpp
|
||||
│ │ ├── Extras
|
||||
│ │ ├── QtGui <------ All exported classes found inside Qts Gui dynamic library
|
||||
│ │ ├── QtWidgets <------ All exported classes found inside Qts Widgets dynamic library
|
||||
│ │ ├── core
|
||||
│ │ └── main.cpp
|
||||
│ └── lib
|
||||
│ ├── QtGui
|
||||
│ ├── QtWidgets
|
||||
│ └── core
|
||||
├── tsconfig.json
|
||||
└── yarn.lock
|
||||
|
||||
```
|
||||
|
||||
First step to seeing how everything works is to take a look at `demo.ts` file. This file is basically like a Kitchen application showcasing all the exported widgets currently with the library.
|
||||
|
||||
Make sure you have read how to write native NodeJS Addons blog first. https://medium.com/@atulanand94/beginners-guide-to-writing-nodejs-addons-using-c-and-n-api-node-addon-api-9b3b718a9a7f
|
||||
|
||||
Once you have done that check out `src/cpp/main.cpp` and `config/application.gypi` to see the list of exported C++ classes.
|
||||
|
||||
Then maybe you can take a look at `src/cpp/QtWidgets/QLabel/qlabel_wrap.h`. This will show you how to wrap a simple Qt Widget.
|
||||
Check the corresponding JS file for the addon here `src/lib/QtWidgets/QLabel/index.ts`.
|
||||
|
||||
## Wrapping a widget
|
||||
|
||||
Create wrappers for each and every Qt class that you will use with N-API (using node-addon-api since it is c++) and export it onto JS side.
|
||||
|
||||
Taking the example of QLabel, if you look inside the directory `src/cpp/QtWidgets/QLabel`, you should see:
|
||||
|
||||
```
|
||||
├── QLabel
|
||||
│ ├── nlabel.cpp
|
||||
│ ├── nlabel.h <---- Extended QLabel
|
||||
│ ├── nlabel_moc.cpp <--- Autogenerated file by qt moc.
|
||||
│ ├── qlabel_wrap.cpp
|
||||
│ └── qlabel_wrap.h <--- Wrapper file
|
||||
```
|
||||
|
||||
The idea is :
|
||||
|
||||
1. We will first extend QLabel class to form NLabel. NLabel is basically QLabel with some extra methods and variables. More on it below.
|
||||
2. Then we will use NLabel and wrap it using NAPI and export it to JS side. This is what qlabel_wrap does.
|
||||
|
||||
**NLabel**: Since NLabel has inherited from QLabel we can treat is as QLabel with extra methods and properties. Primary reason to extend QLabel to create NLabel is to add support for Event listeners and CSS styling using Flex.
|
||||
So if you take a look at NLabel you will see, it inherits from QLabel and NodeWidget. NodeWidget inturn inherits from YogaWidget and EventWidget. Event widget adds event handling support. YogaWidget is a class that contains the magic that enables a regular Qt Widget to have Yoga node. A Yoga node is an instance used by yoga library to calculate a widgets position on the screen. Yoga is a library that will layout the widget on the screen. To do so we will specify the flex properties like alignitems, justify content, margin, paddings etc on the Yoga node of the widget. Apart from adding yoga node, YogaWidget adds support for specifying those yoga properties via Qt's stylesheet. (This is done by using Q_PROPERTY). To make this work we need to use something called as Q_OBJECT inside the class which is a C++ macro. Q_OBJECT will be expanded to relevant code by the compiler. In Qt whenever we add Q_OBJECT to a header file, we need to use a pre compiler called Qt MOC (Meta Object Compiler). The way we use it is
|
||||
|
||||
```
|
||||
moc headername.h -o headername_moc.cpp --include <any_include_file_which_contains_macro> // example : ../../core/YogaWidget/yogawidget.h
|
||||
```
|
||||
|
||||
So for nlabel I would run it as:
|
||||
|
||||
```
|
||||
moc nlabel.h -o nlabel_moc.cpp --include ../../core/YogaWidget/yogawidget.h
|
||||
```
|
||||
|
||||
This will run moc on `headername.h` and generate `headername_moc.cpp`. We will include `headername_moc.cpp` in `config/moc.gypi`. If you dont do this. Then it will give a symbol not found error.
|
||||
|
||||
I hope QLabel's example is enough for now. For more examples and inspirations we can take a look at other wrapped widgets.
|
||||
|
||||
## Learning Materials
|
||||
|
||||
1. Beginners guide to NodeJS Addon - https://medium.com/@atulanand94/beginners-guide-to-writing-nodejs-addons-using-c-and-n-api-node-addon-api-9b3b718a9a7f
|
||||
2. First read this: N-API in nodejs docs
|
||||
3. https://www.youtube.com/watch?v=-Oniup60Afs&feature=youtu.be
|
||||
4. See samples at https://github.com/nodejs/abi-stable-node-addon-examples/
|
||||
4.1. You can see the readme of https://github.com/nodejs/node-addon-api.git/
|
||||
5. See node-qt implementation. It is implemented in Nan (explained in video).
|
||||
6. Now try to match the implementation in node-qt and convert to N-API using examples from samples.
|
||||
7. Implementations not in node-qt need to be done with effort.
|
||||
@ -1,55 +0,0 @@
|
||||
# Setup project for development
|
||||
|
||||
## Development setup and getting started
|
||||
|
||||
Make sure you follow the setup guide of [Qode][qode_setup] so that you have a build environment ready for Qode.
|
||||
|
||||
### MacOSX:
|
||||
|
||||
**Requirements**
|
||||
|
||||
1. Node version: > 11
|
||||
2. CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
3. Make, GCC v7
|
||||
4. Qt (_Optional_): Make sure you followed the setup instructions from [Qode][qode_setup]
|
||||
|
||||
### Windows:
|
||||
|
||||
**Requirements**
|
||||
|
||||
1. Node version: > 11
|
||||
2. CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
3. Visual Studio Community 2017
|
||||
4. Powershell
|
||||
5. Qt (_Optional_): Make sure you followed the setup instructions from [Qode][qode_setup]
|
||||
|
||||
### Linux:
|
||||
|
||||
Supported versions: Ubuntu 17.10 and up
|
||||
|
||||
**Requirements**
|
||||
|
||||
1. Node version: > 11
|
||||
2. CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
3. Make, GCC v7, pkg-config
|
||||
4. Qt (_Optional_): Make sure you followed the setup instructions from [Qode][qode_setup]
|
||||
|
||||
On Ubuntu: `$ sudo apt-get install pkg-config build-essentials` should install everything except Qt5.
|
||||
|
||||
Note: If you are using your own version of Qt make sure to
|
||||
|
||||
`export PKG_CONFIG_PATH="<path to qt installation>/5.13.0/gcc_64/lib/pkgconfig"`
|
||||
|
||||
### Common:
|
||||
|
||||
1. Once you have setup the platform specific stuff as mentioned above, follow these:
|
||||
2. `git clone` this repo.
|
||||
3. `yarn install`
|
||||
4. `yarn build:addon`
|
||||
5. `yarn dev`
|
||||
|
||||
If you want to run with your own version of Qt make sure to pass qt_home_dir variable when building addon.
|
||||
|
||||
`npm run rebuild:addon [--qt_home_dir=/path/to/qt]`
|
||||
|
||||
[qode_setup]: https://github.com/nodegui/qode
|
||||
@ -1,150 +0,0 @@
|
||||
# Event handling
|
||||
|
||||
In Qt you can respond to an external event like a key press via event handling. Events always are processed by the event loop. Alongside events Qt also has a concept of Signals/Slots. Signals and slots are used to primarily communicate between widgets (more precisely QObjects). So the most common way of interacting between Qt Widgets is done through signals/slots. (More details here: https://doc.qt.io/qt-5/signalsandslots.html). Hence we would be implementing support for both events and signals.
|
||||
|
||||
**Technicals:**
|
||||
|
||||
> An event is a message encapsulated in a class (QEvent) which is processed in an event loop and dispatched to a recipient that can either accept the message or pass it along to others to process. They are usually created in response to external system events like mouse clicks.
|
||||
> Signals and Slots are a convenient way for QObjects to communicate with one another and are more similar to callback functions. In most circumstances, when a "signal" is emitted, any slot function connected to it is called directly. The exception is when signals and slots cross thread boundaries. In this case, the signal will essentially be converted into an event.
|
||||
|
||||
# Implementing Signal handling
|
||||
|
||||
In Qt signals and slots are used to communicate between different qt widgets. So they can be used to implement things like
|
||||
onClick, onHover etc.
|
||||
|
||||
The way Qt Signals work is explained here:
|
||||
|
||||
https://doc.qt.io/qt-5/signalsandslots.html
|
||||
|
||||
The way you use them in Qt for a PushButton is explained here:
|
||||
https://wiki.qt.io/How_to_Use_QPushButton#Signals
|
||||
|
||||
# Adding signal/event handling support to a NodeWidget
|
||||
|
||||
We will take the example of PushButton
|
||||
|
||||
**Javascript**
|
||||
|
||||
Steps:
|
||||
|
||||
The widget should inherit from `NodeWidget`. NodeWidget inherits from EventWidget internally. EventWidget constructor needs native object while initialising. So arrange your code such that native object gets initialised before calling `super(native)`.
|
||||
|
||||
EventWidget adds `addEventListener` method to the widget which can be called
|
||||
like this:
|
||||
|
||||
```js
|
||||
button.addEventListener("clicked", () => {
|
||||
console.log("clicked");
|
||||
});
|
||||
```
|
||||
|
||||
To help the user know what all signals/events are supported, export an enum like `QPushButtonEvents` as shown below.
|
||||
|
||||
So the user can then use it as below:
|
||||
|
||||
```js
|
||||
button.addEventListener(QPushButtonEvents.clicked, () => {
|
||||
console.log("clicked");
|
||||
});
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
import addon from "../../core/addon";
|
||||
import { NodeWidget } from "../../QtGui/QWidget";
|
||||
import { BaseWidgetEvents } from "../../core/EventWidget";
|
||||
|
||||
export const QPushButtonEvents = Object.freeze({
|
||||
...BaseWidgetEvents,
|
||||
clicked: "clicked",
|
||||
pressed: "pressed",
|
||||
released: "released",
|
||||
toggled: "toggled"
|
||||
});
|
||||
|
||||
export class QPushButton extends NodeWidget {
|
||||
native: NativeElement;
|
||||
constructor(parent?: NodeWidget) {
|
||||
let native;
|
||||
if (parent) {
|
||||
native = new addon.QPushButton(parent.native);
|
||||
} else {
|
||||
native = new addon.QPushButton();
|
||||
}
|
||||
super(native);
|
||||
this.parent = parent;
|
||||
this.native = native;
|
||||
// bind member functions
|
||||
this.setText.bind(this);
|
||||
}
|
||||
|
||||
setText(text: string | number) {
|
||||
this.native.setText(`${text}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**C++**
|
||||
|
||||
Steps:
|
||||
|
||||
1. `NPushButton`
|
||||
|
||||
Inherit from both QPushButton and NodeWidget. Make sure you have added NODEWIDGET_IMPLEMENTATIONS macro. This adds a crucial method for events support. It will override `event(QEvent *)` method of QPushbutton so that nodejs can listen to the events of this widget. This makes sure we convert all the QEvent's of this widget to an event for the nodejs event emitter.
|
||||
|
||||
Also make sure to connect all the signals of the widgets to the event emitter instance from NodeJS. This way we kindof convert the signal to a simple nodejs event.
|
||||
|
||||
```cpp
|
||||
#pragma once
|
||||
|
||||
#include <QPushButton>
|
||||
#include "src/cpp/core/NodeWidget/nodewidget.h"
|
||||
#include "napi.h"
|
||||
|
||||
class NPushButton: public QPushButton, public NodeWidget
|
||||
{
|
||||
NODEWIDGET_IMPLEMENTATIONS(QPushButton)
|
||||
public:
|
||||
using QPushButton::QPushButton; //inherit all constructors of QPushButton
|
||||
|
||||
// override this method and implement all signals here
|
||||
void connectWidgetSignalsToEventEmitter() {
|
||||
// Qt Connects: Implement all signal connects here
|
||||
QObject::connect(this, &QPushButton::clicked, [=](bool checked) {
|
||||
Napi::Env env = this->emitOnNode.Env();
|
||||
Napi::HandleScope scope(env);
|
||||
this->emitOnNode.Call({ Napi::String::New(env, "clicked"), Napi::Value::From(env, checked) });
|
||||
});
|
||||
QObject::connect(this, &QPushButton::released, [=]() {
|
||||
Napi::Env env = this->emitOnNode.Env();
|
||||
Napi::HandleScope scope(env);
|
||||
this->emitOnNode.Call({ Napi::String::New(env, "released") });
|
||||
});
|
||||
QObject::connect(this, &QPushButton::pressed, [=]() {
|
||||
Napi::Env env = this->emitOnNode.Env();
|
||||
Napi::HandleScope scope(env);
|
||||
this->emitOnNode.Call({ Napi::String::New(env, "pressed") });
|
||||
});
|
||||
QObject::connect(this, &QPushButton::toggled, [=](bool checked) {
|
||||
Napi::Env env = this->emitOnNode.Env();
|
||||
Napi::HandleScope scope(env);
|
||||
this->emitOnNode.Call({ Napi::String::New(env, "toggled"), Napi::Value::From(env, checked) });
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
**Additional**
|
||||
|
||||
Make sure `npushbutton.h` is added to `config/moc.json`.
|
||||
And run `npm run automoc` before running `npm run build:addon`
|
||||
|
||||
We need to run Qt's MOC (Meta Object Compiler) on the file whenever we use Q_OBJECT in a class or use QObject::connect. This is so that Qt can expand the macros and add necessary implementations to our class.
|
||||
|
||||
# How does it work ?
|
||||
|
||||
1. On JS side for each widget instance we create an instance of NodeJS's Event Emitter. This is done by the class `EventWidget` from which `NodeWidget` inherits
|
||||
2. We send this event emiiter's `emit` function to the C++ side by calling `initNodeEventEmitter` method and store a pointer to the event emitter's emit function using `emitOnNode`. initNodeEventEmitter function is added by a macro from EventWidget (c++). You can find the initNodeEventEmitter method with the event widget macros.
|
||||
3. We setup Qt's connect method for all the signals that we want to listen to and call the emitOnNode (which is actually emit from Event emitter) whenever a signal arrives. This is done manually on every widget by overriding the method `connectWidgetSignalsToEventEmitter`. Check `npushbutton.h` for details. This takes care of all the signals of the widgets. Now to export all qt events of the widget, we had overriden the widgets `event(Event*)` method to listen to events received by the widget and send it to the event emitter. This is done inside the EVENTWIDGET_IMPLEMENTATIONS macro
|
||||
@ -1,100 +0,0 @@
|
||||
# How styling works?
|
||||
|
||||
There are two parts to styling.
|
||||
|
||||
1. Layout
|
||||
2. Painting : Colors, text color, etc
|
||||
|
||||
## Painting
|
||||
|
||||
The regular styles such as text color, font-size, font weight etc are achieved using Qt's stylesheet.
|
||||
We just call Qt's setStyleSheet method on the native widget and pass in the styles as a string.
|
||||
|
||||
This method is implemented as part of `QWIDGET_WRAPPED_METHODS_DECLARATION` in `qwidget_macro.h`.
|
||||
So all widgets using this macro will get the setStyleSheet method.
|
||||
|
||||
## Layout
|
||||
|
||||
Layouting is basically positioning widgets on the screen. It takes into account everything from margins, paddings, positions etc. Our main focus will be Flex layouting. For flex layout we are using yoga library from facebook. This is the same library used by React Native. Before looking at flaxlayout in this libarary I recommend browsing Yoga's C API doc here: `deps/yoga/doc.md`
|
||||
|
||||
In case `nodegui`. I have implemented a custom Qt layout by extending `QLayout`, hence Qt is able to take over automagically when window is resized or any other layouting event occurs.
|
||||
You can find the implementation at `src/cpp/core/FlexLayout/flexlayout.h`.
|
||||
|
||||
The c++ api provided by this custom layout looks like this:
|
||||
|
||||
```cpp
|
||||
// FlexLayout is a custom Layout built for QT. This layout will be used to layout qt widgets using facebook's yoga library.
|
||||
// Thus giving ability to layout Qt Widgets using Flexbox.
|
||||
// Usage:
|
||||
QWidget *container = new QWidget();
|
||||
YGNodeRef root = YGNodeNew();
|
||||
YGNodeRef child1 = YGNodeNew();
|
||||
YGNodeRef child2 = YGNodeNew();
|
||||
FlexLayout * flayout = new FlexLayout(container,root);
|
||||
// or FlexLayout * flayout = new FlexLayout(container);
|
||||
// or FlexLayout *flayout = new FlexLayout();
|
||||
|
||||
flayout->addWidget(btn1, child1);
|
||||
flayout->addWidget(btn2, child2);
|
||||
|
||||
```
|
||||
|
||||
This layout is exported to Javascript side via `src/cpp/core/FlexLayout/flexlayout_wrap.h`
|
||||
|
||||
The JS Api looks like this:
|
||||
|
||||
```js
|
||||
const view = new QWidget(rootView);
|
||||
|
||||
const flayout = new FlexLayout(); // Create layout
|
||||
flayout.setFlexNode(view.getFlexNode()); // Set widget's flex as layout's flex node.
|
||||
|
||||
view.setLayout(flayout); // set layout as view's layout
|
||||
|
||||
const label = new QLabel(view);
|
||||
label.setText("Hello12321");
|
||||
|
||||
const label2 = new QLabel(view);
|
||||
label2.setText("SECOND LABEL");
|
||||
|
||||
flayout.addWidget(label2, label2.getFlexNode()); // Add child to layout
|
||||
flayout.addWidget(label, label.getFlexNode()); // Add child to layout
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
1. Every widget that wants to use flex layout should extend from `flexItem` found at `src/cpp/core/FlexLayout/flexitem.h`.
|
||||
For example, see `nlabel.h` at `src/cpp/QtWidgets/QLabel/nlabel.h`
|
||||
|
||||
NLabel inherits from `NodeWidget` which inherits from `YogaWidget` which inturn inherits from `FlexItem`
|
||||
|
||||
- `FlexItem` adds a YogaNode to every widget.
|
||||
- `YogaWidget` adds Yoga specific q-properties to the widget, which is useful to assign yoga properties via qstylesheet. More on this below.
|
||||
- `NodeWidget` adds layout support via `YogaWidget` and event handling support via `EventWidget`
|
||||
|
||||
#### FlexItem
|
||||
|
||||
FlexItem : `src/cpp/core/FlexLayout/flexitem.h` add flexnode to each widget.
|
||||
FlexItem adds methods like getFlexNode.
|
||||
|
||||
#### YogaWidget
|
||||
|
||||
Qt StyleSheet allows you to specify style properties just like in web. You could specify font-size, margin, padding, etc. Qt StyleSheet also allows custom style properties via Qt's q-property system.
|
||||
|
||||
So in order to enable yoga based properties like alignItems, justifyContent, flex, etc via qt's stylesheet we
|
||||
declare and define q properties for each of those custom properties we want.
|
||||
This allows us to use something like:
|
||||
|
||||
```js
|
||||
view.setStyleSheet(`
|
||||
background-color:green;
|
||||
qproperty-flex: 1;
|
||||
qproperty-alignItems: 'center';
|
||||
`);
|
||||
```
|
||||
|
||||
Notice `qproperty-` prefix? These are the custom q-properties we defined in `YogaWidget.h`. We do not need to prefix `qproperty-` if a stylehsheet string is passed through `StyleSheet.create()`. StyleSheet.create has an autoprefixer which will do the right thing.
|
||||
|
||||
#### NodeWidget
|
||||
|
||||
Every widget we implement should inherit from NodeWidget. This helps us add all the properties we want in the widgets via a single class. NodeWidget is the class that contains properties and methods shared by all widgets. This class allows us to add features to all widgets easily.
|
||||
@ -1,3 +0,0 @@
|
||||
# Exporting a new method from a widget
|
||||
|
||||
# Exporting a new widget from scratch
|
||||
62
docs/faq.md
62
docs/faq.md
@ -1,62 +0,0 @@
|
||||
# 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
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 130 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 5.2 KiB |
@ -1,71 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta
|
||||
name="google-site-verification"
|
||||
content="7vXKDSJel62EQdT69DCmRXqdh7Kf6GXU_cYms5iYVh8"
|
||||
/>
|
||||
<title>
|
||||
NodeGui - A cross platform library to build performant desktop apps with
|
||||
Javascript.
|
||||
</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
||||
<meta
|
||||
name="description"
|
||||
content="A cross platform library to build native desktop apps."
|
||||
/>
|
||||
<meta
|
||||
name="viewport"
|
||||
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
|
||||
/>
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"
|
||||
/>
|
||||
|
||||
<style>
|
||||
:root {
|
||||
--heading-margin: 0;
|
||||
--cover-heading-color: hsl(204, 90%, 45%);
|
||||
--heading-h1-color: hsl(204, 90%, 45%);
|
||||
--heading-h2-color: hsl(204, 90%, 45%);
|
||||
--cover-background-color: white;
|
||||
}
|
||||
h1#main-doc {
|
||||
height: 0;
|
||||
opacity: 0;
|
||||
z-index: -2;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app">Loading documentation...</div>
|
||||
<script>
|
||||
window.$docsify = {
|
||||
name: "NodeGui",
|
||||
repo: "https://github.com/nodegui/nodegui",
|
||||
coverpage: ["/", "/react/"],
|
||||
themeable: {
|
||||
readyTransition: true, // default
|
||||
responsiveTables: true // default
|
||||
},
|
||||
search: {
|
||||
maxAge: 86400000, // Expiration time, the default one day
|
||||
paths: ["/", "/faq", "/development/", "/tutorial/about"],
|
||||
placeholder: "Type to search",
|
||||
noData: "No Results!"
|
||||
},
|
||||
disqus: "nodegui"
|
||||
};
|
||||
</script>
|
||||
<script
|
||||
src="//unpkg.com/docsify/lib/docsify.min.js"
|
||||
data-ga="UA-145065218-1"
|
||||
></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/disqus.min.js"></script>
|
||||
<script src="//unpkg.com/docsify/lib/plugins/ga.min.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,69 +0,0 @@
|
||||
# React NodeGUI
|
||||
|
||||
- [About React NodeGUI](react/about.md)
|
||||
- [Examples](https://github.com/nodegui/react-nodegui/tree/master/examples)
|
||||
- [Setting up the Development Environment](tutorial/development-environment.md)
|
||||
- [Creating your First App](react/first-app.md)
|
||||
- [Hello World](react/first-app.md#Hello-World)
|
||||
- [React NodeGUI Development in a Nutshell](react/first-app.md#react-nodegui-development-in-a-nutshell)
|
||||
- [Running Your App](react/first-app.md#running-your-app)
|
||||
// TODO from here
|
||||
- [Application Architecture](react/application-architecture.md)
|
||||
- [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)
|
||||
- [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)
|
||||
- [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)
|
||||
- [Getting Support](tutorial/support.md)
|
||||
|
||||
## API References
|
||||
|
||||
- [Synopsis](api/synopsis.md)
|
||||
- [Process Object](api/process.md)
|
||||
|
||||
### Modules from NodeGui:
|
||||
|
||||
- [QApplication (Application)](api/QApplication.md)
|
||||
- [QMainWindow (Window)](api/QMainWindow.md)
|
||||
- [QWidget (View)](api/QWidget.md)
|
||||
- [QSpinBox ()](api/QSpinBox.md)
|
||||
- [QAbstractScrollArea ()](api/QAbstractScrollArea.md)
|
||||
- [QAbstractSlider ()](api/QAbstractSlider.md)
|
||||
- [QDial ()](api/QDial.md)
|
||||
- [QScrollArea ()](api/QScrollArea.md)
|
||||
- [QPlainTextEdit (TextEdit)](api/QPlainTextEdit.md)
|
||||
- [QLabel (Text/Image)](api/QLabel.md)
|
||||
- [QPushButton (Button)](api/QPushButton.md)
|
||||
- [QRadioButton (RadioButton)](api/QRadioButton.md)
|
||||
- [QCheckBox (CheckBox)](api/QCheckBox.md)
|
||||
- [QLineEdit (LineEdit)](api/QLineEdit.md)
|
||||
- [QProgressBar (ProgressBar)](api/QProgressBar.md)
|
||||
- [FlexLayout](api/FlexLayout.md)
|
||||
- [QPixmap](api/QPixmap.md)
|
||||
- [QIcon](api/QIcon.md)
|
||||
- [Qt Enums](api/QtEnums.md)
|
||||
|
||||
### Internal Modules
|
||||
|
||||
- [NodeWidget](api/NodeWidget.md)
|
||||
- [NodeLayout](api/NodeLayout.md)
|
||||
- [EventWidget](api/EventWidget.md)
|
||||
- [Component](api/Component.md)
|
||||
- [YogaWidget](api/YogaWidget.md)
|
||||
|
||||
## Usage
|
||||
|
||||
- [Events usage](todo)
|
||||
- [Yoga properties using stylesheet usage](todo)
|
||||
|
||||
## Development/Contributor's Guide
|
||||
|
||||
See [development](development/README.md)
|
||||
@ -1,17 +0,0 @@
|
||||
# About React NodeGUI
|
||||
|
||||
[React NodeGUI](https://github.com/nodegui/react-nodegui) is an open source library for building cross-platform desktop applications with React and CSS like styling. React NodeGUI is a custom react renderer for [NodeGui](https://github.com/nodegui/nodegui). React NodeGUI combines the power and flexibility of React with ease of NodeJs and maturity of Qt5. With React NodeGUI you can build native desktop applications which are underneath Qt applications. This means you could in theory use all of Qt's Gui APIs in Javascript.
|
||||
|
||||
As React Native was an improvement over Cordova based applications in Mobile app development with web technologies, React NodeGUI aims to achieve the same with respect to Electron and other chromium based cross platform Gui solutions. React 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 it aims to be memory and CPU efficient.
|
||||
|
||||
Also, React NodeGUI (like 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 React NodeGUI in the [First React NodeGUI app](react/first-app.md).
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
As soon as a new version of NodeGui is released a corresponding version of React NodeGUI will be released simultaneously. This makes sure that both NodeGui and React NodeGUI releases go out in sync. NodeGui an React NodeGUI will be released as separate packages in order keep everything easily maintainable.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
[See core philosophy of NodeGui](tutorial/about?id=core-philosophy)
|
||||
@ -1,116 +0,0 @@
|
||||
# Writing Your First React NodeGUI App
|
||||
|
||||
React NodeGUI enables you to create desktop applications with JavaScript (React). React NodeGUI is a react renderer for NodeGui. This makes it extremely memory and CPU efficient as compared to other popular Javascript Desktop GUI solutions.
|
||||
|
||||
## Hello World
|
||||
|
||||
Clone and run the code in this tutorial by using the
|
||||
[`nodegui/react-nodegui-starter`][quick-start] repository.
|
||||
|
||||
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
|
||||
|
||||
```sh
|
||||
# Clone the repository
|
||||
$ git clone https://github.com/nodegui/react-nodegui-starter
|
||||
# Go into the repository
|
||||
$ cd react-nodegui-starter
|
||||
# Install dependencies
|
||||
$ npm install
|
||||
# Run the app
|
||||
$ npm start
|
||||
```
|
||||
|
||||
As far as development is concerned, an React NodeGUI application is essentially a
|
||||
Node.js application. The starting point is a `package.json` that is identical
|
||||
to that of a Node.js module. A most basic React NodeGUI app would have the following
|
||||
folder structure:
|
||||
|
||||
```text
|
||||
your-app/
|
||||
├── package.json
|
||||
├── index.js
|
||||
```
|
||||
|
||||
## React NodeGUI Development in a Nutshell
|
||||
|
||||
React NodeGUI apps are developed in JavaScript using the same principles and methods
|
||||
found in React Native development. React NodeGUI exposes native widgets in the form of React components. Also, since we are now not running inside a browser, there is no DOM. Hence browser based APIs are NOT available. But you do have access to complete NodeJs APIs along with some exported Qt Apis.All APIs related to React NodeGUI are found in `@nodegui/react-nodegui` module. Additionally you can also access APIs and features from NodeGui via
|
||||
the `@nodegui/nodegui` module. These can be required like any other Node.js module:
|
||||
|
||||
```javascript
|
||||
require("@nodegui/nodegui");
|
||||
require("@nodegui/react-nodegui");
|
||||
```
|
||||
|
||||
A simple `main.js`.
|
||||
|
||||
```javascript
|
||||
import { Renderer, View, Text, Button, Window } from "@nodegui/react-nodegui";
|
||||
import React, { useState } from "react";
|
||||
|
||||
const App = () => {
|
||||
const [time, setTime] = useState(new Date());
|
||||
return (
|
||||
<Window minSize={{ width: 500, height: 200 }} styleSheet={styleSheet}>
|
||||
<View id="container">
|
||||
<Button
|
||||
text="Update Time"
|
||||
on={{
|
||||
clicked: () => setTime(new Date())
|
||||
}}
|
||||
/>
|
||||
<Text id="result">{`${time}`}</Text>
|
||||
<Text id="result">{`Time in epoc: ${time.getTime()}`}</Text>
|
||||
</View>
|
||||
</Window>
|
||||
);
|
||||
};
|
||||
|
||||
const styleSheet = `
|
||||
#container {
|
||||
qproperty-flex: 1;
|
||||
qproperty-flexDirection: column;
|
||||
qproperty-minHeight: '100%';
|
||||
qproperty-alignItems: 'center';
|
||||
qproperty-justifyContent: 'center';
|
||||
}
|
||||
#opBtn {
|
||||
font-size: 20px;
|
||||
}
|
||||
#result {
|
||||
font-size: 12px;
|
||||
qproperty-flex: 1;
|
||||
color: cyan;
|
||||
}
|
||||
`;
|
||||
|
||||
Renderer.render(<App />, () => {});
|
||||
```
|
||||
|
||||
The `index.js` should create windows and handle all the system events your
|
||||
application might encounter.
|
||||
|
||||
## Running Your App
|
||||
|
||||
You can try your app by running `npm start` from your application's
|
||||
directory.
|
||||
|
||||
## Trying this Example
|
||||
|
||||
Clone and run the code in this tutorial by using the
|
||||
[`nodegui/react-nodegui-starter`][quick-start] repository.
|
||||
|
||||
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
|
||||
|
||||
```sh
|
||||
# Clone the repository
|
||||
$ git clone https://github.com/nodegui/react-nodegui-starter
|
||||
# Go into the repository
|
||||
$ cd react-nodegui-starter
|
||||
# Install dependencies
|
||||
$ npm install
|
||||
# Run the app
|
||||
$ npm start
|
||||
```
|
||||
|
||||
[quick-start]: https://github.com/nodegui/react-nodegui-starter
|
||||
@ -1,23 +0,0 @@
|
||||
# About NodeGui
|
||||
|
||||
[NodeGui](https://nodegui.github.io/nodegui) is an open source library for building cross-platform desktop applications with JavaScript and CSS like styling. NodeGui accomplishes this by combining the powers of [Node.js](https://nodejs.org) and [Qt](https://www.qt.io/). NodeGui apps can be packaged for Mac, Windows, and Linux.
|
||||
|
||||
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
|
||||
|
||||
When a new version of Node.js is released, NodeGui usually waits about a month before upgrading in order to bring in a more stable version.
|
||||
|
||||
NodeGui's version of Qt is usually updated within a month after a new stable version is released, depending on the effort involved in the upgrade.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
In order to evolve faster with every Node.Js release, NodeGui aims to patch NodeJs with as much minimum code as possible. This makes sure we support all Node features and keeps upgrade process simple.
|
||||
|
||||
NodeGui will always link dynamically to Qt in order to maintain LGPL lisence requirements for Open source projects.
|
||||
|
||||
NodeGui also encourages plugin/module based architecture, hence instead of bloating the entire core of NodeGui we prefer to build independent modules that can be managed and updated by the community thus keeping the end product binary size low and enabling faster upgrades.
|
||||
@ -1,104 +0,0 @@
|
||||
# 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 in order 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/nodegui/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]: tutorial/using-native-node-modules.md
|
||||
@ -1,38 +0,0 @@
|
||||
# Debugging the App in VSCode
|
||||
|
||||
### 1. Open an NodeGui project in VSCode.
|
||||
|
||||
```sh
|
||||
$ git clone git@github.com:nodegui/nodegui-starter.git
|
||||
$ code nodegui-starter
|
||||
```
|
||||
|
||||
### 2. Add a file `.vscode/launch.json` with the following configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Debug Qode Process",
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"cwd": "${workspaceRoot}",
|
||||
"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/qode",
|
||||
"windows": {
|
||||
"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/qode.exe"
|
||||
},
|
||||
"args": ["./dist/index.js"],
|
||||
"outputCapture": "std"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Tip**
|
||||
|
||||
You could also configure a preLaunchTask for building typescript before launching the debugger everytime.
|
||||
|
||||
### 3. Debugging
|
||||
|
||||
Set some breakpoints in `index.js`, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging). You should be able to hit the breakpoints.
|
||||
@ -1,54 +0,0 @@
|
||||
# Application Debugging
|
||||
|
||||
Whenever your NodeGui application is not behaving the way you wanted it to,
|
||||
an array of debugging tools might help you find coding errors, performance
|
||||
bottlenecks, or optimization opportunities.
|
||||
|
||||
Since a NodeGui application runs on Qode. And Qode is essentially Node.Js. We can consider a NodeGui app as a regular NodeJs app. Hence, you can use any debugging tool that you use with Node.Js
|
||||
One of the most popular way of debugging a Node.Js app is by making use of the [Chromium Developer Tools][node-inspect].
|
||||
|
||||
Google offers [excellent documentation for their developer tools][devtools].
|
||||
We recommend that you make yourself familiar with them - they are usually one
|
||||
of the most powerful utilities in any NodeGui Developer's tool belt.
|
||||
|
||||
# Debugging Qode process
|
||||
|
||||
To debug JavaScript that's executed in the Qode/Node process you will need to use an external debugger and
|
||||
launch Qode with the `--inspect` or `--inspect-brk` switch. Once you run it you can open up Chrome and visit `chrome://inspect` where you should see your app listed.
|
||||
|
||||
## Command Line Switches
|
||||
|
||||
Use one of the following command line switches to enable debugging of the process:
|
||||
|
||||
### `--inspect=[port]`
|
||||
|
||||
Qode will listen for V8 inspector protocol messages on the specified `port`,
|
||||
an external debugger will need to connect on this port. The default `port` is
|
||||
`9229`.
|
||||
|
||||
```shell
|
||||
qode --inspect=9229 your/app
|
||||
```
|
||||
|
||||
### `--inspect-brk=[port]`
|
||||
|
||||
Like `--inspect` but pauses execution on the first line of JavaScript.
|
||||
|
||||
**Note**
|
||||
|
||||
If you are using the official boilerplate `nodegui-starter`, then you can achieve this by running
|
||||
|
||||
```
|
||||
npm run debug
|
||||
```
|
||||
|
||||
## External Debuggers
|
||||
|
||||
You will need to use a debugger that supports the V8 inspector protocol.
|
||||
|
||||
- Connect Chrome by visiting `chrome://inspect` and selecting to inspect the
|
||||
launched NodeGui app present there.
|
||||
- [Debugging the NodeGui app in VSCode](tutorial/debugging-app-vscode.md)
|
||||
|
||||
[node-inspect]: https://nodejs.org/en/docs/inspector/
|
||||
[devtools]: https://developer.chrome.com/devtools
|
||||
@ -1,99 +0,0 @@
|
||||
# Developer Environment
|
||||
|
||||
NodeGui development is essentially Node.js development. To turn your operating
|
||||
system into an environment capable of building desktop apps with NodeGui,
|
||||
you will merely need Node.js, npm, a code editor of your choice, and a
|
||||
rudimentary understanding of your operating system's command line client.
|
||||
|
||||
## Setting up macOS
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- NodeGui supports macOS 10.10 (Yosemite) and up. NodeGui currently only supports 64bit OS.
|
||||
- CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
- Make, GCC v7
|
||||
- Currently supported Node.Js versions are 12.x and up.
|
||||
|
||||
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
|
||||
|
||||
Confirm that both `node` and `npm` are available by running:
|
||||
|
||||
```sh
|
||||
# This command should print the version of Node.js
|
||||
node -v
|
||||
|
||||
# This command should print the version of npm
|
||||
npm -v
|
||||
```
|
||||
|
||||
If both commands printed a version number, you are all set! Before you get
|
||||
started, you might want to install a [code editor](#a-good-editor) suited
|
||||
for JavaScript development.
|
||||
|
||||
## Setting up Windows
|
||||
|
||||
> NodeGui supports Windows 7 and later versions – attempting to develop NodeGui
|
||||
> applications on earlier versions of Windows might not work. NodeGui currently only supports 64bit OS.
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Visual studio 2017
|
||||
- CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
- Currently supported Node.Js versions are 12.x and up.
|
||||
|
||||
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
|
||||
|
||||
We strongly recommend Powershell as preferred terminal in Windows.
|
||||
|
||||
Confirm that both `node` and `npm` are available by running:
|
||||
|
||||
```powershell
|
||||
# This command should print the version of Node.js
|
||||
node -v
|
||||
|
||||
# This command should print the version of npm
|
||||
npm -v
|
||||
```
|
||||
|
||||
If both commands printed a version number, you are all set! Before you get
|
||||
started, you might want to install a [code editor](#a-good-editor) suited
|
||||
for JavaScript development.
|
||||
|
||||
## Setting up Linux
|
||||
|
||||
> NodeGui currently supports Ubuntu 17.10 and Debian 10 and up. Although other Linux distributions can also be easily supported. NodeGui currently only supports 64bit OS. NodeGui can technically support lower versions of Linux than mentioned here provided gcc >= v7 and libc version >= GLIBC_2.25
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Make, GCC v7
|
||||
- CMake 3.1 and up (Installation instructions can be found here: https://cmake.org/install/)
|
||||
- Currently supported Node.Js versions are 12.x and up.
|
||||
- On Ubuntu and Ubuntu-based distros it is advisable to run `sudo apt-get update`, followed by `sudo apt-get install pkg-config build-essential`
|
||||
|
||||
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
|
||||
|
||||
Confirm that both `node` and `npm` are available by running:
|
||||
|
||||
```sh
|
||||
# This command should print the version of Node.js
|
||||
node -v
|
||||
|
||||
# This command should print the version of npm
|
||||
npm -v
|
||||
```
|
||||
|
||||
If both commands printed a version number, you are all set! Before you get
|
||||
started, you might want to install a [code editor](#a-good-editor) suited
|
||||
for JavaScript development.
|
||||
|
||||
## A Good Editor
|
||||
|
||||
We might suggest two free popular editors:
|
||||
GitHub's [Atom][atom] and Microsoft's [Visual Studio Code][code]. Both of
|
||||
them have excellent JavaScript support.
|
||||
|
||||
If you are one of the many developers with a strong preference, know that
|
||||
virtually all code editors and IDEs these days support JavaScript.
|
||||
|
||||
[code]: https://code.visualstudio.com/
|
||||
[atom]: https://atom.io/
|
||||
@ -1,120 +0,0 @@
|
||||
# Writing Your First NodeGui App
|
||||
|
||||
NodeGui enables you to create desktop applications with pure JavaScript. You could see it
|
||||
as a lightly modified variant of the Node.js runtime that is focused on desktop applications
|
||||
instead of web servers.
|
||||
|
||||
NodeGui is also an efficient JavaScript binding to a cross platform graphical user interface
|
||||
(GUI) library `Qt`. Qt is one of the most mature and efficient library for building desktop applications.
|
||||
This enabled NodeGui to be extrememly memory and CPU efficient as compared to other popular Javascript Desktop GUI solutions. A hello world app built with NodeGui runs on less than 20Mb of memory.
|
||||
|
||||
## Hello World
|
||||
|
||||
Clone and run the code in this tutorial by using the
|
||||
[`nodegui/nodegui-starter`][quick-start] repository.
|
||||
|
||||
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
|
||||
|
||||
```sh
|
||||
# Clone the repository
|
||||
$ git clone https://github.com/nodegui/nodegui-starter
|
||||
# Go into the repository
|
||||
$ cd nodegui-starter
|
||||
# Install dependencies
|
||||
$ npm install
|
||||
# Run the app
|
||||
$ npm start
|
||||
```
|
||||
|
||||
As far as development is concerned, an NodeGui application is essentially a
|
||||
Node.js application. The starting point is a `package.json` that is identical
|
||||
to that of a Node.js module. A most basic NodeGui app would have the following
|
||||
folder structure:
|
||||
|
||||
```text
|
||||
your-app/
|
||||
├── package.json
|
||||
├── index.js
|
||||
```
|
||||
|
||||
## NodeGui Development in a Nutshell
|
||||
|
||||
NodeGui apps are developed in JavaScript using the same principles and methods
|
||||
found in Node.js development. All APIs and features found in NodeGui are
|
||||
accessible through the `@nodegui/nodegui` module, which can be required like any other
|
||||
Node.js module:
|
||||
|
||||
```javascript
|
||||
require("@nodegui/nodegui");
|
||||
```
|
||||
|
||||
The `@nodegui/nodegui` module exports features in namespaces. As examples, windows can be created
|
||||
using the `QMainWindow` class. A simple `main.js` file might open a window:
|
||||
|
||||
```javascript
|
||||
const {
|
||||
QMainWindow,
|
||||
QWidget,
|
||||
QLabel,
|
||||
FlexLayout,
|
||||
StyleSheet
|
||||
} = 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(
|
||||
StyleSheet.create(
|
||||
`
|
||||
#myroot {
|
||||
background-color: #009688;
|
||||
}
|
||||
#mylabel {
|
||||
font-size: 16px;
|
||||
font-weight: bold;
|
||||
}
|
||||
`
|
||||
)
|
||||
);
|
||||
win.show();
|
||||
|
||||
global.win = win; // To prevent win from being garbage collected.
|
||||
```
|
||||
|
||||
The `index.js` should create windows and handle all the system events your
|
||||
application might encounter.
|
||||
|
||||
## Running Your App
|
||||
|
||||
You can try your app by running `npm start` from your application's
|
||||
directory.
|
||||
|
||||
## Trying this Example
|
||||
|
||||
Clone and run the code in this tutorial by using the
|
||||
[`nodegui/nodegui-starter`][quick-start] repository.
|
||||
|
||||
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
|
||||
|
||||
```sh
|
||||
# Clone the repository
|
||||
$ git clone https://github.com/nodegui/nodegui-starter
|
||||
# Go into the repository
|
||||
$ cd nodegui-starter
|
||||
# Install dependencies
|
||||
$ npm install
|
||||
# Run the app
|
||||
$ npm start
|
||||
```
|
||||
|
||||
[quick-start]: https://github.com/nodegui/nodegui-starter
|
||||
@ -1,34 +0,0 @@
|
||||
# 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
|
||||
@ -1,52 +0,0 @@
|
||||
# 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