git0 0.2.10 → 0.2.11

package/svelte-nodegui/website/docs/guides/handle-events.md

@@ -0,0 +1,188 @@
+---
+sidebar_label: Handle Events
+title: Handle Events
+---
+
+Svelte NodeGui allows you to listen to various events that might originate from the underlying Qt widgets. These events can either be a simple button click or a text change on a LineEdit or even something like window being hidden and shown.
+
+In order to do this we need to attach an event listener to the respective widget.
+
+Technically, the event listener is a NodeJs [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) instance that listens to events from the underlying Qt widget. The native Qt widget would send all the events to the event emitter in Svelte NodeGui world and the user can essentially subscribe to it.
+
+Lets see an example to see how this looks in practice.
+
+## Event handling
+
+The following example demonstrates how to add a clicked event listener to a button widget.
+
+<img src="https://github.com/nodegui/react-nodegui/releases/download/assets/events-react.gif" alt="event example" style={{width: '100%', maxWidth: 400}}/>
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+  let win;
+
+  function onClicked(checked){
+    console.log("the button was clicked", checked);
+  }
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+    <button on:clicked={onClicked} text="Click me"/>
+</window>
+```
+
+The [`on:` directive](https://svelte.dev/docs#on_component_event) accepts an event name (e.g. "clicked") and a corresponding event handler function.
+
+Internally, Qt widgets in nodegui has two types of events:
+
+- Signals: In short these are basically different for different widgets. So a button may have `clicked` and `pressed` signals, while a LineEdit may have, say, the `textChanged` signal.
+- QEvents: These are common set of events for all the widgets/qobjects in NodeGui world. These are also helpful at times but typically you would end up using signals more than these common events.
+
+In Svelte NodeGui you can listen to both Signals and QEvents using the same `on:` directive.
+
+<!-- ### useEventHandler hook and typescript support
+
+Although you can pass in an object with event handlers to the `on:` directive, its not the most efficient way. This is because everytime the render is called the `on:` directive will get a new object meaning the widget will re-render every time. To solve for this we have `useEventHandler` hook.
+
+```ts
+import React from "react";
+import {
+  Renderer,
+  Button,
+  Window,
+  useEventHandler
+} from "@nodegui/react-nodegui";
+import { QPushButtonSignals } from "@nodegui/nodegui";
+
+const App = () => {
+  const buttonHandler = useEventHandler<QPushButtonSignals>(
+    {
+      clicked: () => {
+        console.log("the button was clicked");
+      },
+      pressed: () => {
+        console.log("button was pressed");
+      },
+      objectNameChanged: objectName => {
+        console.log("new object name", objectName);
+      }
+    },
+    []
+  );
+
+  return (
+    <Window>
+      <Button text={"Click me"} on={buttonHandler} />
+    </Window>
+  );
+};
+
+Renderer.render(<App />);
+```
+
+In a nutshell, the above code uses the `useEventHandler` hook which is a wrapper over `useMemo`.
+This means, the buttonHandler remains same on every render call and hence the `on:` directive to Button doesnt change.
+
+Here `objectNameChanged` is a QEvent while `clicked` and `pressed` are signals. As an app developer it really doesnt mean much but internally they are both two different things in Qt and Svelte NodeGui allows you to use both of them using a single familiar `on:` directive.
+
+Also, another point you see in this typescript code is the QPushButtonSignals. The QPushButtonSignals is a type that allows autocompletion of event handlers as you type them. -->
+
+### How do I know which events are supported ?
+
+In order to find all the supported events for a widget you can take a look at
+
+#### All Signals for the widgets:
+
+- [https://docs.nodegui.org/docs/api/generated/globals/#interfaces](https://docs.nodegui.org/docs/api/generated/globals/#interfaces)
+- [https://docs.nodegui.org/docs/api/generated/globals/#type-aliases](https://docs.nodegui.org/docs/api/generated/globals/#type-aliases)
+
+<!-- You can subscribe to a signal like so:
+
+```ts
+import React from "react";
+import {
+  Renderer,
+  Button,
+  Window,
+  useEventHandler
+} from "@nodegui/react-nodegui";
+import { QPushButtonSignals } from "@nodegui/nodegui";
+
+const App = () => {
+  const buttonHandler = useEventHandler<QPushButtonSignals>(
+    {
+      clicked: () => {
+        console.log("the button was clicked");
+      }
+    },
+    []
+  );
+
+  return (
+    <Window>
+      <Button text={"Click me"} on={buttonHandler} />
+    </Window>
+  );
+};
+
+Renderer.render(<App />);
+```
+
+The value you receive in the callback depends on the signal. Refer to respective signal docs for more details. All the handlers are also typed. So if you are using typescript you should get correct autocomplete for it. -->
+
+#### All common QEvents for the widgets
+
+In nodegui all these common QEvents are represented under an enum type: [WidgetEventTypes](https://docs.nodegui.org/docs/api/generated/enums/widgeteventtypes)
+
+You can subscribe to a QEvent like so:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { QLabelSignals, QMouseEvent, WidgetEventTypes } from "@nodegui/nodegui";
+  let win;
+
+  function onMouseMove(checked){
+    const mouseEvt = new QMouseEvent(nativeEvt);
+    console.log("mouseMoved at: ", { x: mouseEvt.x(), y: mouseEvt.y() });
+  }
+  function onMouseButtonPress(checked){
+    console.log("mouse button was pressed");
+  }
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+    <!-- See the WidgetEventTypes interface for the names of all supported events. -->
+    <text
+      mouseTracking={true}
+      on:MouseMove={onMouseMove}
+      on:MouseButtonPress={onMouseButtonPress}
+    >
+      Move your mouse here
+    </text>
+</window>
+```
+
+<img src="https://github.com/nodegui/react-nodegui/releases/download/assets/qevents.gif" alt="qevent example" style={{width: '100%', maxWidth: 400}}/>
+
+Note here that every QEvent handler gives a reference to native QEvent in the handler callback.
+Not all native QEvent wrappers are implemented yet and we might need your help regarding those. Feel free to jump in and contribute to the nodegui core.
+
+Also you can specify the QEvent type as a regular `MouseMove` string or use it directly from the enum `WidgetEventTypes.MouseMove`. They both achieve same things.

