What is <<widget>>?

[summerstarlight]

Twine Version: 2.10
Sugarcube 2.37

Hello , I want to ask another stupid question…
What is <<widget>>? And how to use it? In what type of case to use it? Can you gave me sample of usage?

I read some forum & motoslave website, and general knowledge

I only knew widget is a macro, and it has args that has depreceated…

Registers the passage as <<widget>> macro definitions, which are loaded during startup
The special $args story variable has been deprecated in favor of the _args_ temporary variable.
"Widgets are macros.

Widgets are written and defined in twine script, while other “standard” macros are written in JavaScript. The widget macro automates the process of creating a macro, but limits your ability to use certain features; for example if you want to create a macro that has child tags, like <<if>> and <<else>>, you’re usually better off just making a macro in JavaScript."

sugarcube 2: What is the difference between widgets and macros? - Twine Forum

I read these, and someone else code that use <<widget>> but I still don’t understand, what it means, why they use it and what is <<widget>> used for…

When I search what is sugarcube widget, what is widget, it seems everyone already knew what its usage and context of it, is there a resource explaining what it means / definition? (Beside motoslave, i feel like elementary school reading university book)

[n-n]

You can think of a widget as a reusable block of display logic. For example, imagine we want to design an RPG combat interface like this:

Combat UI

In this case, the regions containing character information for the enemy and the player character use a similar format. We could write it each time we use it, but what if we have a variable number of characters? Should we change everything X times if we want to add a feature?

Now, widgets allow you to define that reusable piece of logic in one place:

Source code

:: StoryTitle
widgetdemo


:: StoryData
{
  "ifid": "ACC17125-5DB2-489D-AB0F-9DE09C090AA5",
  "format": "SugarCube",
  "format-version": "2.37.3",
  "start": "combat",
  "zoom": 1
}


:: combat {"position":"500,200","size":"100,100"}
<<set $player to {name:"FIGHTER", level: 1, hp: 15, hpMax: 20}>>\
<<set $enemy to {name:"ORC", level: 3, hp: 20, hpMax: 20}>>\

Combat screen of my super-awesome RPG.

<<profile $enemy>>\

[[FIGHT!->combat]]

<<profile $player>>\





:: profile [widget] {"position":"400,400","size":"100,100"}
<<widget "profile">>\
<<set _e to _args[0]>>\
<div style="padding:10px;border:solid 1px white;border-radius:20px; width:25%">\
<b>_e.name</b>
LEVEL: _e.level
HP: _e.hp / _e.hpMax
</div>\
<</widget>>

In this example, all the character presentation is encapsulated in the “profile” passage, and we can print a new character profile in combat using a <<profile _char>> macro, passing an object with the appropriate fields (in our game, name, level, hp and hpMax).

[manonamora (M.)]

Macros are code that lets you do stuff, like <<set>> creates variables/change values, or <<if>> makes conditional statements. They are general use, essentially, for anyone using SugarCube.

Because you can’t create macros for everything any user might need with SugarCube (sometimes what you need is super specific and a one-case-use), there’s the <<widget>> macro, where you can - in short - create your own macro to use in your project (and your project only). There are tons of different ways to use widgets in your project.

Inside widgets, you can have just text (to display on the page when used), a combination of text and code, or just code to run. It also accepts both SugarCube code (your basic macros and functions and APIs) and JavaScript code.

I usually use widgets when there’s a bit of code I’ll use in a bunch of different passages, but I don’t want to code it multiple times (helps avoid bugs between sections), or just hide huge chunks of codes in passages.

A dummy example of a widget:

    :: Widgets [widget]
    <<widget "SimonSays">>
        <<set _array to ["Raise your hands!", "Jump!", "Dance!"]>>
        <<print _array.random()>>
    <</widget>>

    :: Story Passage 
    > Simon says: <<SimonSays>>

This widget will essentially pick a random option from the array and display it on the page.

If you want to see some more complex widgets, check this source code (in there: a hangman, checking the value of some variables for a puzzle, lists of links to be used in different passages (so it’s only coded once)).

the $args being deprecated is because the code behind the <<widget>> macro changed between two versions of SugarCube. The warning is there just to remind people to use the proper formatting when using arguments (which is _args.

Also, I have a whole chapter with interactive examples in my guide.

[jeb019]

Basically, anytime you find yourself rewriting the same code in different passages, it should be made into a widget. Like Manon said, it can also greatly reduce bugs.

[summerstarlight]

Hello n-n thank you for helping
It’s easier to understand now , i’m curious about some parts of your code.

1. Do you need to write [widget] in your passage title to declare it’s a widget passage?

:: profile [widget] 

2. Why do you write {“position”:“400,400”,“size”:“100,100”}, in the passage title? Is it reminder for yourself or you need to do that too?

3. Why do you use args?

I understand it’s called arguments

Why do you use it in the

<<widget "profile">>\
<<set _e to _args[0]>>\

[summerstarlight]

Hello manonamora thank you for answering and for the resources
It is helpful! I think I got it, basically widget is custom template code.

I just read your guide a little bit, it is easier than motoslave, thank you for making tutorials, i appreciate it a lot.

I have some question about your args explaination

_args[] widgets
An argumented widget is used to create more complex but general macros. Arguments can be in the form of base value or variables, and will be stored in an array called _args[] (starting with the position 0).

From what i see, args is like index… But when i read your explaination i think there’s more to it…

But there’s no further explaination for args?
Why sometime it was used sometime it wasn’t? What is it actually for and do when you set it as _args[0]?

I read these and understand it’s about indexing

https://twinery.org/questions/33121/about-%24args-0

[summerstarlight]

Thank you jeb019

[n-n]

@summerstarlight

1. Do you need to write [widget] in your passage title to declare it’s a widget passage?

:: profile [widget] 

2. Why do you write {“position”:“400,400”,“size”:“100,100”}, in the passage title? Is it reminder for yourself or you need to do that too?
3. Why do you use args?

Questions 1 and 2 are related to the twee format.

1. The value in brackets is a tag. The important bit is that the “widget” tag is required on any passage that defines a widget.
2. That’s how the twee export function represents the position of the passages in the editor, working with the twine editor you don’t need to care.
3. _args (short for arguments) is the list of values that can be passed to a widget, it’s how you need to refer to them from the widget’s code.

In my example, the “profile” widget expects args to have one element (referred as _args[0]), of object type and containing some properties representing character data. I could have defined it so it expected the list of simple values, but I would have needed to remember the order, while objects are nice to structure information.

And inside the widget I assigned the object to a temporary variable because it’s easier (and more readable) to refer to _e than to _args[0]. I used _e as short for enemy, but it could be renamed to _c for character.

[summerstarlight]

Thank you very much n-n
Your explaination is easy to understand