feat: add displays.mirror()

Author: codebytere

README.md

@@ -139,6 +139,23 @@ console.log(display)
 */
 ```
 
+### `displays.mirror(enable, firstID[, secondID])`
+
+* `enable` Boolean - Whether to enable or disable mirroring.
+* `firstID` Number - The device ID for the primary display. If no second display ID is provided, the first
+ display will default to the system's main display and the display corresponding to this ID will be set as the mirroring display.
+* `secondID` Number (optional) - The device ID for the secondary display (which will mirror the first).
+
+Example Usage:
+```js
+const displays = require('node-mac-displays')
+
+const [firstDisplay, secondDisplay] = displays.getAllDisplays()
+
+// Set the second display to mirror the first.
+displays.mirror(true, firstDisplay.id, secondDisplay.id)
+```
+
 ### `displays.screenshot(id, options)`
 
 * `id` Number - The device ID for the display.

displays.mm

@@ -4,6 +4,40 @@
 
 /***** HELPERS *****/
 
+// Converts a CGError to a human-readable string.
+std::string CGErrorToString(CGError err) {
+  if (err == kCGErrorCannotComplete) {
+    return "The requested operation is inappropriate for the parameters passed "
+           "in, or the current system state";
+  } else if (err == kCGErrorFailure) {
+    return "A general failure occurred";
+  } else if (err == kCGErrorIllegalArgument) {
+    return "One or more of the parameters passed to a function are invalid";
+  } else if (err == kCGErrorInvalidConnection) {
+    return "The parameter representing a connection to the window server is "
+           "invalid";
+  } else if (err == kCGErrorInvalidContext) {
+    return "The CPSProcessSerNum or context identifier parameter is not valid";
+  } else if (err == kCGErrorInvalidOperation) {
+    return "The requested operation is not valid for the parameters passed in, "
+           "or the current system state.";
+  } else if (err == kCGErrorNoneAvailable) {
+    return "The requested operation could not be completed as the indicated "
+           "resources were not found";
+  } else if (err == kCGErrorNotImplemented) {
+    return "Return value from obsolete function stubs present for binary "
+           "compatibility, but not typically called";
+  } else if (err == kCGErrorRangeCheck) {
+    return "A parameter passed in has a value that is inappropriate, or which "
+           "does not map to a useful operation or value";
+  } else if (err == kCGErrorTypeCheck) {
+    return "A data type or token was encountered that did not match the "
+           "expected type or token";
+  } else {
+    return "Unknown display configuration error";
+  }
+}
+
 // Converts a simple C array to a Napi::Array.
 template <typename T> Napi::Array CArrayToNapiArray(Napi::Env env, T *c_arr) {
   Napi::Array arr = Napi::Array::New(env, sizeof c_arr);
@@ -191,6 +225,45 @@ bool GetIsMonochrome() {
   return Napi::Object();
 }
 
+// Configure two macOS system displays to mirror status.
+void Mirror(const Napi::CallbackInfo &info) {
+  bool enable = info[0].As<Napi::Boolean>().Value();
+
+  uint32_t primary_display_id;
+  uint32_t secondary_display_id;
+  if (info.Length() == 3) {
+    primary_display_id = info[1].As<Napi::Number>().Uint32Value();
+    secondary_display_id = info[2].As<Napi::Number>().Uint32Value();
+  } else {
+    primary_display_id = CGMainDisplayID();
+    secondary_display_id = info[1].As<Napi::Number>().Uint32Value();
+  }
+
+  CGDisplayConfigRef config_ref;
+  CGError err = CGBeginDisplayConfiguration(&config_ref);
+  if (err != 0) {
+    Napi::Error::New(info.Env(), CGErrorToString(err))
+        .ThrowAsJavaScriptException();
+    return;
+  }
+
+  err = CGConfigureDisplayMirrorOfDisplay(config_ref, secondary_display_id,
+                                          enable ? primary_display_id
+                                                 : kCGNullDirectDisplay);
+  if (err != 0) {
+    Napi::Error::New(info.Env(), CGErrorToString(err))
+        .ThrowAsJavaScriptException();
+    return;
+  }
+
+  err = CGCompleteDisplayConfiguration(config_ref, kCGConfigurePermanently);
+  if (err != 0) {
+    Napi::Error::New(info.Env(), CGErrorToString(err))
+        .ThrowAsJavaScriptException();
+    return;
+  }
+}
+
 // Initializes all functions exposed to JS.
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set(Napi::String::New(env, "getAllDisplays"),
@@ -199,6 +272,8 @@ bool GetIsMonochrome() {
               Napi::Function::New(env, GetPrimaryDisplay));
   exports.Set(Napi::String::New(env, "getDisplayFromID"),
               Napi::Function::New(env, GetDisplayFromID));
+  exports.Set(Napi::String::New(env, "mirror"),
+              Napi::Function::New(env, Mirror));
   exports.Set(Napi::String::New(env, "screenshot"),
               Napi::Function::New(env, Screenshot));
 

index.js

@@ -8,6 +8,22 @@ function getDisplayFromID(id) {
   return displays.getDisplayFromID.call(this, id)
 }
 
+function mirror(enable, firstID, secondID) {
+  if (typeof enable !== 'boolean') {
+    throw new TypeError(`'enable' must be a boolean`)
+  }
+
+  if (typeof firstID !== 'number') {
+    throw new TypeError(`'firstID' must be a number`)
+  }
+
+  if (secondID && typeof secondID !== 'number') {
+    throw new TypeError(`'secondID' must be a number`)
+  }
+
+  displays.mirror.call(this, enable, firstID, secondID)
+}
+
 function screenshot(id, options = {}) {
   if (typeof id !== 'number') {
     throw new TypeError(`'id' must be a number`)
@@ -16,23 +32,23 @@ function screenshot(id, options = {}) {
   const validTypes = ['jpeg', 'tiff', 'png']
   if (options.type) {
     if (typeof options.type !== 'string') {
-      throw new Error(`'type' must be a string`)
+      throw new TypeError(`'type' must be a string`)
     } else if (!validTypes.includes(options.type)) {
-      throw new Error(`'type' must be one of ${validTypes.join(', ')}`)
+      throw new TypeError(`'type' must be one of ${validTypes.join(', ')}`)
     }
   }
 
   if (options.bounds) {
     if (typeof options.bounds !== 'object') {
-      throw new Error(`'bounds' must be a number`)
+      throw new TypeError(`'bounds' must be a number`)
     } else if (!options.bounds.x || typeof options.bounds.x !== 'number') {
-      throw new Error(`'bounds.x' must be a number`)
+      throw new TypeError(`'bounds.x' must be a number`)
     } else if (!options.bounds.y || typeof options.bounds.y !== 'number') {
-      throw new Error(`'bounds.y' must be a number`)
+      throw new TypeError(`'bounds.y' must be a number`)
     } else if (!options.bounds.width || typeof options.bounds.width !== 'number') {
-      throw new Error(`'bounds.width' must be a number`)
+      throw new TypeError(`'bounds.width' must be a number`)
     } else if (!options.bounds.height || typeof options.bounds.height !== 'number') {
-      throw new Error(`'bounds.height' must be a number`)
+      throw new TypeError(`'bounds.height' must be a number`)
     }
   }
 
@@ -43,5 +59,6 @@ module.exports = {
   getAllDisplays: displays.getAllDisplays,
   getPrimaryDisplay: displays.getPrimaryDisplay,
   getDisplayFromID,
+  mirror,
   screenshot,
 }

package.json

@@ -3,7 +3,6 @@
   "version": "1.0.0",
   "description": "A native Node.js module for enumerating over system display information",
   "main": "index.js",
-  "types": "index.d.ts",
   "scripts": {
     "build": "node-gyp rebuild",
     "clean": "node-gyp clean",

test/module.spec.js

@@ -1,7 +1,13 @@
 const { expect } = require('chai')
 const fs = require('fs')
 const path = require('path')
-const { getAllDisplays, getPrimaryDisplay, getDisplayFromID, screenshot } = require('../index')
+const {
+  getAllDisplays,
+  getPrimaryDisplay,
+  getDisplayFromID,
+  mirror,
+  screenshot,
+} = require('../index')
 
 describe('node-mac-displays', () => {
   describe('getAllDisplays', () => {
@@ -119,6 +125,27 @@ describe('node-mac-displays', () => {
     })
   })
 
+  describe('mirror', () => {
+    it('throws an error if enable is not a boolean', () => {
+      expect(() => {
+        mirror('im a string!!')
+      }).to.throw(`'enable' must be a boolean`)
+    })
+
+    it('throws an error if firstID is not valid', () => {
+      expect(() => {
+        mirror(true, 'bad-type')
+      }).to.throw(`'firstID' must be a number`)
+    })
+
+    it('throws an error if options.type is not valid', () => {
+      expect(() => {
+        const { id } = getPrimaryDisplay()
+        mirror(true, id, 'bad-type')
+      }).to.throw(`'secondID' must be a number`)
+    })
+  })
+
   describe('screenshot', () => {
     it('throws an error if id is not a number', () => {
       expect(() => {