Merge branch 'origin/main' into translate

Author: allancoding

.github/workflows/newlines.yml

@@ -0,0 +1,42 @@
+name: Check for Newline at End of Files
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+jobs:
+  check-newlines:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Check for missing newlines
+        run: |
+          files=$(git ls-files)
+
+          newline_error=0
+
+          for file in $files; do
+            if file --mime "$file" | grep -q "binary"; then
+              #echo "Skipping binary file: $file"
+              continue
+            fi
+
+            last_char=$(tail -c 1 "$file" | xxd -p)
+            if [[ "$last_char" != "0a" ]]; then
+              echo "File $file does not end with a newline!"
+              newline_error=1
+            fi
+          done
+
+          if [[ $newline_error -eq 1 ]]; then
+            echo "One or more files do not end with a newline."
+            exit 1
+          else
+            echo "All files end with a newline."
+          fi

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.