Feature/element queries (#575)

* Extended window provider with minimize and restore methods

* Moved window interface to types folder, extended it with element query definitions

* Defined intefaces for WindowElement objects and their description

* Introduces window-element query type

* Introduced ElementInspectionProviderInterface

* Added ElementInspectionProviderInterface to provider registry

* Restructured shared code to improve exports

* Introduced windowElementDescribedBy query

* Implemented find, findAll, waitFor and hooks for windows

* Fixed broken tutorials link in readme

* Updated window tests

* Removed leftover dead code

Author: s1hofmann

README.md

@@ -48,7 +48,7 @@ Check out this demo video to get a first impression of what nut.js is capable of
 
 # Tutorials
 
-Please consult the project website at [nutjs.dev](https://nutjs.dev/docs/tutorial-first_steps/prerequisites) for in-depth tutorials
+Please consult the project website at [nutjs.dev](https://nutjs.dev/tutorials/first_steps#prerequisites) for in-depth tutorials
 
 # API Docs
 

core/nut.js/index.ts

@@ -8,7 +8,15 @@ import { LineHelper } from "./lib/util/linehelper.class";
 import { createWindowApi } from "./lib/window.function";
 import providerRegistry from "./lib/provider/provider-registry.class";
 import { loadImageResource } from "./lib/imageResources.function";
-import { ColorQuery, LineQuery, RGBA, WindowQuery, WordQuery } from "@nut-tree/shared";
+import {
+  ColorQuery,
+  LineQuery,
+  RGBA,
+  WindowElementDescription,
+  WindowElementQuery,
+  WindowQuery,
+  WordQuery
+} from "@nut-tree/shared";
 
 export {
   AssertClass,
@@ -91,6 +99,16 @@ const windowWithTitle = (title: string | RegExp): WindowQuery => {
   };
 };
 
+const windowElementDescribedBy = (description: WindowElementDescription): WindowElementQuery => {
+  return {
+    type: "window-element",
+    id: `window-element-described-by-${JSON.stringify(description)}`,
+    by: {
+      description
+    }
+  };
+};
+
 const pixelWithColor = (color: RGBA): ColorQuery => {
   return {
     type: "color",
@@ -122,5 +140,6 @@ export {
   singleWord,
   textLine,
   windowWithTitle,
+  windowElementDescribedBy,
   pixelWithColor
 };

core/nut.js/lib/provider/provider-registry.class.ts

@@ -12,7 +12,8 @@ import {
   ScreenProviderInterface,
   TextFinderInterface,
   WindowFinderInterface,
-  WindowProviderInterface
+  WindowProviderInterface,
+  ElementInspectionProviderInterface
 } from "@nut-tree/provider-interfaces";
 
 import ImageReaderImpl from "./io/jimp-image-reader.class";
@@ -45,6 +46,7 @@ class DefaultProviderRegistry implements ProviderRegistry {
   private _textFinder?: TextFinderInterface;
   private _windowFinder?: WindowFinderInterface;
   private _colorFinder?: ColorFinderInterface;
+  private _windowElementInspector?: ElementInspectionProviderInterface;
 
   hasClipboard(): boolean {
     return this._clipboard != null;
@@ -190,6 +192,20 @@ class DefaultProviderRegistry implements ProviderRegistry {
     this.getLogProvider().trace("Registered new WindowFinder provider", value);
   };
 
+  getWindowElementInspector = (): ElementInspectionProviderInterface => {
+    if (this._windowElementInspector) {
+      return this._windowElementInspector;
+    }
+    const error = new Error(`No WindowElementInspector registered`);
+    this.getLogProvider().error(error);
+    throw error;
+  };
+
+  registerWindowElementInspector = (value: ElementInspectionProviderInterface) => {
+    this._windowElementInspector = value;
+    this.getLogProvider().trace("Registered new WindowElementInspector provider", value);
+  };
+
   hasImageReader(): boolean {
     return this._imageReader != null;
   }

core/nut.js/lib/screen.class.ts

@@ -2,6 +2,7 @@ import { cwd } from "process";
 import {
   ColorQuery,
   FileType,
+  FindHookCallback,
   FindInput,
   FindResult,
   Image,
@@ -13,12 +14,13 @@ import {
   isWindowQuery,
   LineQuery,
   MatchRequest,
-  MatchResult,
+  MatchResultCallback,
   OptionalSearchParameters,
   Point,
   PointResultFindInput,
   Region,
   RegionResultFindInput,
+  WindowCallback,
   WindowResultFindInput,
   WordQuery
 } from "@nut-tree/shared";
@@ -34,15 +36,6 @@ import {
   isRegionResultFindInput
 } from "./screen-helpers.function";
 
-export type WindowCallback = (target: Window) => void | Promise<void>;
-export type MatchResultCallback<TARGET_TYPE> = (
-  target: MatchResult<TARGET_TYPE>
-) => void | Promise<void>;
-export type FindHookCallback =
-  | WindowCallback
-  | MatchResultCallback<Point>
-  | MatchResultCallback<Region>;
-
 function validateSearchRegion(
   search: Region,
   screen: Region,
@@ -333,6 +326,10 @@ export class ScreenClass {
     searchInput: WindowResultFindInput | Promise<WindowResultFindInput>,
     params?: OptionalSearchParameters<PROVIDER_DATA_TYPE>
   ): Promise<Window[]>;
+  public async findAll<PROVIDER_DATA_TYPE>(
+    searchInput: FindInput | Promise<FindInput>,
+    params?: OptionalSearchParameters<PROVIDER_DATA_TYPE>
+  ): Promise<FindResult[]>;
   public async findAll<PROVIDER_DATA_TYPE>(
     searchInput: FindInput | Promise<FindInput>,
     params?: OptionalSearchParameters<PROVIDER_DATA_TYPE>