From c118a47790a4bbaa939621e07cd74906434f3df8 Mon Sep 17 00:00:00 2001
From: Pascal Thomet <pthomet@gmail.com>
Date: Thu, 7 Dec 2023 03:01:35 +0100
Subject: [PATCH] Add doc about  assets/app_settings/emscripten

---
 README.md                                     | 45 +++++++------
 README.src.md                                 | 45 +++++++------
 _example_integration/Readme.md                | 30 +++++----
 .../assets/app_settings/emscripten/custom.js  |  1 +
 .../emscripten/shell.emscripten.html          | 66 +++++++++++++++++++
 5 files changed, 138 insertions(+), 49 deletions(-)
 create mode 100644 _example_integration/assets/app_settings/emscripten/custom.js
 create mode 100644 _example_integration/assets/app_settings/emscripten/shell.emscripten.html

diff --git a/README.md b/README.md
index c3fc4bd1..7dc4cb00 100644
--- a/README.md
+++ b/README.md
@@ -151,7 +151,7 @@ Anything in the assets/ folder located beside the app's CMakeLists will be embed
 └── hello_globe.main.cpp
 ├── CMakeLists.txt
 ├── assets/
-│         └── world.jpg
+│    └── world.jpg
 ```
 (even on iOS and emscripten).
 
@@ -224,19 +224,26 @@ Example:
 ```
 assets/
 ├── app_settings/
-│         ├── icon.png          # If present, this will be used as the app icon.
-│         │                     # Tt should be a square image, of large size, e.g. 1024x1024.
-│         │                     # This works on macOS, iOS, windows, linux, and emscripten 
-│         │                     # and it will automatically 
-│         │                     # be converted to the correct format.
-│         │
-│         ├── apple/
-│         │         ├── Info.plist         # Will be used as the app Info.plist for iOS and macOS
-│         │         │                      # (if absent, HelloImGui will provide a default one)
-│         │         │
-│         │         ├── Info.ios.plist     # (optional, used on iOS if present)
-│         │         ├── Info.macos.plist   # (optional, used on macOS if present) 
-│         │ 
+│    ├── icon.png          # If present, this will be used as the app icon.
+│    │                     # Tt should be a square image, of large size, at least 256x256.
+│    │                     # This works on macOS, iOS, windows, linux, and emscripten 
+│    │                     # and it will automatically 
+│    │                     # be converted to the correct format.
+│    │
+│    ├── apple/
+│    │    ├── Info.plist    # Will be used as the app Info.plist for iOS and macOS
+│    │    │                      # (if absent, HelloImGui will provide a default one)
+│    │    │
+│    │    ├── Info.ios.plist     # (optional, used on iOS if present)
+│    │    ├── Info.macos.plist   # (optional, used on macOS if present) 
+│    │ 
+│    └── emscripten/
+│        ├── shell.emscripten.html # Emscripten shell file
+│        │                         #   (this file will be cmake "configured"
+│        │                         #    to add the name and favicon) 
+│        └── custom.js             # Any custom file here will be deployed
+│                                  #   in the emscripten build folder
+
 ```
 
 -------------------
@@ -523,12 +530,12 @@ For Android, create a folder named "android" beside the application 'CMakeLists.
 
 ```
 ├── android/                                    # android/ is where you customize the Android App
-│         ├── mipmap-source/
-│         │         ├── Readme.md
-│         │         └── ic_launcher.png                     # an icon that helps creating the different sizes
-│         └── res/                                    # anything in the res/ folder will be embedded as a resource
+│    ├── mipmap-source/
+│    │    ├── Readme.md
+│    │    └── ic_launcher.png                     # an icon that helps creating the different sizes
+│    └── res/                                    # anything in the res/ folder will be embedded as a resource
 │             ├── mipmap-hdpi/
-│             │         └── ic_launcher.png                 # icons with different sizes
+│             │    └── ic_launcher.png                 # icons with different sizes
 │             ├── mipmap-.../
 │             └── values/
 │                 ├── colors.xml
