Adds new doc site (#124)
* Adds base template for new docs site * Adds Apis to docs * add some css from rn * Fix right side sidebar functionality * Basic docs * adds old docs * Cleans up unnecessary files * Chane links * Adds docusaurus v2 * Styling fixes * adds wip and new assets * adds code image * Add FAQ link * Adds analytics * adds cname * cleanup blogs
This commit is contained in:
Atul R
GitHub
@@ -0,0 +1,6 @@
|
||||
---
|
||||
sidebar_label: Custom NodeGui Plugin
|
||||
title: Custom NodeGui Plugin
|
||||
---
|
||||
|
||||
WIP
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
sidebar_label: Debugging in VSCode
|
||||
title: Debugging in VSCode
|
||||
---
|
||||
|
||||
- **Open a NodeGui project in VSCode.**
|
||||
|
||||
```sh
|
||||
$ git clone git@github.com:nodegui/nodegui-starter.git
|
||||
$ code nodegui-starter
|
||||
```
|
||||
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
sidebar_label: Debugging
|
||||
title: Debugging
|
||||
---
|
||||
|
||||
## 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](debugging-in-vscode.md)
|
||||
|
||||
[node-inspect]: https://nodejs.org/en/docs/inspector/
|
||||
[devtools]: https://developer.chrome.com/devtools
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
sidebar_label: Getting started
|
||||
title: Getting started
|
||||
---
|
||||
|
||||
NodeGui enables you to create desktop applications with 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.
|
||||
|
||||
## Developer environment
|
||||
|
||||
To turn your operating system into an environment capable of building desktop apps with NodeGui, you would need Node.js, npm,a code editor of your choice, and a rudimentary understanding of your operating system's command line client.
|
||||
|
||||
Along with these, there are a few operating system dependent instructions that are listed below.
|
||||
|
||||
### Setting up on 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 on 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 and up.
|
||||
- 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 on Linux
|
||||
|
||||
> NodeGui currently supports Ubuntu 16.04 and Debian 10 and up. Although other Linux distributions can also be easily supported. NodeGui currently only supports 64bit OS.
|
||||
|
||||
**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/
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
That's it!
|
||||
|
||||
Congratulations! You've successfully run and modified your first NodeGui app.
|
||||
|
||||
### Now what?
|
||||
|
||||
If you're curious to learn more about NodeGui, continue on to the [tutorial](tutorial.md).
|
||||
|
||||
[quick-start]: https://github.com/nodegui/nodegui-starter
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
sidebar_label: Handle Events
|
||||
title: Handle Events
|
||||
---
|
||||
|
||||
WIP
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
sidebar_label: Images
|
||||
title: Images
|
||||
---
|
||||
|
||||
WIP
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
sidebar_label: Layout
|
||||
title: Layout
|
||||
---
|
||||
|
||||
NodeGui uses a layout system to automatically arranging child widgets within a widget to ensure that they make good use of the available space.
|
||||
|
||||
## Fixed Dimensions
|
||||
|
||||
A widget's height and width determine its size on the screen. The simplest way to set the dimensions of a widget is by adding a fixed width and height to style. Setting dimensions this way is common for widgets that should always render at exactly the same size, regardless of screen dimensions.
|
||||
|
||||
```javascript
|
||||
|
||||
const { QMainWindow, QWidget } = require("@nodegui/nodegui");
|
||||
|
||||
const win = new QMainWindow();
|
||||
const view = new QWidget(win);
|
||||
|
||||
view.setInlineStyle("width:50px; height:30px; background-color: yellow;");
|
||||
|
||||
win.show();
|
||||
(global as any).win = win;
|
||||
|
||||
```
|
||||
|
||||
## Dynamic Layouts
|
||||
|
||||
Dynamic layouts automatically position and resize widgets when the amount of space available for them changes, ensuring that they are consistently arranged and that the user interface as a whole remains usable.
|
||||
|
||||
NodeGui currently supports the following layouts at the moment:
|
||||
|
||||
- FlexLayout
|
||||
- QGridLayout
|
||||
|
||||
_More layouts will be added as time goes on. You can also add layouts yourself by creating custom native plugins for NodeGui usng the [Custom Native Plugin API.](custom-nodegui-native-plugin.md)_
|
||||
|
||||
## FlexLayout
|
||||
|
||||
Use FlexLayout to have the children expand and shrink dynamically based on available space. Normally you will use `flex: 1`, which tells a widget to fill all available space, shared evenly amongst other widgets with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.
|
||||
|
||||
> A widget can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.
|
||||
|
||||
Flexbox is designed to provide a consistent layout on different screen sizes. You will normally use a combination of flexDirection, alignItems, and justifyContent to achieve the right layout.
|
||||
|
||||
### Example:
|
||||
|
||||
Lets say you want to build a UI that has a parent view which has two child widgets. One a label with text Hello and another a view with background color white. Now you want the label to occupy 1/3 of the available space while the white colored child view to occupy the remaining 2/3 space.
|
||||
|
||||
<img src="/img/docs/flex-layout-1.png" alt="flex layout example 1" style={{maxWidth: 700, width:'100%'}}/>
|
||||
|
||||
The code for that would look something like this:
|
||||
|
||||
```javascript
|
||||
let { QLabel, FlexLayout, QWidget, QMainWindow } = require("@nodegui/nodegui");
|
||||
|
||||
// Create a root view and assign a flex layout to it.
|
||||
const rootView = new QWidget();
|
||||
rootView.setLayout(new FlexLayout());
|
||||
rootView.setObjectName("rootView");
|
||||
|
||||
// Create two widgets - one label and one view
|
||||
const label = new QLabel();
|
||||
label.setText("Hello");
|
||||
label.setObjectName("label");
|
||||
|
||||
const view = new QWidget();
|
||||
view.setObjectName("view");
|
||||
|
||||
// Now tell rootView layout that the label and the other view are its children
|
||||
rootView.layout.addWidget(label);
|
||||
rootView.layout.addWidget(view);
|
||||
|
||||
// Tell FlexLayout how you want children of rootView to be poisitioned
|
||||
rootView.setStyleSheet(`
|
||||
#rootView{
|
||||
flex: 1;
|
||||
background-color: blue;
|
||||
}
|
||||
#label {
|
||||
flex: 1;
|
||||
color: white;
|
||||
background-color: green;
|
||||
}
|
||||
#view {
|
||||
flex: 3;
|
||||
background-color: white;
|
||||
}
|
||||
`);
|
||||
|
||||
const win = new QMainWindow();
|
||||
win.setCentralWidget(rootView);
|
||||
win.show();
|
||||
global.win = win;
|
||||
```
|
||||
|
||||
### TLDR
|
||||
|
||||
- First step is to set a layout on the parent widget. You can do this using the widget's `setLayout` method. Here we are using FlexLayout.
|
||||
|
||||
- For a layout to work you must let the layout know which widgets are the children and how to lay them on the available screen space within the parent widget. You do this using a layout's `addWidget` method. In the case of FlexLayout you will specify properties by setting flex properties on the parent and child widgets.
|
||||
|
||||
> To know more on how FlexBox layout works in depth you can visit: https://facebook.github.io/react-native/docs/0.60/flexbox.
|
||||
>
|
||||
> NodeGui uses the same library that React Native uses underneath for FlexBox ([Yoga](https://github.com/facebook/yoga)).
|
||||
|
||||
- You can specify layout properties via inline styles also.
|
||||
|
||||
## Conclusion
|
||||
|
||||
The primary layout in NodeGui is the Flexbox layout. Flexbox layout can be controlled via stylesheet just as in web. So both paint and layout properties are available at the same place.
|
||||
|
||||
NodeGui will also try to support other available layouts in Qt. But, If you need a special layout that Qt/NodeGui doesnt yet support you can always create a [native plugin for NodeGui](custom-nodegui-native-plugin.md) and use Qt's APIs to create one. In fact, Qt doesnt have a FlexLayout built in, FlexLayout is actually a custom Qt layout written with the help of Yoga library.
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
sidebar_label: Networking
|
||||
title: Networking
|
||||
---
|
||||
|
||||
WIP
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
sidebar_label: Architecture
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
By looking at how NodeGui works internally, we would get a clear picture on why the APIs are designed 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]: using-native-node-modules.md
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
sidebar_label: Scroll View
|
||||
title: Scroll View
|
||||
---
|
||||
|
||||
WIP
|
||||
@@ -0,0 +1,175 @@
|
||||
---
|
||||
sidebar_label: Styling
|
||||
title: Styling
|
||||
---
|
||||
|
||||
With NodeGui, you can style a widget to your needs. If you are familiar with CSS in the web world you would feel right at home. All widgets have a method `setInlineStyle` for setting inline styles for the respective widget. The style names and values usually match how CSS works on the web.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```js
|
||||
const { QLabel, QMainWindow } = require("@nodegui/nodegui");
|
||||
|
||||
const win = new QMainWindow();
|
||||
|
||||
const label = new QLabel(win);
|
||||
label.setText("Hello world");
|
||||
label.setInlineStyle("color: green; background-color: white;");
|
||||
|
||||
win.show();
|
||||
global.win = win;
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
NodeGui makes use of [Qt's stylesheet](https://doc.qt.io/qt-5/stylesheet-syntax.html) for styling. Qt Style Sheet terminology and syntactic rules are almost identical to those of HTML CSS. Additionally, NodeGui adds support for layout using flex properties like align-items, justify-content, etc. Flexbox layout support is added using [facebook's yoga library](https://github.com/facebook/yoga).
|
||||
|
||||
You would write your style properties in a string and pass it to the NodeGui widgets either via global styles or inline styles (similar to how it works in the web).
|
||||
|
||||
## Global styles
|
||||
|
||||
Lets take a look at an example:
|
||||
|
||||
```js
|
||||
const { QLabel, FlexLayout, QWidget } = require("@nodegui/nodegui");
|
||||
|
||||
const view = new QWidget();
|
||||
view.setObjectName("rootView");
|
||||
view.setLayout(new FlexLayout());
|
||||
|
||||
const label = new QLabel();
|
||||
label.setObjectName("helloLabel");
|
||||
label.setText("Hello");
|
||||
|
||||
const label2 = new QLabel();
|
||||
label2.setObjectName("worldLabel");
|
||||
label2.setText("World");
|
||||
|
||||
view.layout.addWidget(label);
|
||||
view.layout.addWidget(label2);
|
||||
|
||||
view.setStyleSheet(`
|
||||
#helloLabel {
|
||||
color: red;
|
||||
padding: 10px;
|
||||
}
|
||||
#worldLabel {
|
||||
color: green;
|
||||
padding: 10px;
|
||||
}
|
||||
#rootView {
|
||||
background-color: black;
|
||||
}
|
||||
`);
|
||||
view.show();
|
||||
(global as any).view = view;
|
||||
|
||||
```
|
||||
|
||||
In the case of global stylesheet you can define all your style properties in a stylesheet string and the tell the root view or window to set it as a stylsheet for it and its child widgets. The only difference here from web is that you can set a stylesheet on a widget at any level in the whole tree of widgets, the stylesheet will affect the widget and its children.
|
||||
|
||||
In the above example, in order to reference a widget in a stylesheet we will assign it a `objectName` using setObjectName instance method. Think of objectName as something similar to an `id` in the case of web. Now using the objectName you could reference the widget in the stylesheet and set style properties on them. Do not worry about the layout stuff that is going on here, that will be covered in the next section.
|
||||
|
||||
Global stylesheet really becomes powerful when you use things like pseudo-selectors (hover, checked, etc). It also has helps in implementing cascaded styles which allow you to style a group of widgets at once. We will see more about these features below.
|
||||
|
||||
> More details on all the features and the syntax can be found here: https://doc.qt.io/qt-5/stylesheet-syntax.html
|
||||
|
||||
## Inline styles
|
||||
|
||||
Lets look at this example again:
|
||||
|
||||
```js
|
||||
const { QLabel, QMainWindow } = require("@nodegui/nodegui");
|
||||
|
||||
const win = new QMainWindow();
|
||||
|
||||
const label = new QLabel(win);
|
||||
label.setText("Hello world");
|
||||
label.setInlineStyle("color: green; background-color: white;");
|
||||
|
||||
win.show();
|
||||
global.win = win;
|
||||
```
|
||||
|
||||
In most cases it would be easier to style the widgets inline. NodeGui supports inline styling using `setInlineStyle` instance method. Inline styles will only affect the widget to which the style is applied to and is often easier to understand and manage. All properties you use in the global stylesheet are available in inline styles as well.
|
||||
|
||||
## Selectors
|
||||
|
||||
NodeGui style sheets support all the selectors defined in CSS2.
|
||||
Some examples include:
|
||||
|
||||
```css
|
||||
* {
|
||||
color: blue;
|
||||
}
|
||||
|
||||
QPushButton {
|
||||
padding: 10px;
|
||||
}
|
||||
|
||||
#okButton {
|
||||
margin: 10px;
|
||||
}
|
||||
|
||||
#mainView > QPushButton {
|
||||
margin: 10px;
|
||||
}
|
||||
```
|
||||
|
||||
To see a complete list of selectors see here: https://doc.qt.io/qt-5/stylesheet-syntax.html#selector-types
|
||||
|
||||
## Pseudo states
|
||||
|
||||
Like in the web, you can style your widget based on its state. An example would be, you might want the color of the button text to be red when its hovered upon. These are possible with pseudo states. Pseudo-states appear at the end of the selector, with a colon (:) in between.
|
||||
|
||||
```css
|
||||
#okButton:hover {
|
||||
color: red;
|
||||
}
|
||||
```
|
||||
|
||||
> More details here : https://doc.qt.io/qt-5/stylesheet-syntax.html#pseudo-states
|
||||
|
||||
## Cascading
|
||||
|
||||
Style sheets can be set on the parent widgets and on child widgets. An arbitrary widget's effective style sheet is obtained by merging the style sheets set on the widget's ancestors (parent, grandparent, etc.).
|
||||
|
||||
When conflicts arise, the widget's own inline style sheet is always preferred to any inherited style sheet, irrespective of the specificity of the conflicting rules. Likewise, the parent widget's style sheet is preferred to the grandparent's, etc.
|
||||
|
||||
The behaviour is similar to what we see on the web.
|
||||
|
||||
> For more in depth examples see here: https://doc.qt.io/qt-5/stylesheet-syntax.html#cascading
|
||||
|
||||
## Supported properties
|
||||
|
||||
Since we are not running inside a web browser, there are few differences in the properties you could use in NodeGui vs in web.
|
||||
|
||||
The complete list is detailed here: https://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties
|
||||
|
||||
Apart from the properties listed in the link, NodeGui also supports layout properties related to Flex. You can use all flex properties such as align-items, justify-content, flex, etc on all widgets. [The layout styling will be coverted in more detail in the section: Layout.](layout.md)
|
||||
|
||||
## Advanced usage (Setting QObject Properties)
|
||||
|
||||
In Qt, every widget has certain properties set on them using something called as [Q_PROPERTY](https://doc.qt.io/qt-5/qobject.html#Q_PROPERTY). There are many q-properties that are defined on each widget already. You can also define custom qproperties in the native C++ code yourself too. What does it have to do with styling ? The thing is some of these properties can be altered using qt stylesheet. In Qt's terminology, these properties are called designable properties.
|
||||
|
||||
For example:
|
||||
|
||||
```css
|
||||
MyLabel {
|
||||
qproperty-alignment: AlignCenter;
|
||||
}
|
||||
MyGroupBox {
|
||||
qproperty-titlecolor: rgb(100, 200, 100);
|
||||
}
|
||||
QPushButton {
|
||||
qproperty-iconsize: 20px 20px;
|
||||
}
|
||||
```
|
||||
|
||||
You can discover these properties by following Qt's documentation or by running a simple google search like "center text in QLabel using stylesheet in Qt". These are advanced properties and in practice will come in use rarely but its good to know.
|
||||
|
||||
> More details : https://doc.qt.io/qt-5/stylesheet-syntax.html#setting-qobject-properties
|
||||
|
||||
---
|
||||
|
||||
In this section, we mostly covered the paint properties in the NodeGui stylesheet. The next section would cover on how you can use flex to layout your widgets with stylesheet.
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
sidebar_label: Learn the Basics
|
||||
title: Learn the Basics
|
||||
---
|
||||
|
||||
NodeGui uses native components instead of web based components as building blocks. So to understand the basic structure of a NodeGui app, you need to be familiar with Javascript or Typescript. This tutorial is aimed at everyone who has some web experience with web development.
|
||||
|
||||
## NodeGui development in a nutshell
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
All APIs and features found in NodeGui are accessible through the `@nodegui/nodegui` module, which can be required like any other Node.js module. Additionally you have access to all Node.js apis and node modules.
|
||||
|
||||
```javascript
|
||||
require("@nodegui/nodegui");
|
||||
```
|
||||
|
||||
The `@nodegui/nodegui` module exports features in namespaces. As an example, a window can be created
|
||||
using the `QMainWindow` class. A simple `main.js` file might open a window:
|
||||
|
||||
```javascript
|
||||
const { QMainWindow } = require("@nodegui/nodegui");
|
||||
|
||||
const win = new QMainWindow();
|
||||
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.
|
||||
|
||||
## What's going on here?
|
||||
|
||||
Firstly, we are running a regular Node.js app. This means that we are not running in a browser environment. The window you see is actually a native widget created by Qt. QMainWindow is essentially a lightweight javascript wrapper over Qt's QMainWindow. Hence every method you call on QMainWindow instance is actually affecting a native window widget. This is very light weight as compared to browser based solutions and hence is more closer to the Operating system.s
|
||||
|
||||
## Trying out the starter project
|
||||
|
||||
Clone and run the code 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
|
||||
|
||||
## What else other than a basic window?
|
||||
|
||||
NodeGui has support for basic widgets like QWidget (similar to div), QCheckBox, QPushButton and many more.
|
||||
You can take a look at the list of native widgets that NodeGui currently supports here : [Native widgets in NodeGui](/docs/api/QWidget).
|
||||
With time more widgets and APIs will be added to NodeGui. Apart from modules in NodeGui, you also have access to the entire node modules ecosystem. Thus, any node module that you can use with Node.js, can be used with NodeGui. This makes it extremely powerful.
|
||||
|
||||
Fine, I want something more custom and beautiful than just native looking widgets. What do I do?
|
||||
|
||||
To make things more beautiful, you will have to [learn about styling](styling). Lets take a look at that next.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
sidebar_label: Native Node Modules
|
||||
title: 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
|
||||
Reference in New Issue
Block a user