📝 How window-manager.js works

Author: imlucas

src/electron/window-manager.js

@@ -1,31 +1,74 @@
+/**
+ * A high-level wrapper around electron's builtin
+ * [BrowserWindow](https://github.com/atom/electron/blob/master/docs/api/browser-window.md)
+ * class
+ */
+var path = require('path');
 var _ = require('lodash');
-
-var BrowserWindow = require('browser-window');
 var app = require('app');
-var debug = require('debug')('scout-electron:window-manager');
 var attachMenu = require('./menu');
-var path = require('path');
+var BrowserWindow = require('browser-window');
+var debug = require('debug')('scout-electron:window-manager');
 
+/**
+ * When running in electron, we're in `RESOURCES/src/electron`.
+ */
 var RESOURCES = path.resolve(__dirname, '../../');
+
+/**
+ * The app's HTML shell which is the output of `./src/index.jade`
+ * created by the `build:pages` gulp task.
+ */
 var DEFAULT_URL = 'file://' + path.join(RESOURCES, 'index.html#connect');
 
+/**
+ * The outer dimensions to use for new windows.
+ */
 var DEFAULT_WIDTH = 1024;
 var DEFAULT_HEIGHT = 700;
 
-var DEFAULT_HEIGHT_DIALOG;
-
-if (process.platform === 'win32') {
-  DEFAULT_HEIGHT_DIALOG = 500;
-} else if (process.platform === 'linux') {
-  DEFAULT_HEIGHT_DIALOG = 470;
-} else {
-  DEFAULT_HEIGHT_DIALOG = 440;
-}
+/**
+ * The outer window dimensions to use for new dialog
+ * windows like the connection and setup dialogs.
+ */
 var DEFAULT_WIDTH_DIALOG = 640;
+var DEFAULT_HEIGHT_DIALOG = 600;
+/**
+ * Adjust the heights to account for platforms
+ * that use a single menu bar at the top of the screen.
+ */
+if (process.platform === 'linux') {
+  DEFAULT_HEIGHT_DIALOG -= 30;
+  DEFAULT_HEIGHT -= 30;
+} else if (process.platform === 'darwin') {
+  DEFAULT_HEIGHT_DIALOG -= 60;
+  DEFAULT_HEIGHT -= 60;
+}
 
+/**
+ * We want want the Connect dialog window to be special
+ * and for there to ever only be one instance of it
+ * so we'll use scope to essentially make it a Singleton.
+ */
 var connectWindow;
+
+// @todo (imlucas): Removed in setup branch as we dont need to do this anymore
+// as a `all-windows-closed` event has been added to the `app` event api
+// since this code was laid down.
 var windowsOpenCount = 0;
 
+/**
+ * Call me instead of using `new BrowserWindow()` directly because i'll:
+ *
+ * 1. Make sure the window is the right size
+ * 2. Doesn't load a blank screen
+ * 3. Overrides `window.open` so we have control over message passing via URL's
+
+ *
+ * @param {Object} opts - Smaller subset of [`BrowserWindow#options`][0].
+ * @return {BrowserWindow}
+ * [0]: http://git.io/vnwTY
+ */
 module.exports.create = function(opts) {
   opts = _.defaults(opts || {}, {
     width: DEFAULT_WIDTH,
@@ -49,6 +92,7 @@ module.exports.create = function(opts) {
     debug('intercepting new-window (disregard the "error" message '
       + 'preventDefault is about to cause)');
     event.preventDefault();
+
     module.exports.create({
       url: 'file://' + RESOURCES + '/index.html' + decodeURIComponent(url.replace('file://', ''))
     });
@@ -61,6 +105,8 @@ module.exports.create = function(opts) {
       connectWindow = null;
     });
   }
+
+  // @see `all-windows-closed` above
   windowsOpenCount++;
   _window.on('closed', function() {
     windowsOpenCount--;
@@ -87,6 +133,12 @@ app.on('show connect dialog', function(opts) {
   module.exports.create(opts);
 });
 
+/**
+ * When electron's main renderer has completed setup,
+ * we'll always show the [connect][./src/connect] dialog
+ * on start which is responsible for retaining it's own
+ * state between application launches.
+ */
 app.on('ready', function() {
   app.emit('show connect dialog');
 });