diff --git a/README.md b/README.md index 27c9413..2b63285 100644 --- a/README.md +++ b/README.md @@ -17,210 +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 -## 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. diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md new file mode 100644 index 0000000..2eef28f --- /dev/null +++ b/docs/breaking-changes.md @@ -0,0 +1,40 @@ +# 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(); +``` + +### `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` + +### `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.md b/docs/monitor.md new file mode 100644 index 0000000..4c54f1d --- /dev/null +++ b/docs/monitor.md @@ -0,0 +1,42 @@ +## Class `Monitor` `Windows` + +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 + +### Instance properties + +- `id` number + +### Instance methods + +#### monitor.getBounds() `Windows` + +- Returns [`Rectangle`](rectangle.md) + +#### monitor.getWorkArea() `Windows` + +Gets monitor working area bounds. + +- Returns [`Rectangle`](rectangle.md) + +#### 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-manager.md b/docs/window-manager.md new file mode 100644 index 0000000..172b4ce --- /dev/null +++ b/docs/window-manager.md @@ -0,0 +1,57 @@ +## `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` + +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` + +- Returns [`Window`](window.md) + +#### windowManager.getWindows() `Windows` `macOS` + +- Returns [`Window[]`](window.md) + +#### windowManager.getMonitors() `Windows` + +- Returns [`Monitor[]`](monitor.md) + +#### windowManager.getPrimaryMonitor() `Windows` + +- Returns [`Monitor`](monitor.md) + +### Events + +#### Event 'window-activated' `Windows` `macOS` + +Returns: + +- [`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 new file mode 100644 index 0000000..4555908 --- /dev/null +++ b/docs/window.md @@ -0,0 +1,97 @@ +## Class `Window` + +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. + +### 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.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`](monitor.md) + +#### 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` + +#### win.setOwner(win: Window | number | null) `Windows` + +- `win` Window | number | null + - pass null to unset window owner. + +#### win.getIcon(size: number) `Windows` `macOS` + +- `size` number - can be `16`, `32`, `64` or `256`. By default it's `64`. + +Returns a png Buffer \ No newline at end of file