Adjust readme

README.md

@@ -25,25 +25,21 @@ step during the `npm i` command.
 
 ```
 const { View } = require('qml-raub');
-View.init(process.cwd(), HWND, CTX);
+View.init(process.cwd(), hwnd, ctx, device);
 
 const ui = new View({ width, height, file: 'gui.qml' });
 ```
 
 The QML engine must be initialized first. Then, new View instances can be created.
-See [TypeScript defenitions](/index.d.ts) for more details.
+See [TypeScript declarations](/index.d.ts) for more details.
 
-QML views can process input events, as per Qt documentation. We can
-propagate mouse and keyboard events to the View, and it will react as any
-normal QML scene. Also there is a loop-back to propagate back any unused
-events. This means a lot for screen-space UI's: we still want the underlying
-app to receive mouse and keyboard events as well.
+QML views can process input events. Mouse and keyboard events can be sent to a view.
+Unhandled (unused) events are re-emitted by the view.
 
-Using loop-back implies a change from `source -> app` event
-flow to `source -> ui -> app`. If mouse click hits a QML button, we don't
-want it to also hit an object behind the button. And if some QML input is
-focused, we should be able to type any text without hitting random
-combinations of app's hotkeys.
+Changing the event flow from `window -> app` to `window -> ui -> app` allows blocking
+the handled events. For example, when a QML button is pressed, a 3D scene
+behind the button won't receive any mouse event. Or when a QML input is
+focused, the app's hotkeys won't be triggered by typing text.
 
 
 ### class View
@@ -62,7 +58,7 @@ display in the distant corner of 3d room, can be textured this way.
 const ui = new View({ width, height, file: 'gui.qml' });
 ```
 
-See [TypeScript defenitions](/index.d.ts) for more details.
+See [TypeScript declarations](/index.d.ts) for more details.
 
 Events:
 * `'destroy'` - emitted when the scene is destroyed.
@@ -85,7 +81,7 @@ const x1 = new Property({ view, name: 'obj1', key: 'x1' });
 x1.value = 10;
 ```
 
-See [TypeScript defenitions](/index.d.ts) for more details.
+See [TypeScript declarations](/index.d.ts) for more details.
 
 ---
 

index.d.ts

@@ -44,8 +44,10 @@ declare module "qml-raub" {
 
 	/**
 	 * View
-	 *
+	 * 
 	 * Loads and manages a QML file.
+	 * 
+	 * @note Make sure to always switch back to your own OpenGL context before drawing.
 	*/
 	export class View implements EventEmitter {
 		constructor(opts?: TOptsView);
@@ -101,11 +103,11 @@ declare module "qml-raub" {
 
 		/**
 		 * Load a new QML scene from file or source text.
-		 *
+		 * 
 		 * @param opts either `{ file: string }` or `{ source: string }`.
-		 *
+		 * 
 		 * @description
-		 *
+		 * 
 		 * Can load QML from `file` (by path), or directly from `source` string.
 		 * The old scene will be discarded, if any. A new texture will be created.
 		 */
@@ -125,30 +127,30 @@ declare module "qml-raub" {
 
 		/**
 		 * Initialize the QML engine.
-		 *
+		 * 
 		 * @param cwd base directory for QML file resolution. Usually, `process.cwd()`.
 		 * @param wnd platform window handle (e.g. HWND on Windows).
 		 * @param ctx the OpenGL context to which the QML render texture will be made available.
 		 * @param device optional system display device, used only on Linux.
-		 *
+		 * 
 		 * @see [OpenGL context](https://www.khronos.org/opengl/wiki/OpenGL_Context).
-		 *
+		 * 
 		 * @description
 		 * QML has a dedicated OpenGL context because of the renderer-specific requirements.
 		 * The QML render textures are available to the main application's OpenGL context as well.
 		 *
 		 * With [glfw-raub](https://github.com/node-3d/glfw-raub), `hwnd` and `ctx` can
 		 * be obtained with helpers:
-		 *
+		 * 
 		 * ```
 		 * // window - is returned by glfw.createWindow(...) call
 		 * const hwnd = glfw.platformWindow(window);
 		 * const ctx = glfw.platformContext(window);
 		 * const device = glfw.platformDevice();
 		 * ```
-		 *
+		 * 
 		 * or
-		 *
+		 * 
 		 * ```
 		 * // window - is an instance of glfw.Window
 		 * const hwnd = window.platformWindow;
@@ -158,16 +160,34 @@ declare module "qml-raub" {
 		 */
 		static init(cwd: string, wnd: number, ctx: number, device?: number): void;
 
-		/** Register a QML "library" directory. */
+		/**
+		 * Register a QML "library" directory.
+		 * 
+		 * Where to look for `*.qml` files for `import` resolution.
+		 */
 		static libs(l: string): void;
 
-		/** Register a QML "plugin" directory. */
+		/**
+		 * Register a QML "plugin" directory.
+		 * 
+		 * Where to look for low-level Qt stuff, such as `platforms, iconengines, imageformats`.
+		 */
 		static plugins(p: string): void;
 
-		/** Assign QML style value. */
-		static style(name: string, def: string): void;
+		/**
+		 * Assign
+		 * [QML style](https://doc.qt.io/qt-5/qtquickcontrols2-styles.html#using-styles-in-qt-quick-controls)
+		 * value.
+		 */
+		static style(name: string, fallback: string): void;
 
-		/** Update the QML scene (similar to "pollEvents" for a window). */
+		/**
+		 * Update the QML scene (similar to "pollEvents" for a window).
+		 * 
+		 * Required for async operations, such as signal/slot interaction.
+		 * If this method is not called at all, the QML scene won't ever load. It is preferred
+		 * to call it regularly, e.g. every frame.
+		 */
 		static update(): void;
 
 		// ------ implements EventEmitter