Add a `<<select>>` macro

[tmedwards]

What it says on the tin.

<<select [optional_args]>>
	/*
		Links (<a> or <button>) and, optionally, descriptive text.
	*/
<<onselect>>
	/*
		Code to run if the player selects a link.
	*/
<<ontimeout>>
	/*
		Code to run if the `time` option is specified and the player fails to select a link in time.
	*/
<</select>>

Arguments

Optional

• text description: (string) The text to display to the player that must be clicked on to reveal the selection content. If not specified, the selection content is automatically displayed.
• id identifier: (string) The unique CSS/DOM ID assigned to the selection wrapper element.
• class classes: (string) The space separated list of CSS/DOM classes assigned to the selection wrapper element.
• time: (time unit) The time until the selections time out and are disabled, in CSS compatible time units—e.g., 10s. If the time is set to zero—e.g., 0s—then the timer is disabled and no timeout will occur.
• meter name: (bar|radial) The type of meter used to show the remaining time if the time option is specified. Defaults to bar.

Events

• If the player selects a link, a :select event will be fired from the selection wrapper.
• If the time option is specified and the player fails to select a link in time, a :selecttimeout event will be fired from the selection wrapper.

Notes

• If the time option is specified, the timer will start only once the selection contents are displayed and within view. Strolling the selection out of view, once started, does not affect the running timer.

Ideas

• Maybe change the name to avoid a clash with a 3rd-party macro—Sleepy's <<select>>. Possibilities: <<choose>>, <<event>>, …?

[hituro]

It would be great if it also fires an event when the timer runs out, passing the ID of the QTE that generated it

[SjoerdHekking]

Also, a possibility to pause the timer would be nice, reasoning an author could make an "extra time" button or some "easy" game mode!

[MalifaciousGames]

It'd be nice to have an easy way to disable the timer alltogether (maybe if the time value is false ?).

I can see qte timing being offered as a setting, going from fast to entirely disabled.

<<qte `(3* settings.qteSpeed)+'s'`>>...<</qte>>

[tmedwards]

Made some edits to the issue.

@hituro @SjoerdHekking @MalifaciousGames

[tmedwards]

It would be great if it also fires an event when the timer runs out, passing the ID of the QTE that generated it

The ID is optional, so that's a wash. The event target will be the wrapper element though, which is better anyway.

[david-donachie]

It would be great if it also fires an event when the timer runs out, passing the ID of the QTE that generated it

The ID is optional, so that's a wash. The event target will be the wrapper element though, which is better anyway.

Yeah, that makes sense

[tmedwards]

I'm thinking about using a button to unlock the content and timer rather than by scrolling into view. This would almost certainly be better in situations where there's considerable text before the QTE that the player may want or need to read—for the QTE to make sense.

[tmedwards]

Updates to the OP. The macro will be more generally useful.

Might change the name since Sleepy has a <<select>> macro. Dunno.

[greyelf]

Might change the name since Sleepy has a <<select>>

Maybe <<action>> as a potential name replacement.

[ChapelR]

Select doesn't seem like the right word to me, but I can't think of anything better, either. Not helpful, I know, but I'll think about it.

[david-donachie]

Name suggestions, some variant on "time limit"

• time-limit
• timeout
• deadline
• countdown (probably not)
• limit
• cutoff

[tmedwards]

Maybe <<action>> as a potential name replacement.

Too close to <<actions>>. I don't like one of the alternates I came up with, <<choose>>, for a similar reason—to close to <<choice>>.

I need to formally deprecate those two, so I can reuse the names someday.

 

Name suggestions, some variant on "time limit"

The current intent is a generic selection macro, so time-/duration-based names are a bust.

It still has a time option, so it can be a QTE, but that's not the sole thrust anymore.

[tmedwards]

Select doesn't seem like the right word to me, but I can't think of anything better, either. Not helpful, I know, but I'll think about it.

Please do. 🙏🏻

I hit the thesaurus already, but that was a bust. Then again, I was probably thinking too narrowly.

[david-donachie]

The current intent is a generic selection macro, so time-/duration-based names are a bust.

It still has a time option, so it can be a QTE, but that's not the sole thrust anymore.

Looking again, then, maybe right name is <<choices>>, as analogue to the existing <<actions>>.

Contents could then be links, <<link>>, buttons, <<button>> and <<choice>>. Rename <<onselect>> to something like <<any>> or <<after>> because it runs in addition to the whichever choice was selected.

Not to feature-creep, but if the same worked with <<radiobutton>> and <<checkbox>> you'd have also solved one of the most requested help features that pushes people to JS event handlers, namely the "How do I have something happen immediately when any one of these radiobuttons is chosen"

[MalifaciousGames]

I agree with Hituro in the sense that this feels like two macros in a trenchcoat:

• a <<qte>> macro, which would be a time-based vanishing link
• a listener container that is meant to catch click events on its contents (which could be anything)

It is true that limiting the qte target to being a link feels arbitrary, and it'd be convenient to be able to attach a click listener to any element.

But in this situation, a macro which could listen for any event type would solve more issues and have broader uses.

<<listen>>

  The answer is:
  <<numberbox '$var' 0>>

<<when 'change'>>

  <<if $var === 15>>
    <<goto 'GoodJob'>>
  <</if>>

<</listen>>

[tmedwards]

Looking again, then, maybe right name is <<choices>>, as analogue to the existing <<actions>>.

That's not happening for exactly the same reason I gave to Greyelf. It's too close to the name of an existing macro. Simply adding or removing an "s" is not sufficient.

I should have hard deprecated those two miserable things ages ago. Missed opportunity that. /sigh

 

Contents could then be links, <<link>>, buttons, <<button>> and <<choice>>.

The active contents, as noted above, are <a> & <button> elements, regardless of how they're created.

 

Rename <<onselect>> to something like <<any>> or <<after>> because it runs in addition to the whichever choice was selected.

I'll be sticking with the <<on…>> naming. I'm satisfied with that.

 

Not to feature-creep, but if the same worked with <<radiobutton>> and <<checkbox>> you'd have also solved one of the most requested help features that pushes people to JS event handlers, namely the "How do I have something happen immediately when any one of these radiobuttons is chosen"

That's not really feasible in v2 for a few reasons:

• Changing the existing macros to containers would break all existing uses.
• Adding a generic DOM event container macro to act as wrapper is not something I'm inclined to do for various reasons. The primary being, aside from the absolutely basic usage of "I saw an event", it's not significantly more friendly than JavaScript. I.e., once you get beyond simply executing a content section due to an event happening, you have to deal with the event object, and possibly arguments to the handler, and that's not going to be especially friendly no matter what you do. Besides, Chapel already has such a macro that's easily added.

My personal preference is targeted applications built into macros that need it rather than attempting to have some generic catch all that's not much better than using a little JavaScript. E.g., making <<textbox>> and <<radiobutton>> containers.

[tmedwards]

Maybe I should just suck it up and add an event wrapper macro as a stopgap in v2 until I can fix the core macro set in v3.

I just don't want to get into a situation where people are ~~doing dumb shit~~ cargo culting by combining macros that don't need to be combined, thus causing a mess.

Feh. 🤦🏻 Going to drive myself crazy with this.

[greyelf]

Another potential issue with the name <<select>> is the fact that HTML has a <select> element that behaves nothing like this macro.

[tmedwards]

The name's not going to be <<select>>, I just had to choose something after the scope changed.