From 05f0f1043da90181efc87889ca14be13f20951aa Mon Sep 17 00:00:00 2001 From: Sential Date: Sat, 14 Dec 2019 15:26:06 +0100 Subject: [PATCH 1/5] docs: move objects to separate files --- README.md | 196 +---------------------------------------- docs/monitor-info.md | 5 ++ docs/monitor.md | 39 ++++++++ docs/rectangle.md | 6 ++ docs/window-info.md | 8 ++ docs/window-manager.md | 46 ++++++++++ docs/window.md | 101 +++++++++++++++++++++ 7 files changed, 206 insertions(+), 195 deletions(-) create mode 100644 docs/monitor-info.md create mode 100644 docs/monitor.md create mode 100644 docs/rectangle.md create mode 100644 docs/window-info.md create mode 100644 docs/window-manager.md create mode 100644 docs/window.md diff --git a/README.md b/README.md index 27c9413..da454f1 100644 --- a/README.md +++ b/README.md @@ -29,198 +29,4 @@ window.setBounds({ x: 0, y: 0 }); ``` # Documentation - -## Object `Rectangle` - -- `x` number -- `y` number -- `width` number -- `height` number - -## Object `WindowInfo` - -- `title` string -- `processId` string -- `path` string - path to executable associated with the window -- `bounds` [`Rectangle`](#object-rectangle) -- `opacity` number (`Windows`) -- `owner` [`Window`](#class-window) (`Windows`) - owner window of the current window - -## Object `MonitorInfo` - -- `isPrimary` boolean -- `bounds` [`Rectangle`](#object-rectangle) - the monitor position and bounds -- `workArea` [`Rectangle`](#object-rectangle) - the monitor working area bounds - -## Class `WindowManager` - -### Instance methods - -#### windowManager.requestAccessibility() `macOS` - Required before any action on macOS. -- Returns `boolean` - -#### windowManager.getActiveWindow() `Windows` `macOS` - -- Returns [`Window`](#class-window) - -#### windowManager.getWindows() `Windows` `macOS` - -- Returns [`Window[]`](#class-window) - -#### windowManager.getMonitors() `Windows` - -- Returns [`Monitor[]`](#class-monitor) - -#### windowManager.getPrimaryMonitor() `Windows` - -- Returns [`Monitor`](#class-monitor) - -### Events - -#### Event 'window-activated' `Windows` `macOS` - -Returns: - -- [`Window`](#class-window) - -Emitted when a window has been activated. - -## Class `Window` - -We try to keep this class similar to Electron's known [`BrowserWindow`](https://electronjs.org/docs/api/browser-window) class, to keep it simple to use. - -### new Window(id: number) - -- `id` number - -### Instance properties - -- `id` number -- `processId` number - process id associated with the window -- `path` string - path to executable associated with the window - -### Instance methods - -#### win.getBounds() `Windows` `macOS` - -- Returns [`Rectangle`](#object-rectangle) - -#### win.setBounds(bounds: Rectangle) `Windows` `macOS` - -Resizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values. - -```javascript -window.setBounds({ height: 50 }); -``` - -#### win.getInfo() `Windows` `macOS` - -Returns [`WindowInfo`](#object-windowinfo) - -#### win.getTitle() `Windows` `macOS` - -- Returns `string` - -#### win.show() `Windows` - -Shows the window. - -#### win.hide() `Windows` - -Hides the window. - -#### win.minimize() `Windows` `macOS` - -Minimizes the window. - -#### win.restore() `Windows` `macOS` - -Restores the window. - -#### win.maximize() `Windows` `macOS` - -Maximizes the window. - -#### win.bringToTop() `Windows` `macOS` - -Brings the window to top and focuses it. - -#### win.setOpacity(opacity: number) `Windows` - -- `opacity` - a value between 0 and 1. - -Sets the window opacity. - -#### win.getOpacity() `Windows` - -Gets the window opacity - -Returns `number` between 0 and 1. - -#### win.getMonitor() `Windows` - -Gets monitor which the window belongs to. - -Returns [`Monitor`](#class-monitor) - -#### win.isWindow() `Windows` `macOS` - -Returns `boolean` - whether the window is a valid window. - -#### win.isVisible() `Windows` -Returns `boolean` - whether the window is visible or not. - -#### win.getOwner() `Windows` - -Returns [`Window`](#class-window) - -#### win.setOwner(win: [`Window`](#class-window) | number | null) `Windows` - -- `win` [Window](#class-window) | number | null - - pass null to unset window owner. - -#### win.getIcon(size: number) `Windows` `macOS` - -- `size` number - can be only `16`, `32`, `64`, `256`. By default it's `64`. - -Returns a png Buffer - - -## Class `Monitor` `Windows` - -### new Monitor(id: number) - -- `id` number - the monitor handle - -### Instance properties - -- `id` number - -### Instance methods - -#### monitor.getBounds() `Windows` - -- Returns [`Rectangle`](#object-rectangle) - -#### monitor.getWorkArea() `Windows` - -Gets monitor working area bounds. - -- Returns [`Rectangle`](#object-rectangle) - -#### monitor.getInfo() `Windows` - -Returns [`MonitorInfo`](#object-monitorinfo) - -#### monitor.isPrimary() `Windows` - -Whether the monitor is primary. - -- Returns `boolean` - -#### monitor.getScaleFactor() `Windows` - -Gets monitor scale factor (DPI). - -- Returns `number` +The documentation and API references are located in the [`docs`](docs) directory. \ No newline at end of file diff --git a/docs/monitor-info.md b/docs/monitor-info.md new file mode 100644 index 0000000..a014cc1 --- /dev/null +++ b/docs/monitor-info.md @@ -0,0 +1,5 @@ +## Object `MonitorInfo` + +- `isPrimary` boolean +- `bounds` [`Rectangle`](#object-rectangle) - the monitor position and bounds +- `workArea` [`Rectangle`](#object-rectangle) - the monitor working area bounds diff --git a/docs/monitor.md b/docs/monitor.md new file mode 100644 index 0000000..9d816ea --- /dev/null +++ b/docs/monitor.md @@ -0,0 +1,39 @@ +## Class `Monitor` `Windows` + +Control monitors. + +### new Monitor(id: number) + +- `id` number - the monitor handle + +### Instance properties + +- `id` number + +### Instance methods + +#### monitor.getBounds() `Windows` + +- Returns [`Rectangle`](#object-rectangle) + +#### monitor.getWorkArea() `Windows` + +Gets monitor working area bounds. + +- Returns [`Rectangle`](#object-rectangle) + +#### monitor.getInfo() `Windows` + +Returns [`MonitorInfo`](#object-monitorinfo) + +#### monitor.isPrimary() `Windows` + +Whether the monitor is primary. + +- Returns `boolean` + +#### monitor.getScaleFactor() `Windows` + +Gets monitor scale factor (DPI). + +- Returns `number` diff --git a/docs/rectangle.md b/docs/rectangle.md new file mode 100644 index 0000000..81283b6 --- /dev/null +++ b/docs/rectangle.md @@ -0,0 +1,6 @@ +## Object `Rectangle` + +- `x` number +- `y` number +- `width` number +- `height` number \ No newline at end of file diff --git a/docs/window-info.md b/docs/window-info.md new file mode 100644 index 0000000..d37058b --- /dev/null +++ b/docs/window-info.md @@ -0,0 +1,8 @@ +## Object `WindowInfo` + +- `title` string +- `processId` string +- `path` string - path to executable associated with the window +- `bounds` [`Rectangle`](#object-rectangle) +- `opacity` number (`Windows`) +- `owner` [`Window`](#class-window) (`Windows`) - owner window of the current window \ No newline at end of file diff --git a/docs/window-manager.md b/docs/window-manager.md new file mode 100644 index 0000000..68148fe --- /dev/null +++ b/docs/window-manager.md @@ -0,0 +1,46 @@ +## `windowManager` + +Get monitors and opened windows. + +```typescript +import { windowManager } from 'node-window-manager'; + +windowManager.requestAccessibility(); + +const window = windowManager.getActiveWindow(); + +// Prints the currently focused window title. +console.log(window.getTitle()); +``` + +### Instance methods + +#### windowManager.requestAccessibility() `macOS` + Required before any action on macOS. +- Returns `boolean` + +#### windowManager.getActiveWindow() `Windows` `macOS` + +- Returns [`Window`](#class-window) + +#### windowManager.getWindows() `Windows` `macOS` + +- Returns [`Window[]`](#class-window) + +#### windowManager.getMonitors() `Windows` + +- Returns [`Monitor[]`](#class-monitor) + +#### windowManager.getPrimaryMonitor() `Windows` + +- Returns [`Monitor`](#class-monitor) + +### Events + +#### Event 'window-activated' `Windows` `macOS` + +Returns: + +- [`Window`](#class-window) + +Emitted when a window has been activated. \ No newline at end of file diff --git a/docs/window.md b/docs/window.md new file mode 100644 index 0000000..b720acc --- /dev/null +++ b/docs/window.md @@ -0,0 +1,101 @@ +## Class `Window` + +Control opened windows. + +We try to keep this class similar to Electron's known [`BrowserWindow`](https://electronjs.org/docs/api/browser-window) class, to keep it simple to use. + +### new Window(id: number) + +- `id` number + +### Instance properties + +- `id` number +- `processId` number - process id associated with the window +- `path` string - path to executable associated with the window + +### Instance methods + +#### win.getBounds() `Windows` `macOS` + +- Returns [`Rectangle`](#object-rectangle) + +#### win.setBounds(bounds: Rectangle) `Windows` `macOS` + +Resizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values. + +```javascript +window.setBounds({ height: 50 }); +``` + +#### win.getInfo() `Windows` `macOS` + +Returns [`WindowInfo`](#object-windowinfo) + +#### win.getTitle() `Windows` `macOS` + +- Returns `string` + +#### win.show() `Windows` + +Shows the window. + +#### win.hide() `Windows` + +Hides the window. + +#### win.minimize() `Windows` `macOS` + +Minimizes the window. + +#### win.restore() `Windows` `macOS` + +Restores the window. + +#### win.maximize() `Windows` `macOS` + +Maximizes the window. + +#### win.bringToTop() `Windows` `macOS` + +Brings the window to top and focuses it. + +#### win.setOpacity(opacity: number) `Windows` + +- `opacity` - a value between 0 and 1. + +Sets the window opacity. + +#### win.getOpacity() `Windows` + +Gets the window opacity + +Returns `number` between 0 and 1. + +#### win.getMonitor() `Windows` + +Gets monitor which the window belongs to. + +Returns [`Monitor`](#class-monitor) + +#### win.isWindow() `Windows` `macOS` + +Returns `boolean` - whether the window is a valid window. + +#### win.isVisible() `Windows` +Returns `boolean` - whether the window is visible or not. + +#### win.getOwner() `Windows` + +Returns [`Window`](#class-window) + +#### win.setOwner(win: [`Window`](#class-window) | number | null) `Windows` + +- `win` [Window](#class-window) | number | null + - pass null to unset window owner. + +#### win.getIcon(size: number) `Windows` `macOS` + +- `size` number - can be only `16`, `32`, `64`, `256`. By default it's `64`. + +Returns a png Buffer \ No newline at end of file From ab931abe75a9932d0f87baf3a249a8d3e87da06c Mon Sep 17 00:00:00 2001 From: Sential Date: Sat, 14 Dec 2019 15:48:22 +0100 Subject: [PATCH 2/5] docs: add more examples, fix links --- docs/monitor-info.md | 4 ++-- docs/monitor.md | 13 ++++++++++--- docs/window-info.md | 4 ++-- docs/window-manager.md | 10 +++++----- docs/window.md | 14 +++++++------- 5 files changed, 26 insertions(+), 19 deletions(-) diff --git a/docs/monitor-info.md b/docs/monitor-info.md index a014cc1..82df485 100644 --- a/docs/monitor-info.md +++ b/docs/monitor-info.md @@ -1,5 +1,5 @@ ## Object `MonitorInfo` - `isPrimary` boolean -- `bounds` [`Rectangle`](#object-rectangle) - the monitor position and bounds -- `workArea` [`Rectangle`](#object-rectangle) - the monitor working area bounds +- `bounds` [`Rectangle`](rectangle.md) - the monitor position and bounds +- `workArea` [`Rectangle`](rectangle.md) - the monitor working area bounds diff --git a/docs/monitor.md b/docs/monitor.md index 9d816ea..3d68672 100644 --- a/docs/monitor.md +++ b/docs/monitor.md @@ -2,6 +2,13 @@ Control monitors. +```typescript +import { windowManager } from 'node-window-manager'; + +// Gets height of the primary window working area. +const { height } = windowManager.getPrimaryWindow().getWorkArea(); +``` + ### new Monitor(id: number) - `id` number - the monitor handle @@ -14,17 +21,17 @@ Control monitors. #### monitor.getBounds() `Windows` -- Returns [`Rectangle`](#object-rectangle) +- Returns [`Rectangle`](rectangle.md) #### monitor.getWorkArea() `Windows` Gets monitor working area bounds. -- Returns [`Rectangle`](#object-rectangle) +- Returns [`Rectangle`](rectangle.md) #### monitor.getInfo() `Windows` -Returns [`MonitorInfo`](#object-monitorinfo) +Returns [`MonitorInfo`](monitor-info.md) #### monitor.isPrimary() `Windows` diff --git a/docs/window-info.md b/docs/window-info.md index d37058b..7a398c0 100644 --- a/docs/window-info.md +++ b/docs/window-info.md @@ -3,6 +3,6 @@ - `title` string - `processId` string - `path` string - path to executable associated with the window -- `bounds` [`Rectangle`](#object-rectangle) +- `bounds` [`Rectangle`](rectangle.md) - `opacity` number (`Windows`) -- `owner` [`Window`](#class-window) (`Windows`) - owner window of the current window \ No newline at end of file +- `owner` [`Window`](window.md) (`Windows`) - owner window of the current window \ No newline at end of file diff --git a/docs/window-manager.md b/docs/window-manager.md index 68148fe..e7fd4b6 100644 --- a/docs/window-manager.md +++ b/docs/window-manager.md @@ -21,19 +21,19 @@ console.log(window.getTitle()); #### windowManager.getActiveWindow() `Windows` `macOS` -- Returns [`Window`](#class-window) +- Returns [`Window`](window.md) #### windowManager.getWindows() `Windows` `macOS` -- Returns [`Window[]`](#class-window) +- Returns [`Window[]`](window.md) #### windowManager.getMonitors() `Windows` -- Returns [`Monitor[]`](#class-monitor) +- Returns [`Monitor[]`](monitor.md) #### windowManager.getPrimaryMonitor() `Windows` -- Returns [`Monitor`](#class-monitor) +- Returns [`Monitor`](monitor.md) ### Events @@ -41,6 +41,6 @@ console.log(window.getTitle()); Returns: -- [`Window`](#class-window) +- [`Window`](window.md) Emitted when a window has been activated. \ No newline at end of file diff --git a/docs/window.md b/docs/window.md index b720acc..4bba317 100644 --- a/docs/window.md +++ b/docs/window.md @@ -1,6 +1,6 @@ ## Class `Window` -Control opened windows. +Control open windows. We try to keep this class similar to Electron's known [`BrowserWindow`](https://electronjs.org/docs/api/browser-window) class, to keep it simple to use. @@ -30,7 +30,7 @@ window.setBounds({ height: 50 }); #### win.getInfo() `Windows` `macOS` -Returns [`WindowInfo`](#object-windowinfo) +Returns [`WindowInfo`](window-info.md) #### win.getTitle() `Windows` `macOS` @@ -76,7 +76,7 @@ Returns `number` between 0 and 1. Gets monitor which the window belongs to. -Returns [`Monitor`](#class-monitor) +Returns [`Monitor`](monitor.md) #### win.isWindow() `Windows` `macOS` @@ -87,15 +87,15 @@ Returns `boolean` - whether the window is visible or not. #### win.getOwner() `Windows` -Returns [`Window`](#class-window) +Returns `Window` -#### win.setOwner(win: [`Window`](#class-window) | number | null) `Windows` +#### win.setOwner(win: Window | number | null) `Windows` -- `win` [Window](#class-window) | number | null +- `win` Window | number | null - pass null to unset window owner. #### win.getIcon(size: number) `Windows` `macOS` -- `size` number - can be only `16`, `32`, `64`, `256`. By default it's `64`. +- `size` number - can be `16`, `32`, `64` or `256`. By default it's `64`. Returns a png Buffer \ No newline at end of file From cd7ca0a722021e74950ce26dabf46ef5bd25b8e6 Mon Sep 17 00:00:00 2001 From: Sential Date: Sat, 14 Dec 2019 16:03:46 +0100 Subject: [PATCH 3/5] docs: describe requestAccessibility more precisely --- docs/breaking-changes.md | 29 +++++++++++++++++++++++++++++ docs/window-manager.md | 13 ++++++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 docs/breaking-changes.md diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md new file mode 100644 index 0000000..41482ab --- /dev/null +++ b/docs/breaking-changes.md @@ -0,0 +1,29 @@ +# Breaking changes + +List of breaking changes between major versions. + +## Planned Breaking API Changes (2.0) + +### `windowManager.getScaleFactor(monitor: number)` + +```typescript +// Deprecated +windowManager.getScaleFactor(windowManager.getActiveWindow().getMonitor()); +// Replace with +windowManager.getActiveWindow().getMonitor().getScaleFactor(); +``` + +### `window.getMonitor(): number` + +Now the `window.getMonitor` method returns [`Monitor`](monitor.md) object. + +### `windowManager.requestAccessibility()` `macOS` + +The `windowManager.requestAccessibility` method won't be required before each operation on windows anymore. Only on: + +- `window.setBounds` +- `window.maximize` +- `window.minimize` +- `window.restore` +- `window.bringToTop` +- `window.getTitle` \ No newline at end of file diff --git a/docs/window-manager.md b/docs/window-manager.md index e7fd4b6..172b4ce 100644 --- a/docs/window-manager.md +++ b/docs/window-manager.md @@ -16,7 +16,18 @@ console.log(window.getTitle()); ### Instance methods #### windowManager.requestAccessibility() `macOS` - Required before any action on macOS. + +If the accessibility permission is not granted on `macOS`, it opens an accessibility permission request dialog. + +The method is required to call before calling the following methods: + +- `window.setBounds` +- `window.maximize` +- `window.minimize` +- `window.restore` +- `window.bringToTop` +- `window.getTitle` + - Returns `boolean` #### windowManager.getActiveWindow() `Windows` `macOS` From d2af3c9a1f1ea36815dd0b3ed6dbed83890cc09e Mon Sep 17 00:00:00 2001 From: Sential Date: Sat, 14 Dec 2019 16:08:37 +0100 Subject: [PATCH 4/5] docs: improve the example in readme --- README.md | 15 +++++++++------ docs/breaking-changes.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index da454f1..2b63285 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,19 @@ The following example shows how to get the currently focused window's title and ```javascript const { windowManager } = require("node-window-manager"); -windowManager.requestAccessibility(); // required on macOS - const window = windowManager.getActiveWindow(); -// Prints the currently focused window title. -console.log(window.getTitle()); +// Prints the currently focused window bounds. +console.log(window.getBounds()); + +// This method has to be called on macOS before changing the window's bounds, otherwise it will throw an error. +// It will prompt an accessibility permission request dialog, if needed. +windowManager.requestAccessibility(); -// Moves the window. +// Sets the active window's bounds. window.setBounds({ x: 0, y: 0 }); ``` # Documentation -The documentation and API references are located in the [`docs`](docs) directory. \ No newline at end of file + +The documentation and API references are located in the [`docs`](docs) directory. diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 41482ab..2f53b82 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -26,4 +26,4 @@ The `windowManager.requestAccessibility` method won't be required before each op - `window.minimize` - `window.restore` - `window.bringToTop` -- `window.getTitle` \ No newline at end of file +- `window.getTitle` From 6c8cca1fb0dad300f689b3131707a46e48866c5c Mon Sep 17 00:00:00 2001 From: Sential Date: Sat, 14 Dec 2019 18:57:51 +0100 Subject: [PATCH 5/5] docs: remove getInfo method --- docs/breaking-changes.md | 19 +++++++++++++++---- docs/monitor-info.md | 5 ----- docs/monitor.md | 4 ---- docs/window-info.md | 8 -------- docs/window.md | 4 ---- 5 files changed, 15 insertions(+), 25 deletions(-) delete mode 100644 docs/monitor-info.md delete mode 100644 docs/window-info.md diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 2f53b82..2eef28f 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -13,10 +13,6 @@ windowManager.getScaleFactor(windowManager.getActiveWindow().getMonitor()); windowManager.getActiveWindow().getMonitor().getScaleFactor(); ``` -### `window.getMonitor(): number` - -Now the `window.getMonitor` method returns [`Monitor`](monitor.md) object. - ### `windowManager.requestAccessibility()` `macOS` The `windowManager.requestAccessibility` method won't be required before each operation on windows anymore. Only on: @@ -27,3 +23,18 @@ The `windowManager.requestAccessibility` method won't be required before each op - `window.restore` - `window.bringToTop` - `window.getTitle` + +### `window.getMonitor(): number` + +Now the `window.getMonitor` method returns [`Monitor`](monitor.md) object. + +### `window.getInfo()` + +`window.getInfo` method has been removed. + +```typescript +// Deprecated +const { title } = window.getInfo(); +// Replace with +const title = window.getTitle(); +``` diff --git a/docs/monitor-info.md b/docs/monitor-info.md deleted file mode 100644 index 82df485..0000000 --- a/docs/monitor-info.md +++ /dev/null @@ -1,5 +0,0 @@ -## Object `MonitorInfo` - -- `isPrimary` boolean -- `bounds` [`Rectangle`](rectangle.md) - the monitor position and bounds -- `workArea` [`Rectangle`](rectangle.md) - the monitor working area bounds diff --git a/docs/monitor.md b/docs/monitor.md index 3d68672..4c54f1d 100644 --- a/docs/monitor.md +++ b/docs/monitor.md @@ -29,10 +29,6 @@ Gets monitor working area bounds. - Returns [`Rectangle`](rectangle.md) -#### monitor.getInfo() `Windows` - -Returns [`MonitorInfo`](monitor-info.md) - #### monitor.isPrimary() `Windows` Whether the monitor is primary. diff --git a/docs/window-info.md b/docs/window-info.md deleted file mode 100644 index 7a398c0..0000000 --- a/docs/window-info.md +++ /dev/null @@ -1,8 +0,0 @@ -## Object `WindowInfo` - -- `title` string -- `processId` string -- `path` string - path to executable associated with the window -- `bounds` [`Rectangle`](rectangle.md) -- `opacity` number (`Windows`) -- `owner` [`Window`](window.md) (`Windows`) - owner window of the current window \ No newline at end of file diff --git a/docs/window.md b/docs/window.md index 4bba317..4555908 100644 --- a/docs/window.md +++ b/docs/window.md @@ -28,10 +28,6 @@ Resizes and moves the window to the supplied bounds. Any properties that are not window.setBounds({ height: 50 }); ``` -#### win.getInfo() `Windows` `macOS` - -Returns [`WindowInfo`](window-info.md) - #### win.getTitle() `Windows` `macOS` - Returns `string`