package/svelte-nodegui/website/docs/guides/images.md

@@ -0,0 +1,62 @@
+---
+sidebar_label: Images
+title: Images
+---
+
+Images are very important for making your app more interesting.
+
+In Svelte NodeGui, `<image>` is used to display an image.
+
+Internally Image is a QLabel. QLabel is typically used for displaying text, but it can also display an image.
+What this means is that you can pass all the props you pass to a `<text>` to `<image>` also.
+
+A very minimal example would look like this:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { QLabelSignals, QMouseEvent, WidgetEventTypes } from "@nodegui/nodegui";
+  let win;
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+    <image src="https://docs.nodegui.org/img/logo-circle.png" />
+</window>
+```
+
+Here,
+
+- Image is a native QLabel component that sets the image as its pixmap.
+
+The result would look like this:
+
+<img src="https://github.com/nodegui/react-nodegui/releases/download/assets/images.png" alt="image example" style={{width: '100%', maxWidth: 400}}/>
+
+## 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 `<image>`
+- Set the image instance as a child to a `<scrollArea>`
+
+### Animated images
+
+In order to use animated images, instead of `<image>` use `<animatedImage>`
+
+### Loading an image from a buffer
+
+Lets say we want to load an image from a buffer. In this case we can't use the `src` prop since its only reserved for local file system path or urls.
+
+In this case use the `buffer` prop.

package/svelte-nodegui/website/docs/guides/layout.md

@@ -0,0 +1,281 @@
+---
+sidebar_label: Layout
+title: Layout
+---
+
+Svelte NodeGui uses a layout system to automatically arrange child components within a component to ensure that they make good use of the available space.
+
+## Fixed Dimensions
+
+A component's height and width determine its size on the screen. The simplest way to set the dimensions of a component is by adding a fixed width and height to style. Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <view style="width: 50px; height: 30px; background-color: yellow;"/>
+</window>
+```
+
+
+## Dynamic Layouts
+
+Dynamic layouts automatically position and resize components 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.
+
+Svelte NodeGui currently supports layouting using FlexLayout.
+
+## FlexLayout
+
+FlexLayout allows the children to expand and shrink dynamically based on available space. Normally you will use `flex: 1`, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.
+
+> A component 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 flex-direction, align-items,and justify-content to achieve the right layout.
+
+### Example:
+
+Lets say you want to build a UI that has a parent view which has two child components. 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="https://github.com/nodegui/react-nodegui/raw/gh-pages/img/flex-layout-1.png" alt="flex layout example 1" style={{maxWidth: 700, width:'100%'}}/>
+
+The code for that would look something like this:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <view id="rootView">
+    <text id="label">Hello</text>
+    <view id="view"/>
+  </view>
+</window>
+
+<style>
+  #rootView{
+    height: '100%';
+    background-color: blue;
+  }
+  #label {
+    flex: 1;
+    color: white;
+    background-color: green;
+  }
+  #view {
+    flex: 3;
+    background-color: white;
+  }
+</style>
+```
+
+> 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.
+
+
+## BoxView Layout
+
+BoxView Layout is an implementation of QBoxLayout of NodeGui.
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { Direction } from "@nodegui/nodegui";
+  import type { QPushButtonSignals } from "@nodegui/nodegui";
+
+  let additionalButtons: string[] = [];
+  let direction: Direction = Direction.LeftToRight;
+
+  function addHandler(): void {
+    additionalButtons = [...additionalButtons, `Button ${additionalButtons.length}`];
+  }
+  function removeHandler(): void {
+    additionalButtons = [...additionalButtons.slice(0, additionalButtons.length - 1)];
+  }
+  function toggleDirection(): void {
+    direction = ((direction + 1) % 4) as Direction;
+  }
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <boxView direction={direction}>
+    <button text="Add" on={addHandler} />
+    <button text="Remove" on={removeHandler} />
+    <button text="Toggle direction" on={toggleDirection} />
+    {#each additionalButtons as additionalButton (additionalButton)}
+      <button text={additionalButton}/>
+    {/each}
+  </boxView>
+</window>
+```
+
+The above code produces
+
+<img src="https://github.com/nodegui/react-nodegui/raw/gh-pages/img/box-layout-1.png" alt="box layout example 1" style={{maxWidth: 700, width:'100%'}}/>
+<img src="https://github.com/nodegui/react-nodegui/raw/gh-pages/img/box-layout-2.png" alt="box layout example 1" style={{maxWidth: 700, width:'100%'}}/>
+
+
+## GridView Layout
+
+GridView Layout is an implementation of QGridLayout of NodeGui.
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+  let win;
+
+  let additionalRows: string[] = [];
+  let additionalColumns: string[] = [];
+  let rowStretch: boolean = false;
+
+  function insertRowHandler(): void {
+    additionalRows = [...additionalRows, `Row ${additionalRows.length}`];
+  }
+  function removeRowHandler(): void {
+    additionalRows = [...additionalRows.slice(0, additionalRows.length - 1)];
+  }
+  function insertColumnHandler(): void {
+    additionalColumns = [...additionalColumns, `Column ${additionalColumns.length}`];
+  }
+  function removeColumnsHandler(): void {
+    additionalColumns = [...additionalColumns.slice(0, additionalColumns.length - 1)];
+  }
+  function toggleRowStretch(): void {
+    rowStretch = !rowStretch;
+  }
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <gridView
+    style="flex: 1"
+    columnProps={{
+      0: {
+        minWidth: 200,
+      },
+      1: {
+        minWidth: 300,
+      },
+    }}
+    rowProps={{
+      0: {
+        stretch: rowStretch ? 2 : undefined,
+        minHeight: 400,
+      },
+      1: {
+        stretch: !rowStretch ? 2 : undefined,
+      },
+    }}
+  >
+    <gridRow>
+      <gridColumn width={2}>
+        <view style="background-color: red">
+          <text>Hello</text>
+          <button text="Insert row" on:clicked={insertRowHandler} />
+          <button text="Remove row" on:clicked={removeRowHandler} />
+          <button text="Toggle row stretch" on:clicked={toggleRowStretch} />
+          <button text="Insert column" on:clicked={insertColumnHandler} />
+          <button text="Remove column" on:clicked={removeColumnsHandler} />
+        </view>
+      </gridColumn>
+      <gridColumn width={2}>
+        <view style="background-color: blue">
+          <text>Second Column</text>
+        </view>
+      </gridColumn>
+      {#each additionalColumns as column (column)}
+        <gridColumn>
+          <text>{column}</text>
+        </gridColumn>
+      {/each}
+    </gridRow>
+    <gridRow height={2}>
+      <gridColumn>
+        <view style="background-color: green">
+          <text>Second row</text>
+        </view>
+      </gridColumn>
+      <gridColumn>
+        <view style="background-color: purple">
+          <text>Second Column</text>
+        </view>
+      </gridColumn>
+      <gridColumn>
+        <view style="background-color: purple">
+          <text>Third Column</text>
+        </view>
+      </gridColumn>
+      <gridColumn>
+        <view style="background-color: purple">
+          <text>Fourth Column</text>
+        </view>
+      </gridColumn>
+      {#each additionalColumns as column (column)}
+        <gridColumn>
+          <text>Second {column}</text>
+        </gridColumn>
+      {/each}
+    </gridRow>
+    <gridRow>
+      <gridColumn>
+        <text>Third row</text>
+      </gridColumn>
+    </gridRow>
+    {#each additionalRows as row (row)}
+      <gridColumn>
+        <gridColumn width={2}>
+          <text>{row}</text>
+        </gridColumn>
+        <gridColumn>
+          <text>Second {row}</text>
+        </gridColumn>
+      </gridColumn>
+    {/each}
+  </gridView>
+</window>
+```
+
+The above code produces
+
+<img src="https://github.com/nodegui/react-nodegui/raw/gh-pages/img/grid-layout-1.png" alt="grid layout example 1" style={{maxWidth: 700, width:'100%'}}/>
+
+
+## Conclusion
+
+The primary layout in Svelte 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.

package/svelte-nodegui/website/docs/guides/networking.md

@@ -0,0 +1,31 @@
+---
+sidebar_label: Networking
+title: Networking
+---
+
+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.

package/svelte-nodegui/website/docs/guides/packaging.md

@@ -0,0 +1,32 @@
+---
+sidebar_label: Packaging
+title: Packaging
+---
+
+In order to distribute your finished app, you can use [@nodegui/packer](https://github.com/nodegui/packer)
+
+- **Step 1: (Run this command only once)**
+
+  ```sh
+  npx nodegui-packer --init MyAppName
+  ```
+
+  This will produce the deploy directory containing the template. You can modify this to suite your needs. Like add icons, change the name, description and add other native features or dependencies. Make sure you commit this directory.
+
+- **Step 2: (Run this command every time you want to build a new distributable)**
+
+  Next you can run the pack command:
+
+  ```sh
+  npm run build
+  ```
+
+  This will produce the js bundle along with assets inside the ./dist directory
+
+  ```sh
+  npx nodegui-packer --pack ./dist
+  ```
+
+  This will build the distributable using @nodegui/packer based on your template. The output of the command is found under the build directory. You should gitignore the build directory.
+
+  More details about packer can be found here: https://github.com/nodegui/packer

package/svelte-nodegui/website/docs/guides/scroll-view.md

@@ -0,0 +1,69 @@
+---
+sidebar_label: ScrollArea
+title: Scroll Area
+---
+
+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
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <scrollArea>
+    <text>
+      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).
+    </text>
+  </scrollArea>
+</window>
+```
+
+**TLDR;**
+
+We create a `<scrollArea>` instance and then set the target widget as its child.
+
+The result would look like this:
+
+<img src="https://github.com/nodegui/react-nodegui/releases/download/assets/scrollarea.gif" alt="scroll area" style={{width: '100%', maxWidth: 400}}/>