v1.1.2

- fixed issue w/ `options.controls.show` - updated documentation
ChapelR · Jan 31, 2019 · 7b223d7 · 7b223d7
1 parent 295eeff
commit 7b223d7
Show file tree

Hide file tree

Showing 8 changed files with 155 additions and 103 deletions.
diff --git a/dist/harlowe-audio.min.js b/dist/harlowe-audio.min.js
diff --git a/docs/README.md b/docs/README.md
@@ -702,6 +702,8 @@ Returns true if the playlist is currently being played in some fashion.
 
 ## Control Panel
 
+?> **Note:** These APIs are completely unavailable if `options.controls.show` is `false`.
+
 The control panel is a user interface for controlling the audio that is set up through this library. You can use it to give your players a mute button and a volume control without having to build these functions yourself.
 
 You may wish to alter the panels CSS to math your game. [Look here](https://github.com/ChapelR/harlowe-audio/blob/master/src/panel.css) to check out it's default styles.
@@ -756,7 +758,9 @@ This library adds a loading screen to Harlowe that is superficially similar to S
 
 ## The Menu API
 
-> TODO: Add this to the API section. Improve this aspect of the demo. Write code examples.
+?> **Note:** These APIs are completely unavailable if `options.controls.show` is `false`.
+
+?> **TODO:** Add this to the API section. Improve this aspect of the demo. Write code examples.
 
 This API allows you to add links to the sidebar as a 'story menu', similar to what can be done in SugarCube. THese links can be used to navigate to a passage, run a JavaScript function, or both. They can be hidden, shown, toggled, and removed at any time.
 
@@ -859,6 +863,43 @@ This method removes a story menu link. If there are multiple links with the same
 
 ---
 
+# Events
+
+There are two kinds of events that are triggered by HAL--events triggered on the document *only* and events triggered on *both* the track element and the document.
+
+## Event Handlers
+
+It is recommended that you write events using [jQuery's `on()`](http://api.jquery.com/on/) or [`one()` methods](http://api.jquery.com/one/). For example:
+
+```javascript
+$(document).on(':volume', function (ev) {
+    console.log('track "' + ev.track.$el.attr('data-track') + '"" volume changed');
+});
+```
+
+```javascript
+A.track('some-song').$el.one(':volume', function () {
+    console.log('track "some-song" volume changed');
+});
+```
+
+## List of Track Events
+
+These events are triggered on both the document and the track element. The track's definition is available as `<event>.track`.
+
+- `:available` -> a track's metadata is loaded  
+- `:loaded` -> a track can be played from start to finish  
+- `:play` -> a track starts playing  
+- `:pause` -> a track is paused  
+- `:stop` -> a track reaches the end or is stopped  
+- `:mute` -> a track is muted or unmuted  
+- `:volume` -> a track's volume is changed
+
+## Other Events
+
+- `:master-mute` -> the master mute control is muted or unmuted  
+- `:master-volume` -> the master volume is changed
+
 # Detailed Examples
 
 Some more detailed examples and explanations of common use-cases.

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,3 +1,9 @@
+## v1.1.2
+
+This patch addresses an issue where `options.controls.show` was throwing on false.
+
+The custom events emitted by HAL are now (somewhat) documented.
+
 ## v1.1.1
 
 This patch addresses a bug in the *track#fadeTo()* method.

diff --git a/src/setup.js b/src/setup.js
@@ -10,6 +10,8 @@
     });
 
     Chapel.Audio.classes.Track.renew();
-    Chapel.Audio.controls.updateVolume();
+    if (Chapel.Audio.controls) {
+        Chapel.Audio.controls.updateVolume();
+    }
 
 }());
diff --git a/src/userland.js b/src/userland.js
@@ -3,111 +3,114 @@
 
     // userland sidebar editing
 
