Merge pull request #40 from ChapelR/v2.6.1

v2.6.1

Author: ChapelR

docs/README.md

@@ -1,4 +1,4 @@
-## Chapel's Custom Macro Collection (v2.6.0)
+## Chapel's Custom Macro Collection (v2.6.1)
 
 - [Try the demo!](https://macros.twinelab.net/demo) ([Sausage](https://github.com/ChapelR/custom-macros-demo))
 - [Downloads](./download ':ignore')
@@ -8,19 +8,19 @@
 ### Documentation
 - **Gameplay Systems and Mechanics**
   - [The Simple Inventory System](simple-inventory.md)
-  - Updated [The Cycles System](cycles-system.md) 
+  - [The Cycles System](cycles-system.md) 
   - [The Playtime System](playtime-system.md)
 - **Interface and Style**
   - [The Dialog API Macro Set](dialog-api-macro-set.md)
-  - New [The Popover Macro](popover.md)
+  - [The Popover Macro](popover.md)
   - [The UI Macro](ui-macro.md)
   - [The Fading Macro Set](fading-macros.md)
   - [The CSS Macro](css-macro.md)
   - [The Notify Macro](notify-macro.md)
   - [The Meter Macro Set](meter-macros.md)
   - [The Speech Box System](speech-box-system.md)
 - **User Interaction and Events**
-  - [The Event Macros](event-macros.md)
+  - *Updated!* [The Event Macros](event-macros.md)
   - [The Continue Macro Set](continue-macro.md)
   - [The Swap Macro Set](swap-macro-set.md)
   - [The Mouseover Macro](mouseover-macro.md)
@@ -30,7 +30,7 @@
   - [The Pronoun Templates](pronoun-templates.md)
   - [The Articles (A/An) Macros](articles.md)
 - **Utilities and Other**
-  - New [The Preload Macro](preload.md)
+  - [The Preload Macro](preload.md)
   - [The Done Macro](done-macro.md)
   - [The File System Macro Set](file-system-macros.md)
   - [The First Macro](first-macro.md)

docs/changelog.md

@@ -2,6 +2,14 @@
 
 [Back to the main page](./README.md).
 
+### August 2, 2020 (v2.6.1)
+
+- **[Update]** Updated the event macro set.
+  - Added `<<on>>`,`<<one>>`, and `<<off>>`. Deprecated `<<event>>`.
+  - Support for single-use event handlers.
+  - Added default namespaces.
+  - Internal improvements.
+
 ### July 24, 2020 (v2.6.0)
 
 - **[New]** New macros.

docs/event-macros.md

@@ -2,17 +2,17 @@
 
 [Back to the main readme](./README.md).
 
-This macro set allows Twine authors to create event programming without needing to use JavaScript or jQuery.
+This macro set allows Twine authors to create event handlers without needing to use JavaScript or jQuery.
 
 **THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/events.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/events.js).  
 **DEMO:** [Available](http://macros.twinelab.net/demo?macro=event).  
 **GUIDE:** Not available.
 
-### Macro: `<<event>>`
+### Macros: `<<on>>` and `<<one>>`
 
 **Syntax**:
 ```
-<<event type [selector]>>
+<<on type [selector] [once]>>
     ...
 	<<which keycode>>
 	    ...
@@ -21,27 +21,33 @@ This macro set allows Twine authors to create event programming without needing
 <</event>>
 ```
 
-This macro set can be used to add more interaction to your game; things like keyboard hotkeys, controls, clickable non-link elements, and more.  Once registered, events are essentially permanent (though they can be removed via JavaScript and suppressed via code logic); therefore, **the best place to create events is your StoryInit special passage**.  Note that the element the event is tied to does not need to be rendered (or currently on the page or in the passage) in order to attach an event to it.
+This macro be used to handle events in your game; things like keyboard hotkeys, controls, clickable non-link elements, and more. Note that the element the event is tied to does not need to be rendered (or currently on the page or in the passage) in order to attach an event to it.
 
-* **type**: a valid jQuery event type.  Some events that may be of interest:
+This macro has three aliases: `<<on>>` set recurring event handlers, while `<<one>>` creates a single-use event handler. If you want the handler to run each and every time the event occurs, use `<<on>>`. If you want the event to occur only once, the next time the event occurs, use `<<one>>`.
+
+> [!NOTE]
+> The `<<event>>` macro exists as an alias for `<<on>>` for backwards-compatibility with code written for older version of this macro set. The `<<event>>` macro should be considered deprecated going forward.
+
+* **type**: a valid jQuery event type. You may include a namespace with a dot, e.g., `click.my-namespace`.  Some events that may be of interest:
   * `click`: fires when an element is clicked on.
   * `dblclick`: fires when an element is double-clicked on.
   * `keyup`: fires when an key is pressed and released.
   * `keydown`: fires immediately when a key is pressed.
   * `mouseup`: fires when a mouse button is pressed and released.
   * `mousedown`: fires when a mouse button is pressed.
 * **selector**: (optional) a valid jQuery/CSS selector.  with some events (such as key presses), this checks for focus; with others it checks for the target element of the event (such as mouse clicks).  if no selector is provided, the event is bound to the document element.
+* **once**: (optional) the keyword `once`. If included, overrides the normal behavior of `<<on>>` (and `<<event>>`) to create a single-use event handler.
 * **keycode**: an integer.  allows you to determine which key or mouse button triggered the event and react accordingly.  you can find keycodes [here](http://keycode.info/).
 
 **Usage**:
 ```
 /% stow/unstow the ui-bar on double-click %/
-<<event 'dblclick' '#ui-bar'>>
+<<on 'dblclick' '#ui-bar'>>
     <<toggleclass '#ui-bar' 'stowed'>>
-<</event>>
+<</on>>
 
 /% set up some hotkeys %/
-<<event 'keyup'>>
+<<on 'keyup'>>
 <<which 67>> /% the c key %/
 	<<if not tags().includes('menu')>> /% avoid menu loop %/
 		<<goto 'character-menu'>>
@@ -52,17 +58,27 @@ This macro set can be used to add more interaction to your game; things like key
 	<</if>> 
 <<which 77>> /% the m key %/
 	<<masteraudio mute>>
-<</event>>
+<</on>>
+
+/% run one time %/
+<<one ':dialogclosed'>>
+	<<run UI.alert("You closed a dialog!")>>
+<</one>>
+
+/% the above could also be written: %/
+<<on ':dialogclosed' once>>
+	<<run UI.alert("You closed a dialog!")>>
+<</on>>
 ```
 
 ### Macro: `<<trigger>>`
 
-**Syntax**:`<<trigger (type) (optional: selector)>>`
+**Syntax**:`<<trigger type [selector]>>`
 
 Allows you to simulate any event on any element.  This macro is useful for triggering events you may not otherwise have easy access to.
 
 * **type**: a valid jQuery event type
-* **selector**: a valid jQuery/CSS selector.  if omitted, defaults to the document element
+* **selector**: (optional) a valid jQuery/CSS selector.  if omitted, defaults to the document element
 
 **Usage**:
 ```
@@ -71,4 +87,27 @@ Allows you to simulate any event on any element.  This macro is useful for trigg
 <<which 27>>
 	<<trigger 'click' '#ui-dialog-close'>>
 <</event>>
-```
+```
+
+### Macro: `<<off>>`
+
+**Syntax**:`<<off type [selector]>>`
+
+Allows you to remove an event handler.
+
+* **type**: a valid jQuery event type; may include namespaces
+* **selector**: (optional) a valid jQuery/CSS selector.  if omitted, defaults to the document element
+
+**Usage**:
+
+```
+/% removes all events created through this macro set %/
+<<off '.macro-event'>>
+
+/% remove all `dblclick` handlers from the `#ui-bar` element %/
+<<off 'dblclick' '#ui-bar'>>
+```
+
+### Setting: `setup.eventMacroNamespace`
+
+Handlers set up via this macro set are given a namespace automatically. The default value of this name space is `"macro-event"`. You may change this value to change the namespace if you want. Omit the dot.

scripts/events.js

@@ -1,65 +1,102 @@
 // event macro set, by chapel; for sugarcube 2
-// version 1.1.1
+// version 2.0.0
 
-// the <<trigger>> macro
-Macro.add('trigger', {
-    handler : function () {
-        
-        // declare vars
-        var evt, $el;
-        
-        // check for errors
-        if (this.args.length > 2 || this.args.length === 0) {
-            return this.error('incorrect number of arguments');
-        }
-        if (typeof this.args[0] != 'string') {
-            return this.error('first argument should be a string and a valid event type');
-        }
-        
-        // some setup
-        evt = this.args[0];
-        $el = (this.args.length === 1 ||
-            (this.args[1] && typeof this.args[1] === 'string' &&
-            this.args[1].toLowerCase().trim() === 'document')) ?
-            $(document) : $(this.args[1]);
-        
-        // fire the event
-        $el.trigger(evt);
-        
-    }
-});
+(function () {
+    setup.eventMacroNamespace = 'macro-event';
 
-// the <<event>> macro
-Macro.add('event', {
-       tags : ['which'],
-    handler : function () {
-        
-        var payload = this.payload;
-        var evt, sel = '', code = '', i;
-        
-        if (this.args.length > 2 || this.args.length === 0) {
-            return this.error('incorrect number of arguments');
-        }
-        if (typeof this.args[0] != 'string') {
-            return this.error('first argument should be a string and a valid event type');
-        }
-        if (this.args.length === 2 && typeof this.args[1] == 'string') {
-            sel = this.args[1];
+    // the <<trigger>> macro
+    Macro.add('trigger', {
+        handler : function () {
+            
+            // declare vars
+            var evt, $el;
+            
+            // check for errors
+            if (this.args.length > 2 || this.args.length === 0) {
+                return this.error('incorrect number of arguments');
+            }
+            if (typeof this.args[0] != 'string') {
+                return this.error('first argument should be a string and a valid event type');
+            }
+            
+            // some setup
+            evt = this.args[0];
+            $el = (this.args.length === 1 ||
+                (this.args[1] && typeof this.args[1] === 'string' &&
+                this.args[1].toLowerCase().trim() === 'document')) ?
+                $(document) : $(this.args[1]);
+            
+            // fire the event
+            $el.trigger(evt);
+            
         }
-        
-        evt = this.args[0];
-        
-        $(document).on(evt, sel, function (e) {
-            code = payload[0].contents;
-            if (payload.length > 1) {
-                for (i = 1; i < payload.length; i++) {
-                    if (payload[i].args.includes(e.which)) {
-                        code = code + payload[i].contents;
+    });
+
+    // the <<event>> macro: <<event type [selector] [once]>>
+    Macro.add(['event', 'on', 'one'], {
+           tags : ['which'],
+        handler : function () {
+            
+            var payload = this.payload;
+            var method = 'on';
+            var evt, sel = '', code = '', i;
+            
+            if (this.args.length > 3 || this.args.length === 0) {
+                return this.error('incorrect number of arguments');
+            }
+            if (typeof this.args[0] != 'string') {
+                return this.error('first argument should be a string and a valid event type');
+            }
+            if (this.args.length === 2 && typeof this.args[1] == 'string' && this.args[1] !== 'once') {
+                sel = this.args[1];
+            }
+            
+            if (this.args.includes('once') || this.name === 'one') {
+                method = 'one';
+            }
+
+            evt = this.args[0];
+            
+            $(document)[method](evt + '.' + setup.eventMacroNamespace, sel, function (e) {
+                code = payload[0].contents;
+                if (payload.length > 1) {
+                    for (i = 1; i < payload.length; i++) {
+                        if (payload[i].args.includes(e.which)) {
+                            code = code + payload[i].contents;
+                        }
                     }
                 }
+                new Wikifier(null, code);
+            });
+            
+        }
+    });
+
+    Macro.add('off', {
+        handler : function () {
+            
+            // declare vars
+            var evt, $el;
+            
+            // check for errors
+            if (this.args.length > 2 || this.args.length === 0) {
+                return this.error('incorrect number of arguments');
+            }
+            if (typeof this.args[0] != 'string') {
+                return this.error('first argument should be a string and a valid event type or namespace');
             }
-            new Wikifier(null, code);
-        });
-        
-    }
-});
+            
+            // some setup
+            evt = this.args[0];
+            $el = (this.args.length === 1 ||
+                (this.args[1] && typeof this.args[1] === 'string' &&
+                this.args[1].toLowerCase().trim() === 'document')) ?
+                $(document) : $(this.args[1]);
+            
+            // fire the event
+            $el.off(evt);
+            
+        }
+    });
+
+}());