Merge pull request #55 from EmulatorJS/custom-button-documentation

Updated documentation for the changes to the EJS_Buttons variable

Author: ethanaobrien

content/1.docs/7.options.md

@@ -1,5 +1,11 @@
 ## Main Options
 
+::alert{type="info"}
+  ::list{type="info"}
+  - **Note**: Some projects have been using internal API's not documented here. As these internal API's are undocumented, they are not guarrenteed to function the same between EmulatorJS versions. We *highly* recommend not using internal API's. If they are something your project relies upon, consider raising a Pull Request or Feature Request to have the API exposed public and documented here.
+  ::
+::
+
 ### `EJS_player`
 
 The selector of the element you want the emulator to be placed in.
@@ -483,6 +489,8 @@ Available control schemes: `nes` `gb`  `gba` `snes` `n64` `gba` `nds` `vb` `sega
 
 ### `EJS_Buttons`
 
+#### Version 4.2.1 and earlier
+
 Shows/hides buttons.
 
 - Type: `object`
@@ -512,6 +520,91 @@ EJS_Buttons = {
 }
 ```
 
+#### Version 4.2.2 and later
+
+Configures toolbar button icons, visibility, and custom call back functions to execute a custom action on the host page when a button is pressed (for example, automation of handling save files).
+
+Configurable buttons:
+| Name          | Notes         |
+| ------------- | ------------- |
+| `playPause`<br />`play`<br />`pause`     | `playPause` is an alias for two buttons named `play` and `pause`.<br /><br />Setting the visible attribute of `playPause` will set the visibility of `play` and `pause`, however `icon`, `displayName`, and `callback` need be configured individually for the `play` and `pause` buttons if different behaviour is required. |
+| `restart`      |               |
+| `mute`<br />`unmute`          | `mute` is an alias for two buttons named `mute` and `unmute`.<br /><br />Setting the visible attribute of `mute` will also set the visibility of `unmute`. The `icon`, `displayName` and `callback` attributes should be configured for `unmute` if different behaviour is required. |
+| `settings`      |               |
+| `fullscreen`<br />`enterFullscreen`<br />`exitFullscreen`    | `fullscreen` is an alias for two buttons named `enterFullscreen` and `exitFullscreen`.<br /><br />Setting the visible attribute of `fullscreen` will set the visibility of `enterFullscreen` and `exitFullscreen`, however `icon`, `displayName`, and `callback` will need to be configured individually for the `enterFullscreen` and `exitFullscreen` buttons if different behaviour is required. |
+| `saveState`     |               |
+| `loadState`     |               |
+| `screenRecord`  |               |
+| `gamepad`       |               |
+| `cheat`         |               |
+| `volume `       |               |
+| `saveSavFiles`  |               |
+| `loadSavFiles`  |               |
+| `quickSave`     |               |
+| `quickLoad`     |               |
+| `screenshot`    |               |
+| `cacheManager`  |               |
+| `exitEmulation` |               |
+
+Each button can accept either a boolean which controls the buttons visibility (as per behaviour in version 4.2.1 and earlier), or an array with the following elements:
+```js
+{
+    buttonName: {
+        visible: true,
+        icon: '<svg xml>',
+        displayName: "Button Name",
+        callback: () => {
+            console.log('Button clicked');
+        }
+    }
+}
+```
+
+Any undefined element will use the default behaviour for that button - for example, if `visible` is ommited, the button will be visibile.
+
+Custom buttons can be added by adding button elements with a unique name that's not on the above list. Custom buttons appear at the end of the toolbar, and require a name, icon, displayName, and callback to be provided.
+
+::alert{type="info"}
+  ::list{type="info"}
+  - Note that while the `displayName` value is localized using the EJS language files, if a `displayName` is used that's not available it will be displayed as provided. It is up to the developer to provide localized values for `displayName`.
+  ::
+::
+
+- Type: `object`
+- Default: `{}`
+- Examples:
+```js
+// show the saveState button, set the display name, and print a message to the console when clicked
+{
+    saveState: {
+        visible: true,
+        displayName: "Save State",
+        callback: () => {
+            console.log("The save state button was clicked");
+        }
+    }
+}
+```
+```js
+// hide the button
+{
+    saveState: false
+}
+```
+```js
+// Custom button
+{
+    customButton: {
+        visible: true,
+        displayName: "Custom Button",
+        icon: '<svg xml/>',
+        callback: () => {
+            console.log("The custom button was clicked");
+        }
+    }
+}
+```
+
 ### `EJS_defaultOptions`
 
 Sets the default settings menu options.