diff --git a/README.src.md b/README.src.md
index 456467b9..77bf10be 100644
--- a/README.src.md
+++ b/README.src.md
@@ -128,7 +128,7 @@ Anything in the assets/ folder located beside the app's CMakeLists will be embed
 └── hello_globe.main.cpp
 ├── CMakeLists.txt
 ├── assets/
-│         └── world.jpg
+│    └── world.jpg
 ```
 (even on iOS and emscripten).
 
@@ -201,19 +201,26 @@ Example:
 ```
 assets/
 ├── app_settings/
-│         ├── icon.png          # If present, this will be used as the app icon.
-│         │                     # Tt should be a square image, of large size, e.g. 1024x1024.
-│         │                     # This works on macOS, iOS, windows, linux, and emscripten 
-│         │                     # and it will automatically 
-│         │                     # be converted to the correct format.
-│         │
-│         ├── apple/
-│         │         ├── Info.plist         # Will be used as the app Info.plist for iOS and macOS
-│         │         │                      # (if absent, HelloImGui will provide a default one)
-│         │         │
-│         │         ├── Info.ios.plist     # (optional, used on iOS if present)
-│         │         ├── Info.macos.plist   # (optional, used on macOS if present) 
-│         │ 
+│    ├── icon.png          # If present, this will be used as the app icon.
+│    │                     # Tt should be a square image, of large size, at least 256x256.
+│    │                     # This works on macOS, iOS, windows, linux, and emscripten 
+│    │                     # and it will automatically 
+│    │                     # be converted to the correct format.
+│    │
+│    ├── apple/
+│    │    ├── Info.plist    # Will be used as the app Info.plist for iOS and macOS
+│    │    │                      # (if absent, HelloImGui will provide a default one)
+│    │    │
+│    │    ├── Info.ios.plist     # (optional, used on iOS if present)
+│    │    ├── Info.macos.plist   # (optional, used on macOS if present) 
+│    │ 
+│    └── emscripten/
+│        ├── shell.emscripten.html # Emscripten shell file
+│        │                         #   (this file will be cmake "configured"
+│        │                         #    to add the name and favicon) 
+│        └── custom.js             # Any custom file here will be deployed
+│                                  #   in the emscripten build folder
+
 ```
 
 -------------------
@@ -462,12 +469,12 @@ For Android, create a folder named "android" beside the application 'CMakeLists.
 
 ```
 ├── android/                                    # android/ is where you customize the Android App
-│         ├── mipmap-source/
-│         │         ├── Readme.md
-│         │         └── ic_launcher.png                     # an icon that helps creating the different sizes
-│         └── res/                                    # anything in the res/ folder will be embedded as a resource
+│    ├── mipmap-source/
+│    │    ├── Readme.md
+│    │    └── ic_launcher.png                     # an icon that helps creating the different sizes
+│    └── res/                                    # anything in the res/ folder will be embedded as a resource
 │             ├── mipmap-hdpi/
-│             │         └── ic_launcher.png                 # icons with different sizes
+│             │    └── ic_launcher.png                 # icons with different sizes
 │             ├── mipmap-.../
 │             └── values/
 │                 ├── colors.xml
diff --git a/_example_integration/Readme.md b/_example_integration/Readme.md
index 1a0ca111..5ba1a6d0 100644
--- a/_example_integration/Readme.md
+++ b/_example_integration/Readme.md
@@ -17,21 +17,29 @@ The [CMakeLists.txt](CMakeLists.txt) file will download and build hello_imgui at
  
 
 Anything in the assets/ folder located beside the app's CMakeLists will be bundled together with the app (for macOS, iOS, Android, Emscripten).