-    var _engine = Engine;
+    if (options.controls.show) {
 
-    var $user = Chapel.Audio.controls.$user;
+        var _engine = Engine;
 
-    function checkDisp () {
-        // return true if user sidebar is displayed
-        return $user.css('display') !== 'none';
-    }
+        var $user = Chapel.Audio.controls.$user;
 
-    function showUserMenu () {
-        if (!checkDisp()) {
-            $user.css('display', 'block');
-        }
-        return $user;
-    }
+        var checkDisp = function () {
+            // return true if user sidebar is displayed
+            return $user.css('display') !== 'none';
+        };
 
-    function hideUserMenu () {
-        if (checkDisp()) {
-            $user.css('display', 'none');
-        }
-        return $user;
-    }
+        var showUserMenu = function () {
+            if (!checkDisp()) {
+                $user.css('display', 'block');
+            }
+            return $user;
+        };
 
-    function addLinks (text, psg, cb) {
-        // add tw-link elements to the userland sidebar area
-        var passage, callback;
-
-        if (!text || typeof text !== 'string') {
-            var msg = 'Cannot add a link with the text "' + (text === undefined) ? 'undefined' : JSON.stringify(text) + '".';
-            alert(msg);
-            console.error(msg);
-            return;
-        }
-
-        if (!cb && typeof psg === 'function') {
-            callback = psg;
-            passage = null;
-        } else {
-            if (psg && typeof psg === 'string') {
-                passage = psg;
+        var hideUserMenu = function () {
+            if (checkDisp()) {
+                $user.css('display', 'none');
             }
-            if (cb && typeof cb === 'function') {
-                callback = cb;
+            return $user;
+        };
+
+        var addLinks = function (text, psg, cb) {
+            // add tw-link elements to the userland sidebar area
+            var passage, callback;
+
+            if (!text || typeof text !== 'string') {
+                var msg = 'Cannot add a link with the text "' + (text === undefined) ? 'undefined' : JSON.stringify(text) + '".';
+                alert(msg);
+                console.error(msg);
+                return;
             }
-        }
-
-        var $link = $(document.createElement('tw-link'))
-            .append(text)
-            .attr({ 
-                tabindex : '0',
-                name : text.toLowerCase().trim()
-            })
-            .on('click', function () {
-                if (passage) {
-                    _engine.goToPassage(passage);
+
+            if (!cb && typeof psg === 'function') {
+                callback = psg;
+                passage = null;
+            } else {
+                if (psg && typeof psg === 'string') {
+                    passage = psg;
                 }
-                if (callback) {
-                    callback();
+                if (cb && typeof cb === 'function') {
+                    callback = cb;
                 }
-            })
-            .addClass('story-menu')
-            .appendTo($user);
-
-        showUserMenu();
-
-        return $link;
-    }
-
-    function clearLinks () {
-        $user.empty();
-        return hideUserMenu();
-    }
-
-    function hideLink (text) {
-        text = text.toLowerCase().trim();
-        $('tw-link.story-menu[name="' + text + '"]').addClass('hide');
-    }
-
-    function showLink (text) {
-        text = text.toLowerCase().trim();
-        $('tw-link.story-menu[name="' + text + '"]').removeClass('hide');
-    }
-
-    function toggleLink (text) {
-        text = text.toLowerCase().trim();
-        $('tw-link.story-menu[name="' + text + '"]').toggleClass('hide');
-    }
+            }
 
-    function deleteLink (text) {
-        text = text.toLowerCase().trim();
-        $('tw-link.story-menu[name="' + text + '"]').remove();
+            var $link = $(document.createElement('tw-link'))
+                .append(text)
+                .attr({ 
+                    tabindex : '0',
+                    name : text.toLowerCase().trim()
+                })
+                .on('click', function () {
+                    if (passage) {
+                        _engine.goToPassage(passage);
+                    }
+                    if (callback) {
+                        callback();
+                    }
+                })
+                .addClass('story-menu')
+                .appendTo($user);
+
+            showUserMenu();
+
+            return $link;
+        };
+
+        var clearLinks = function () {
+            $user.empty();
+            return hideUserMenu();
+        };
+
+        var hideLink = function (text) {
+            text = text.toLowerCase().trim();
+            $('tw-link.story-menu[name="' + text + '"]').addClass('hide');
+        };
+
+        var showLink = function (text) {
+            text = text.toLowerCase().trim();
+            $('tw-link.story-menu[name="' + text + '"]').removeClass('hide');
+        };
+
+        var toggleLink = function (text) {
+            text = text.toLowerCase().trim();
+            $('tw-link.story-menu[name="' + text + '"]').toggleClass('hide');
+        };
+
+        var deleteLink = function (text) {
+            text = text.toLowerCase().trim();
+            $('tw-link.story-menu[name="' + text + '"]').remove();
+        };
+
+        Chapel.Audio.menu = {
+            hide : hideUserMenu,
+            show : showUserMenu,
+            isShown : checkDisp,
+            links : {
+                add : addLinks,
+                clear : clearLinks,
+                hide : hideLink,
+                show : showLink,
+                toggle : toggleLink,
+                remove : deleteLink
+            }
+        };
     }
 
-    Chapel.Audio.menu = {
-        hide : hideUserMenu,
-        show : showUserMenu,
-        isShown : checkDisp,
-        links : {
-            add : addLinks,
-            clear : clearLinks,
-            hide : hideLink,
-            show : showLink,
-            toggle : toggleLink,
-            remove : deleteLink
-        }
-    };
-
 }());
diff --git a/src/wrap/min.js b/src/wrap/min.js
diff --git a/src/wrap/wrapper.js b/src/wrap/wrapper.js
@@ -1,6 +1,6 @@
 ;(function () {
     /**
-     * Harlowe Audio Library, by Chapel, v1.0.0
+     * Harlowe Audio Library, by Chapel, v1.1.2
      *
      * Released under the Unlicense, and dedicated to the public domain.
     **/

diff --git a/test/index.html b/test/index.html