diff --git a/package-lock.json b/package-lock.json index e027bac96..36050fa59 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@nodegui/nodegui", - "version": "0.17.0", + "version": "0.18.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 236c635eb..d8eff0e38 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@nodegui/nodegui", - "version": "0.17.0", + "version": "0.18.0", "description": "A cross platform library to build native desktop apps.", "main": "dist/index.js", "typings": "dist/index.d.ts", diff --git a/src/demo.ts b/src/demo.ts index 1a15d48a9..6f64b80f1 100644 --- a/src/demo.ts +++ b/src/demo.ts @@ -3,10 +3,10 @@ import { QMainWindow, QLabel, WidgetEventTypes, QMouseEvent } from './index'; const win = new QMainWindow(); const label = new QLabel(); -label.setText('Move your move here'); +label.setText('Move your mouse here'); label.setMouseTracking(true); -label.addEventListener(WidgetEventTypes.MouseMove, nativeEvt => { +label.addEventListener(WidgetEventTypes.MouseMove, (nativeEvt) => { const mouseEvt = new QMouseEvent(nativeEvt as any); console.log('mouseMoved at: ', { x: mouseEvt.x(), y: mouseEvt.y() }); }); diff --git a/website/docs/guides/handle-events.md b/website/docs/guides/handle-events.md index 7f02ff4ac..0d60994a4 100644 --- a/website/docs/guides/handle-events.md +++ b/website/docs/guides/handle-events.md @@ -60,7 +60,7 @@ const win = new QMainWindow(); const checkbox = new QCheckBox(); checkbox.setText('Check/Uncheck me'); -checkbox.addEventListener('clicked', checked => { +checkbox.addEventListener('clicked', (checked) => { console.log('was checked', checked); }); @@ -83,10 +83,10 @@ const { QMainWindow, QLabel, WidgetEventTypes, QMouseEvent } = require('@nodegui const win = new QMainWindow(); const label = new QLabel(); -label.setText('Move your move here'); +label.setText('Move your mouse here'); label.setMouseTracking(true); -label.addEventListener(WidgetEventTypes.MouseMove, nativeEvt => { +label.addEventListener(WidgetEventTypes.MouseMove, (nativeEvt) => { const mouseEvt = new QMouseEvent(nativeEvt); console.log('mouseMoved at: ', { x: mouseEvt.x(), y: mouseEvt.y() }); }); diff --git a/website/docs/guides/helpful-links.md b/website/docs/guides/helpful-links.md new file mode 100644 index 000000000..b587293bf --- /dev/null +++ b/website/docs/guides/helpful-links.md @@ -0,0 +1,12 @@ +--- +sidebar_label: Helpful Links +title: Helpful links +--- + +NodeGui is an open source project that exists because of amazing contributors and users. + +The following repo contains all the helpful links, examples, plugins, etc in a single maintainable place. + +[https://github.com/nodegui/awesome-nodegui/](https://github.com/nodegui/awesome-nodegui/) + +Please do star ⭐️ the [NodeGui project repo](https://github.com/nodegui/nodegui) to show your support 😄 diff --git a/website/docs/guides/images.md b/website/docs/guides/images.md index 31e67b13b..3e99eaf50 100644 --- a/website/docs/guides/images.md +++ b/website/docs/guides/images.md @@ -3,4 +3,110 @@ sidebar_label: Images title: Images --- -WIP +Images are very important for making your app more interesting. + +In NodeGui, QLabel is typically used for displaying text, but it can also display an image. + +A very minimal example would look like this: + +```js +const { QMainWindow, QPixmap, QLabel } = require('@nodegui/nodegui'); + +const win = new QMainWindow(); +const label = new QLabel(); + +const absoulteImagePath = '/Users/atulr/Project/nodegui/nodegui/extras/assets/logox200.png'; +const image = new QPixmap(); +image.load(absoulteImagePath); + +label.setPixmap(image); + +win.setCentralWidget(label); +win.show(); +global.win = win; +``` + +Here, + +- We first create a label using QLabel. +- Then we create an instance of QPixmap. `QPixmap` is used to represent the image in memory. QPixmap is not a widget, so it can’t be shown on the screen as it is. +- Hence, we use QLabel instance and set QPixmap to it. + +The result would look like this: + +image example + +## Loading an image using a url + +Lets say we want to load an image from a URL on the internet. In this case we can't use the `load()` method of QPixmap since its only reserved for local file system images. + +Instead, we’ll download the image using axios as a buffer and use the QPixmap's method loadFromData instead. + +So let’s start with the axios installation: + +```sh +npm i axios +``` + +Now let’s create a function that will take a URL as a parameter and will return a configured QMovie instance for the GIF: + +```js +const axios = require('axios'); + +async function getPixmap(url) { + const { data } = await axios.get(url, { responseType: 'arraybuffer' }); + const pixmap = new QPixmap(); + pixmap.loadFromData(data); + return pixmap; +} +``` + +The `getPixmap` function takes in a URL, tells axios to download the image as a buffer, and then uses that buffer to create a QPixmap instance. + +Since getPixmap returns a promise, we need to make some changes to the code. After some minor refactoring, we end up with the following. + +```js +const { QMainWindow, QPixmap, QLabel } = require('@nodegui/nodegui'); +const axios = require('axios'); +async function getPixmap(url) { + const { data } = await axios.get(url, { responseType: 'arraybuffer' }); + const pixmap = new QPixmap(); + pixmap.loadFromData(data); + return pixmap; +} +async function main() { + const win = new QMainWindow(); + const label = new QLabel(); + const image = await getPixmap('https://upload.wikimedia.org/wikipedia/commons/9/96/Nature-morocco.jpg'); + label.setPixmap(image); + win.setCentralWidget(label); + win.show(); + global.win = win; +} +main().catch(console.error); +``` + +And the result would look like this: + +image url example + +## Some tips + +### Showing large images + +The above examples wont allow you to show a huge image without either cutting it off or making the widget huge. + +In order to do that: + +- You can create the image instance using QPixmap +- Set the image instance to a QLabel +- And finally set the QLabel to a QScrollArea that allows you to scroll the image if the size of the image is too big. + +### Animated images + +In order to use animated images + +- Instead of QPixmap use QMovie +- And instead of a label's `setPixmap` method use `setMovie` + +More details on it can be seen on this blog post : [https://www.sitepoint.com/build-native-desktop-gif-searcher-app-using-nodegui/](https://www.sitepoint.com/build-native-desktop-gif-searcher-app-using-nodegui/) diff --git a/website/docs/guides/networking.md b/website/docs/guides/networking.md index 28128e632..b94bec051 100644 --- a/website/docs/guides/networking.md +++ b/website/docs/guides/networking.md @@ -3,4 +3,29 @@ sidebar_label: Networking title: Networking --- -WIP +Many apps need to load resources from a remote URL. You may want to make a POST request to a REST API, or you may need to fetch a chunk of static content from another server. + +Remember that NodeGui apps do not run in a browser and hence do not have access to browser apis. NodeGui app is essentially a Node.js app. + +And in a typical Node.js application you would use a third party library like [axios](https://github.com/axios/axios), [node-fetch](https://github.com/node-fetch/node-fetch) or [frisbee](https://github.com/niftylettuce/frisbee) for achieving this functionality. + +## Using Node Fetch + +[Node Fetch](https://github.com/node-fetch/node-fetch) is a light-weight module that brings window.fetch to Node.js. + +An example usage would look like this: + +```js +const fetch = require('node-fetch'); +async function getData() { + try { + let response = await fetch('https://somewebsite.com/some.json'); + let responseJson = await response.json(); + return responseJson.somecontent; + } catch (error) { + console.error(error); + } +} +``` + +Take a look at the [Node Fetch docs](https://github.com/node-fetch/node-fetch) for a full list of properties. diff --git a/website/docs/guides/scroll-view.md b/website/docs/guides/scroll-view.md index 89ec383a9..e3ed50c51 100644 --- a/website/docs/guides/scroll-view.md +++ b/website/docs/guides/scroll-view.md @@ -1,6 +1,68 @@ --- -sidebar_label: Scroll View -title: Scroll View +sidebar_label: ScrollArea +title: Scroll Area --- -WIP +ScrollArea allows you to display a large content (image, list or even plain text) in an area of predefined size. A scroll area is used to display the contents of a child widget within a frame. If the widget exceeds the size of the frame, the view can provide scroll bars so that the entire area of the child widget can be viewed. + +## Example + +```js +const { QMainWindow, QLabel, QScrollArea } = require('@nodegui/nodegui'); + +const win = new QMainWindow(); +const label = new QLabel(); +const scrollArea = new QScrollArea(); + +scrollArea.setWidget(label); +win.setCentralWidget(scrollArea); +win.show(); + +global.win = win; + +label.setText(` +Contrary to popular belief, +Lorem Ipsum is not simply random text. +It has roots in a piece of classical Latin literature from 45 BC, +making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, +looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, +and going through the cites of the word in classical literature, +discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 +and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. +This book is a treatise on the theory of ethics, very popular during the Renaissance. +The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. + +The standard chunk of Lorem Ipsum used since the 1500s +is reproduced below for those interested. +Sections 1.10.32 and 1.10.33 from "de Finibus Bonorum et Malorum" by Cicero are also +reproduced in their exact original form, accompanied +by English versions from the 1914 translation by H. Rackham. + + +Why do we use it? + +It is a long established +fact that a reader will be distracted by +the readable content of a page when looking at its layout. +The point of using Lorem Ipsum is that it has +a more-or-less normal distribution of letters, +as opposed to using 'Content here, content here', +making it look like readable English. +Many desktop publishing packages and web page +editors now use Lorem Ipsum as their default model text, +and a search for 'lorem ipsum' will uncover many web +sites still in their infancy. Various versions +have evolved over the years, sometimes by accident, +sometimes on purpose (injected humour and the like). + +`); +``` + +**TLDR;** + +We create a QScrollArea instance and use the setWidget method to insert a widget as its child. +QScrollArea can take any widget as its child. + +The result would look like this: + +scroll area diff --git a/website/sidebars.js b/website/sidebars.js index d1ce6b1a5..66c596048 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -16,6 +16,7 @@ module.exports = { 'guides/scroll-view', 'guides/images', 'guides/networking', + 'guides/helpful-links', ], Guides: [ 'guides/nodegui-architecture',