Add-ons / Event Macros

This macro set allows Twine authors to create event handlers without needing to use JavaScript or jQuery.

Author ChapelR
Website https://twinelab.net/custom-macros-for-sugarcube-2/#/event-macros
Story format SugarCube 2
Last checked Thu Jul 21 2022
License Unlicense
Download event.zip

Index

Overview

This macro set allows Twine authors to create event handlers without needing to use JavaScript or jQuery.

Macros

<<on>>

<<on>>

Syntax:

<<on type [selector] [once]>>
    ...
    <<which keycode>>
        ...
    <<which keycode>>
        ...
<</on>>

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.

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.

Arguments:

Usage:

/% stow/unstow the ui-bar on double-click %/
<<on 'dblclick' '#ui-bar'>>
    <<toggleclass '#ui-bar' 'stowed'>>
<</on>>

/% set up some hotkeys %/
<<on 'keyup'>>
<<which 67>> /% the c key %/
    <<if not tags().includes('menu')>> /% avoid menu loop %/
        <<goto 'character-menu'>>
    <</if>>
<<which 83>> /% the s key %/
    <<if not tags().includes('menu')>> /% avoid menu loop %/
        <<goto 'spells-menu'>>
    <</if>>
<<which 77>> /% the m key %/
    <<masteraudio mute>>
<</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>>

READ: Documentation

<<one>>

<<one>>

Syntax:

<<on type [selector] [once]>>
    ...
    <<which keycode>>
        ...
    <<which keycode>>
        ...
<</on>>

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.

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.

Arguments:

Usage:

/% stow/unstow the ui-bar on double-click %/
<<on 'dblclick' '#ui-bar'>>
    <<toggleclass '#ui-bar' 'stowed'>>
<</on>>

/% set up some hotkeys %/
<<on 'keyup'>>
<<which 67>> /% the c key %/
    <<if not tags().includes('menu')>> /% avoid menu loop %/
        <<goto 'character-menu'>>
    <</if>>
<<which 83>> /% the s key %/
    <<if not tags().includes('menu')>> /% avoid menu loop %/
        <<goto 'spells-menu'>>
    <</if>>
<<which 77>> /% the m key %/
    <<masteraudio mute>>
<</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>>

READ: Documentation

<<event>>

<<event>>

⚠️ Attention: 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.

<<trigger>>

<<trigger>>

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.

Arguments:

Usage:

/% close any dialog box when the player presses esc %/
<<on 'keydown'>>
<<which 27>>
    <<trigger 'click' '#ui-dialog-close'>>
<</on>>

READ: Documentation

<<off>>

<<off>>

Syntax: <<off type [selector]>>

Allows you to remove an event handler.

Arguments:

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'>>

READ: Documentation

Settings

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.

Live demo

Demo Twee code:

:: Start
@@#eventmacro;Double-click this text to hide/show the side bar.@@
<<on 'dblclick' '#eventmacro'>><<toggleclass '#ui-bar' 'stowed'>><</on>>\