Add initial touch bar docs

atom/browser/ui/cocoa/atom_touch_bar.mm

@@ -341,7 +341,7 @@ static NSTouchBarItemIdentifier SliderIdentifier = @"com.electron.touchbar.slide
     item.collapsedRepresentationImage = image.AsNSImage();
   }
 
-  bool showCloseButton;
+  bool showCloseButton = true;
   if (settings.Get("showCloseButton", &showCloseButton)) {
     item.showsCloseButton = showCloseButton;
   }

docs/api/browser-window.md

@@ -1270,7 +1270,8 @@ will remove the vibrancy effect on the window.
 
 * `touchBar` TouchBar
 
-Sets the touchBar layout for the current window.
+Sets the touchBar layout for the current window. Specifying `null` or
+`undefined` clears the touch bar.
 
 [blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62
 [quick-look]: https://en.wikipedia.org/wiki/Quick_Look

docs/api/touch-bar-button.md

@@ -0,0 +1,33 @@
+## Class: TouchBarButton
+
+> Create a button in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarButton(options)`
+
+* `options` Object
+  * `label` String (optional) - Button text.
+  * `backgroundColor` String (optional) - Button background color in hex format,
+    i.e `#ABCDEF`.
+  * `icon` NativeImage (optional) - Button icon.
+  * `click` Function (optional) - Function to call when the button is clicked.
+
+### Instance Properties
+
+The following properties are available on instances of `TouchBarButton`:
+
+#### `touchBarButton.label`
+
+The button's current text. Changing this value immediately updates the button
+in the touch bar.
+
+#### `touchBarButton.backgroundColor`
+
+The button's current background color. Changing this value immediately updates
+the button in the touch bar.
+
+#### `touchBarButton.icon`
+
+The button's current icon. Changing this value immediately updates the button
+in the touch bar.

docs/api/touch-bar-color-picker.md

@@ -0,0 +1,28 @@
+## Class: TouchBarColorPicker
+
+> Create a color picker in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarColorPicker(options)`
+
+* `options` Object
+  * `availableColors` String[] (optional) - Array of hex color strings to
+    appear as possible colors to select.
+  * `selectedColor` String (optional) - The selected hex color in the picker,
+    i.e `#ABCDEF`.
+  * `change` Function (optional) - Function to call when a color is selected.
+
+### Instance Properties
+
+The following properties are available on instances of `TouchBarColorPicker`:
+
+#### `touchBarColorPicker.availableColors`
+
+The color picker's available colors to select. Changing this value immediately
+updates the color picker in the touch bar.
+
+#### `touchBarColorPicker.selectedColor`
+
+The color picker's currently selected color. Changing this value immediately
+updates the color picker in the touch bar.

docs/api/touch-bar-group.md

@@ -0,0 +1,10 @@
+## Class: TouchBarGroup
+
+> Create a group in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarGroup(options)`
+
+* `options` Object
+  * `items` TouchBar - Items to display as a group.

docs/api/touch-bar-label.md

@@ -0,0 +1,19 @@
+## Class: TouchBarLabel
+
+> Create a label in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarLabel(options)`
+
+* `options` Object
+  * `label` String (optional) - Text to display.
+
+### Instance Properties
+
+The following properties are available on instances of `TouchBarLabel`:
+
+#### `touchBarLabel.label`
+
+The label's current text. Changing this value immediately updates the label in
+the touch bar.

docs/api/touch-bar-popover.md

@@ -0,0 +1,28 @@
+## Class: TouchBarPopover
+
+> Create a popover in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarPopover(options)`
+
+* `options` Object
+  * `label` String (optional) - Popover button text.
+  * `icon` NativeImage (optional) - Popover button icon.
+  * `items` TouchBar (optional) - Items to display in the popover.
+  * `showCloseButton` Boolean (optional) - `true` to display a close button
+    on the left of the popover, `false` to not show it. Default is `true`.
+
+### Instance Properties
+
+The following properties are available on instances of `TouchBarPopover`:
+
+#### `touchBarPopover.label`
+
+The popover's current button text. Changing this value immediately updates the
+popover in the touch bar.
+
+#### `touchBarPopover.icon`
+
+The popover's current button icon. Changing this value immediately updates the
+popover in the touch bar.

docs/api/touch-bar-slider.md

@@ -0,0 +1,38 @@
+## Class: TouchBarSlider
+
+> Create a slider in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarSlider(options)`
+
+* `options` Object
+  * `label` String (optional) - Label text.
+  * `value` Integer (optional) - Selected value.
+  * `minValue` Integer (optional) - Minimum value.
+  * `maxValue` Integer (optional) - Maximum value.
+  * `change` Function (optional) - Function to call when the slider is changed.
+
+### Instance Properties
+
+The following properties are available on instances of `TouchBarSlider`:
+
+#### `touchBarSlider.label`
+
+The slider's current text. Changing this value immediately updates the slider
+in the touch bar.
+
+#### `touchBarSlider.value`
+
+The slider's current value. Changing this value immediately updates the slider
+in the touch bar.
+
+#### `touchBarSlider.minValue`
+
+The slider's current minimum value. Changing this value immediately updates the
+slider in the touch bar.
+
+#### `touchBarSlider.maxValue`
+
+The slider's current maximum value. Changing this value immediately updates the
+slider in the touch bar.

docs/api/touch-bar-spacer.md

@@ -0,0 +1,13 @@
+## Class: TouchBarSpacer
+
+> Create a spacer between two items in the touch bar for native macOS applications
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+### `new TouchBarSlider(options)`
+
+* `options` Object
+  * `size` String (optional) - Size of spacer, possible values are:
+    * `small` - Small space between items.
+    * `large` - Large space between items.
+    * `flexible` - Take up all available space.

docs/api/touch-bar.md

@@ -6,39 +6,114 @@ Process: [Main](../tutorial/quick-start.md#main-process)
 
 ### `new TouchBar(items)`
 
-* `items` (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopOver | TouchBarSlider)[]
+* `items` (TouchBarButton | TouchBarColorPicker | TouchBarGroup | TouchBarLabel | TouchBarPopOver | TouchBarSlider | TouchBarSpacer)[]
 
-Creates a new touch bar.  Note any changes to the TouchBar instance
+Creates a new touch bar with the specified items. Use
-will not affect the rendered TouchBar.  To affect the rendered
+`BrowserWindow.setTouchBar` to add the `TouchBar` to a window.
-TouchBar you **must** use either methods on the TouchBar or methods
-on the TouchBar* items
-
-### Instance Methods
-
-The `menu` object has the following instance methods:
-
-#### `touchBar.destroy()`
-
-Immediately destroys the TouchBar instance and will reset the rendered
-touch bar.
 
 ## Examples
 
-The `TouchBar` class is only available in the main process, it is not currently possible to use in the renderer process **even** through the remote module.
+The `TouchBar` class is only available in the main process, it is not currently
+possible to use in the renderer process **even** through the remote module.
 
-### Main process
+Below is an example of a simple slot machine touch bar game with a button
-
+and some labels.
-An example of creating a touch bar in the main process:
 
 ```javascript
-const {TouchBar, TouchBarButton} = require('electron')
+const {app, BrowserWindow, TouchBar} = require('electron')
+
+const {TouchBarLabel, TouchBarButton, TouchBarSpacer} = TouchBar
+
+let spinning = false
+
+// Reel labels
+const reel1 = new TouchBarLabel()
+const reel2 = new TouchBarLabel()
+const reel3 = new TouchBarLabel()
+
+// Spin result label
+const result = new TouchBarLabel()
+
+// Spin button
+const spin = new TouchBarButton({
+  label: '🎰 Spin',
+  backgroundColor: '#7851A9',
+  click: () => {
+    // Ignore clicks if already spinning
+    if (spinning) {
+      return
+    }
+
+    spinning = true
+    result.label = ''
+
+    let timeout = 10
+    const spinLength = 4 * 1000 // 4 seconds
+    const startTime = Date.now()
+
+    const spinReels = () => {
+      updateReels()
+
+      if ((Date.now() - startTime) >= spinLength) {
+        finishSpin()
+      } else {
+        // Slow down a bit on each spin
+        timeout *= 1.1
+        setTimeout(spinReels, timeout)
+      }
+    }
+
+    spinReels()
+  }
+})
+
+const getRandomValue = () => {
+  const values = ['🍒', '💎', '7️⃣', '🍊', '🔔', '⭐', '🍇']
+  return values[Math.floor(Math.random() * values.length)]
+}
+
+const updateReels = () => {
+  reel1.label = getRandomValue()
+  reel2.label = getRandomValue()
+  reel3.label = getRandomValue()
+}
+
+const finishSpin = () => {
+  const uniqueValues = new Set([reel1.label, reel2.label, reel3.label]).size
+  if (uniqueValues === 1) {
+    // All 3 values are the same
+    result.label = '💰 Jackpot!'
+  } else if (uniqueValues === 2) {
+    // 2 values are the same
+    result.label = '😍 Winner!'
+  } else {
+    // No values are the same
+    result.label = '🙁 Spin Again'
+  }
+  spinning = false
+}
 
 const touchBar = new TouchBar([
-  new TouchBarButton({
+  spin,
-    label: 'Example Button',
+  new TouchBarSpacer({size: 'large'}),
-    click: () => console.log('I was clicked')
+  reel1,
-  })
+  reel2,
+  reel3,
+  new TouchBarSpacer({size: 'large'}),
+  result
 ])
 
-mainWindow.setTouchBar(touchBar)
+let window
+
+app.once('ready', () => {
+  window = new BrowserWindow({
+    frame: false,
+    titleBarStyle: 'hidden-inset',
+    width: 200,
+    height: 200,
+    backgroundColor: '#000'
+  })
+  window.loadURL('about:blank')
+  window.setTouchBar(touchBar)
+})
 ```

lib/browser/api/touch-bar.js

@@ -165,15 +165,6 @@ TouchBar.TouchBarLabel = class TouchBarLabel extends TouchBarItem {
   }
 }
 
-TouchBar.TouchBarSpacer = class TouchBarSpacer extends TouchBarItem {
-  constructor (config) {
-    super()
-    if (config == null) config = {}
-    this.type = 'spacer'
-    this._addLiveProperty('size', config.size)
-  }
-}
-
 TouchBar.TouchBarPopover = class TouchBarPopover extends TouchBarItem {
   constructor (config) {
     super()
@@ -209,4 +200,13 @@ TouchBar.TouchBarSlider = class TouchBarSlider extends TouchBarItem {
   }
 }
 
+TouchBar.TouchBarSpacer = class TouchBarSpacer extends TouchBarItem {
+  constructor (config) {
+    super()
+    if (config == null) config = {}
+    this.type = 'spacer'
+    this.size = config.size
+  }
+}
+
 module.exports = TouchBar