Skip to content

Commit

Permalink
Merge pull request #40 from ChapelR/v2.6.1
Browse files Browse the repository at this point in the history
v2.6.1
  • Loading branch information
ChapelR committed Aug 2, 2020
2 parents c363249 + 37438eb commit 73aa650
Show file tree
Hide file tree
Showing 28 changed files with 184 additions and 100 deletions.
10 changes: 5 additions & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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')
Expand All @@ -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)
Expand All @@ -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)
Expand Down
8 changes: 8 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
63 changes: 51 additions & 12 deletions docs/event-macros.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>>
...
Expand All @@ -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'>>
Expand All @@ -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**:
```
Expand All @@ -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.
153 changes: 95 additions & 58 deletions scripts/events.js
Original file line number Diff line number Diff line change
@@ -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);

}
});

}());
2 changes: 1 addition & 1 deletion scripts/minified/articles.min.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion scripts/minified/continue.min.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion scripts/minified/css-macro.min.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 73aa650

Please sign in to comment.