-The files in assets/app_settings/ will be used to generate the app icon, and the app settings (for macOS, iOS, Android).
+The files in assets/app_settings/ will be used to generate the app icon, and the app settings.
 
 ```
 assets/
-├── world.jpg                         # A custom asset
-├── app_settings/                     # Application settings
-│         ├── icon.png                # This will be the app icon, it should be square
-│         │                           # and at least 512x512. It will  be converted
-│         │                           # to the right format, for each platform.
-│         ├── apple/
-│         │         └── Info.plist    # macOS and iOS app settings
-│         │                          # (or Info.ios.plist + Info.macos.plist)
+├── world.jpg                   # A custom asset
+│
+├── app_settings/               # Application settings
+│    ├── icon.png               # This will be the app icon, it should be square
+│    │                          # and at least 256x256. It will  be converted
+│    │                          # to the right format, for each platform.
+│    ├── apple/
+│    │    └── Info.plist        # macOS and iOS app settings
+│    │                          # (or Info.ios.plist + Info.macos.plist)
+│    └── emscripten/
+│        ├── shell.emscripten.html # Emscripten shell file
+│        │                         #   (this file will be cmake "configured"
+│        │                         #    to add the name and favicon) 
+│        └── custom.js             # Any custom file here will be deployed
+│                                  #   in the emscripten build folder
+│
 ├── fonts/
-│         ├── DroidSans.ttf           # Default fonts
-│         └── fontawesome-webfont.ttf #     used by HelloImGui
+│    ├── DroidSans.ttf           # Default fonts
+│    └── fontawesome-webfont.ttf #   used by HelloImGui
 ```
 
 ### Standard usage
diff --git a/_example_integration/assets/app_settings/emscripten/custom.js b/_example_integration/assets/app_settings/emscripten/custom.js
new file mode 100644
index 00000000..10043b0a
--- /dev/null
+++ b/_example_integration/assets/app_settings/emscripten/custom.js
@@ -0,0 +1 @@
+// Any file in this directory will be copied to the app build directory
diff --git a/_example_integration/assets/app_settings/emscripten/shell.emscripten.html b/_example_integration/assets/app_settings/emscripten/shell.emscripten.html
new file mode 100644
index 00000000..2973b2ff
--- /dev/null
+++ b/_example_integration/assets/app_settings/emscripten/shell.emscripten.html
@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en-us">
+<head>
+    <link rel="icon" type="image/x-icon" href="@HELLO_IMGUI_FAVICON@">
+    <!--
+    You could include your own custom CSS and JS here, e.g.:
+    <script src="custom.js"></script>
+
+    Any file located in assets/app_settings/emscripten/ will be copied to the build directory.
+    -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no"/>
+    <title>@HELLO_IMGUI_ICON_DISPLAY_NAME@</title>
+    <style>
+        body { margin: 0; background-color: black }
+        .emscripten {
+            position: absolute;
+            top: 0px;
+            left: 0px;
+            margin: 0px;
+            border: 0;
+            width: 100%;
+            height: 100%;
+            overflow: hidden;
+            display: block;
+            image-rendering: optimizeSpeed;
+            image-rendering: crisp-edges;
+            -ms-interpolation-mode: nearest-neighbor;
+        }
+    </style>
+</head>
+<body>
+<canvas class="emscripten" id="canvas" oncontextmenu="event.preventDefault()"></canvas>
+<script type='text/javascript'>
+    var Module = {
+        preRun: [],
+        postRun: [],
+        print: (function() {
+            return function(text) {
+                text = Array.prototype.slice.call(arguments).join(' ');
+                console.log(text);
+            };
+        })(),
+        printErr: function(text) {
+            text = Array.prototype.slice.call(arguments).join(' ');
+            console.error(text);
+        },
+        canvas: (function() {
+            var canvas = document.getElementById('canvas');
+            //canvas.addEventListener("webglcontextlost", function(e) { alert('FIXME: WebGL context lost, please reload the page'); e.preventDefault(); }, false);
+            return canvas;
+        })(),
+        setStatus: function(text) {
+            console.log("status: " + text);
+        },
+        monitorRunDependencies: function(left) {
+            // no run dependencies to log
+        }
+    };
+    window.onerror = function() {
+        console.log("onerror: " + event);
+    };
+</script>
+{{{ SCRIPT }}}
+</body>
+</html>