Namespace: Widgets

Widgets

LibEcho.Widgets provides a collection of useful SugarCube macros that don't really fit anywhere else.

For move in-depth examples, see the Test Story.


<<choose>>

<<choose [linkText [canon [ifExpr]]]>>
    arbitrary twinescript
<<or [linkText [canon [ifExpr]]]>>
    arbitrary twinescript
<<or ...>>
<</choose>>

Displays a bulleted list of choices. When one is selected, all the other choices are removed and the chosen one is grayed out. Then the twinescript in that particular choice body is evaluated and inserted into the page.

This macro is useful for building choice trees within a single passage.

linkText - The text to be displayed in the link.

canon - Passing 'canon' or a truthy value makes this a canon choice (marked as such in NewGame+ modes).

ifExpr - A quoted expression to evaluate. If the expression evaluates to a truthy value, then the choice is displayed. Otherwise, it is not.

Example:

<<choose "Yes." canon>>
	// Canon choice.
	You win!
<<or "No.">>
	You lose!
	// Build a choice tree by nesting calls to this macro.
	// If you are using tweego, you <<include>>ing sub-passages is useful for building recursive choice trees.
	Did you really want to pick that?!?
	<<choose "Yes">>
		You still lose then!
	<<or "No">>
		Yay!  You win after all!
	<</choose>>
<<or "Maybe?" noncanon "someVariable == 'something'">>
	// This choice only appears when <i>someVariable == 'something'</i>.
	You neither win nor lose???
<</choose>>

<<image>>

<<image [name [alignment [width [hspace="20em"]]]]>>

This macro displays an image.

name - The image name.

  • If an image passage with this name exists in the story, then it is displayed.
  • Otherwise, an external image tag is emitted, with a path of "<imageType>/<imageName>.<imageType>". Set LibEcho.Widgets.imageType in your initialization code to change <imageType>; it defaults to "webp". FIXME: This is a dumb way to handle this.

alignment - The image alignment: "left", "right", "center", or "none".

  • "left" and "right" will emit an "align=" attribute, causing text to wrap around the image.
  • "center" will wrap the image tag in a center tag, centering it without any text wrap.
  • "none" causes no alignment attributes or tags to be emitted at all.

width - A width to scale the image to.

hspace - Emits an "hspace=" attribute, set to the given value.

Example:

<<image "CoverPage">>
<<image "Walrus" right 300px >>

<<imagemap>>

<<imagemap name src [size="100%"]>>
    <<area name coords shape>>
        arbitrary twinescript
    <<area ...>>
<</imagemap>>

Displays an imagemap. When the defined areas are clicked, the twinescript in their body is silently evaluated.

This macro differs from SugarCube's implementation in that this macro can execute any arbitrary twinescript, without requiring a passage navigation to happen.

This macro depends on the external imageMapResizer library (https://github.com/davidjbradshaw/image-map-resizer). It's automagically compiled into LibEcho-Widgets, but if you're using this macro by itself then you'll have to include imageMapResizer in your Story Javascript.

name - A name for the map or area elements to be generated.

src - The path of the image to be used. This tries to detect between image passage and external images, but the code that does this is poor. FIXME: Change this to call out to the <<image>> macro instead.

size - The size to which the image should be scaled.

coords - The coordinates of the area being defined.

shape - The shape of the area being defined.

Example:

<<imagemap "floorplan" "floor-plan" "100%">>
	<<area "Bedroom" "62,76,402,460" "rect">>
		<<script>>
			Dialog.setup( "Bedroom" );
			Dialog.wiki( "It's the Bedroom!" );
			Dialog.open();
		<</script>>
	<<area "Living Room" "418,78,760,471" "rect">>
		<<script>>
			Dialog.setup( "Living Room" );
			Dialog.wiki( "It's the Living Room!" );
			Dialog.open();
		<</script>>
<</imagemap>>

<<multireturn>>

<<multireturn linkText>>

This macro solves the "<<return>> loop" problem. If you haven't encountered it before, you'll know when you do. :P

To use it, prepend your passage names with a single-word group identifier.

For example, start all of your side-menu passages with "StoryMenu", ie "StoryMenu Appearance", "StoryMenu Characters", etc.

Then instead of using <<return "Continue">> or somesuch, use <<multireturn "Continue">> instead. When you click the link, it will search back through your history and revisit the most recent passage that does NOT begin with the current passage's group identifier.

Example:

<<multireturn "Commit Changes.">>

<<popup>>

<<popup [passage [title=passage [allowClose=true [showDone=false]]]]>>
    arbitrary twinescript
<</popup>>

Immediately opens a modal dialog. When the dialog is closed, the twinescript in the macro body is silently evaluated.

passage - The name of the passage to be displayed in the modal dialog.

title - The title of the dialog. Defaults to the name of the passage being displayed in the dialog.

allowClose - Boolean value that selects whether or not the dialog can be closed via the X button or clicking somewhere off of it.

showDone - Boolean value that selects whether or not a "Done." link should be shown at the bottom of the dialog, which closes it when clicked.

Example:

<<popup "DeathScreen" "You Have Died!">>
    <<run Engine.restart()>>
<</popup>>

<<popuplink>>

<<popuplink [passage [title=passage [linkText=title [allowClose=true [showDone=false]]]]]>>
    arbitrary twinescript
<</popuplink>>

Inserts a link that, when clicked, will open a modal dialog. When the dialog is closed, the twinescript in the macro body is silently evaluated.

passage - The name of the passage to be displayed in the modal dialog.

title - The title of the dialog. Defaults to the name of the passage being displayed in the dialog.

linkText - The text of the link to be inserted. Defaults to the dialog title (or the passage name if no dialog title is specified).

allowClose - Boolean value that selects whether or not the dialog can be closed via the X button or clicking somewhere off of it.

showDone - Boolean value that selects whether or not a "Done." link should be shown at the bottom of the dialog, which closes it when clicked.

Example:

<<popuplink "DeathScreen" "You Have Died!" "Click here to die.">>
    <<run Engine.restart()>>
<</popuplink>>

<<unroll>>

<<unroll linkText>>
    arbitrary twinescript
<</unroll>>

This macro is obsolete. You probably ought to be using <<choose>> instead. It's much prettier!

This macro is a substitute for <<linkreplace>>, except that when you navigate backwards in the story history, all of the nodes automatically unroll so you don't have to click through a bunch of garbage over and over as you explore the different story branches.

<<choose>> cannot automatically unroll like that on back-navigation, so maybe this macro is still useful to someone.

Example:

There's some stuff going on.

<<unroll "What is going on?">>\
	You know.  Stuff.
	
	<<unroll "Oh, come on.  Tell me.">>\
		I lied.  There is nothing going on, and this macro is obsolete!
		
		[[Go to the next passage.->Next]]
	<</unroll>>
<</unroll>>

Source: