Let's start with some context. All of the contraptions in WigglyKit share the convention of an "animation value"  consisting of a dictionary with the keys "frames" (a list of images) and "order" (a list of integers; indices into the list "frames"). There's nothing intrinsically special about this dictionary; it's just a convention to bundle together all the relevant information for a wiggly animation such that it can be easily moved around between those contraptions and manipulated with scripts.

WigglyKit offers an example of pulling the animation value out of a WigglyCanvas and then saving it as a GIF:

v:wc.value
# (optionally) make the background opaque:
v.frames:v.frames..copy[].map[0 dict 32]
gif.frames:v.frames @ v.order
gif.delays:10
write[gif]

As noted in the Decker reference manual for the built-in function write[] (see note 12), to save an animated GIF we need to call write[] with a dictionary with the keys "frames" (a list of images) and "delays" (a list of integers; how many 100ths of a second should each frame be displayed?)

So really, what we need to do to save a GIF outside the specific context of WigglyKit is make an appropriately-shaped dictionary and hand it to write[]:

gif.frames: ... # obtain or assemble a list of images, somehow
gif.delays: 10  # one number applies the delay to every frame
write[gif]

Obtaining/assembling that list of images will depend entirely upon your use case. We might grab them from a sequence of canvases:

gif.frames: (c1,c2,c3)..copy[]

We could do the above in a more verbose way, if we wanted:

gif.frames: c1.copy[],c2.copy[],c3.copy[]

Or perhaps we could use the recently-added ".images" attribute of rich-text fields to grab all the inline images stored in a field:

gif.frames: myRichTextField.images

Etc.

Does that help point you in the right direction?

Hmm. I think this would be rather tricky.

Decker is designed to try to accommodate text input on devices that don't have a physical keyboard, so it avoids exposing low-level keyboard events and doesn't (presently) allow scripts to modify the contents of a text field while it has user focus. Consider how the soft keyboard overlay introduced in Decker 1.19 interacts with unlocked field widgets.  While it's easy enough to detect that a user has pressed return in a text field (and typed a newline),

on change do
 if "\n" in me.text
  # ...
 end
end

That event handler wouldn't be able to clear out the user's line of input, which would make a scripting REPL or an IF parser input awkward.

I'll give this some serious thought and see if I can come up with a good compromise to allow the sort of thing you're interested in making

Decker 1.49 includes some subtle changes that I think will address this request.

It is now possible to clear a field via scripts while it is selected. In touch mode, this will additionally dismiss the on-screen keyboard and remove focus from the field.

In the above example, the script looks like this:

on change do
 if "\n" in me.text
  log.text:log.text,"\n %s%J" format me.text,list eval[me.text].value
  log.scroll:99999
  me.text:""
 end
end

There are a few details to be aware of when using this technique:

• It takes 1/4 of a second without user input for the contents of a field to fire a change[] event, and it is also possible to fire a change[] event by pasting an arbitrary block of text into a field. Therefore it's possible for a user to type several characters following a newline, or even multiple newlines; input handling code will need to be robust to this.
• An alternative to looking for "\n" in a change[] event would be to use the run[] event, which is fired immediately when the user presses shift+return. This may be less intuitive for users, and therefore unsuitable for many applications, but it's much less error-prone and more flexible than newline-delimited input; the run[] event makes it possible to build UIs which behave like Decker's Listener.
• Since the user actually does type a newline, you'll need to carefully adjust the vertical sizing of the input field to match the font in order to maintain the illusion that the field is "cleared" instantly when the user presses return.

I hope this helps!

In Lil, the "&" and "|" operators provide logical AND and logical OR. Both "conform" to the elements of lists:

(1,1,0,0) & (1,0,1,0)  # -> (1,0,0,0)
(1,1,0,0) | (1,0,1,0)  # -> (1,1,1,0)

To be more precise, these operators are actually binary "minimum" and "maximum" operators for numbers:

(1,2,3,4) & 2          # -> (1,2,2,2)
(1,2,3,4) | 2          # -> (2,2,3,4)

As always, be careful to remember that Lil expressions are carried out right-to-left unless you include parentheses.

For comparisons, Lil has < (less), > (more), and = (equal). It does not have "compound" symbols like "<=", ">=", or "!=". If you want the complementary operation, you can use ! (negation):

  a > b      # a is more than b
! a > b      # a is not more than b (a <= b)
  a < b      # a is less than b
! a < b      # a is not less than b (a >= b)
  a = b      # a is equal to b
! a = b      # a is not equal to be (a != b)

Note that all of these operations work to lexicographically compare strings, too:

"Apple" < "Aardvark","Blueberry"    # -> (0,1)
"Apple" & "Aardvark","Blueberry"    # -> ("Aardvark","Apple")
"Apple" | "Aardvark","Blueberry"    # -> ("Apple","Blueberry")

Lil syntax highlighting profiles for vim, emacs, and Sublime Text are available at the Decker Github Repo.

Syntax highlighting is also available in the Lil Playground.

Variables that live beyond an event handler must be stored in a widget. If you find it inconvenient to reference widgets on another card,

thatCard.widgets.has_knife.value
thatCard.widgets.has_soap.value
thatCard.widgets.has_corncob.value

You could write utility functions on the card script that aggregate information from widgets:

on get_inventory do
 ("knife","soap","corncob") dict (has_knife,has_soap,has_corncob)..value
end

And then send events at that card from elsewhere:

thatCard.event["get_inventory"]

(Or as shorthand if the event handler doesn't take any arguments,)

thatCard.event.get_inventory

In this way you can give cards an "API" of sorts. You could also define helper functions in the deck-level script to reach into specific cards:

on items do
 thatCard.event.get_inventory
end

And then call that helper function from anywhere in the deck:

items[]

(I think this is probably overkill unless you're accessing the same info in lots of places within a deck.)

You can absolutely use tables to keep track of dialog options. A grid widget stores a table in its "value" attribute. Aside from manually editing table contents as CSV or JSON, you can initialize one with a script:

myGrid.value:insert k v with
 "Tell me about Chickens"  "They cool."
 "Tell me about Daffodils" "They flower."
end

You could append a new row (or several rows) to the existing table in a grid like so:

myGrid.value:insert k v with
 "Tell me about Easter Eggs" "They rare."
into myGrid.value

And you could then later retrieve that table and convert it into the dictionary form dd.chat[] wants by razing it (which turns the first two columns into dictionary keys and values, respectively):

dd.open[deck]
dd.chat["Ask away." (raze myGrid.value)]
dd.close[]

Note that if you plan on revisiting the same dialog tree over the course of a game many times but you don't want to repeat old selections you'll need to do additional bookkeeping; dd.chat[] only remembers/winnows selections within the course of one conversation.

For more information about tables and querying, see Lil, The Query Language.

Does that help point you in the right direction?

The "image.map[]" function can be used to re-palette any Image interface, including card backgrounds. The simplest way to call it is to feed it a dictionary where the keys are the original pattern indices and the values are the replacement pattern indices:

card.image.map[colors.red dict colors.green]

Note that this operation modifies the image in-place.

The difference is that deck parts are "Interface" values, while your later example is a dictionary.

Lil's basic datatypes (numbers, strings, lists, dictionaries, tables, functions) are all immutable values: attempting to modify them will return a new value and leave the original value unchanged.

Interfaces (like most deck parts) are mutable, and accessing or modifying their attributes may have side-effects. For example, modifying the ".index" attribute of a widget to change its order on a card will also visibly modify the ".widgets" property of the container card, since these attributes are related to one another. The "sys" interface exposes "sys.now", an attribute which contains the current Unix timestamp, and may (generally) be different every time it's accessed. Lil also offers utility Interfaces like Array for those times when mutable data structures are necessary for performance reasons.

Does that make sense?

You can inspect and modify the order of widgets on a card via their .index attribute, which counts from back to front, starting at 0. This is automatically clamped within the permissible range on a card, so assigning it to 0 or -1 can be a convenient shorthand for "all the way to the back" and any very large number (say, 999999) can likewise be used for "all the way to the front".

For example, you could give your draggable canvas a script like so:

on click do
 me.index:999999
end

Don't worry- it's quite normal to stash contraption state in auxiliary hidden widgets. The contents of such widgets is distinct between contraption instances, but the background image of contraptions is shared among all instances; pasting directly onto the contraption background will cause issues if you have more than one sprite. The conventional solution would be to add a canvas widget to the contraption and draw on that instead. You'll also need to configure non-zero margins for the contraption to ensure that the canvas automatically stretches and resizes properly along with it. Both the contraption instance and the canvas will need to be set to "show transparent" if you want objects behind the sprite to show through.

Since you intend to redraw the contents of the canvas frequently, you may be able to mark it as volatile, which will ensure that having many sprite instances won't bloat deck size with unnecessary copies of sprite frames. If you aren't already doing something similar, you may find it useful to mark the canvas as "animated" so that it will automatically bubble view[] events to the contraption instance at 60fps and "locked" so that it doesn't inherit the default click-and-drag-to-scribble behavior of canvases. (Be aware that "me" will be bound to the original target of the view[] event, not necessarily the contraption itself!)

The Sokoban example deck contains a contraption called "mover" which works similarly in some ways to your "sprite" design, and the Path example deck has another variant called "follower". You might find these useful to reference.

Does any of this point you in the right direction?

When a field is configured to display "Rich Text", it can contain text spans that are links, use different fonts, or include inline images. Rich Text is described in the reference manual here.

Rich Text is represented as a Lil table, and can be constructed like any other table so long as it has the appropriate columns. For example,

myField.value:insert text font arg with
 "Apple" "" "theAppleCard"
end

Remember, of course, that fields need to be locked for their hyperlinks to be clickable. Unless you define your own link[] handler for a field, clicking a link will call the go[] built-in function with that "arg" value, which conveniently serves either to navigate to cards by name or to prompt the user to open URLs in a new browser tab.

The "RText" utility interface (linked above) offers a number of convenience functions for creating and manipulating Rich Text tables. The "rtext.make[]" function offers a more concise alternative to the above:

myField.value:rtext.make["Apple" "" "theAppleCard"]

In the interactive docs for a variety of modules I use this sort of approach to automatically generate the index in the title card's view[] event handler:

bullet:image["%%IMG0AAYADQAAAAB49Pz8/HgAAAA="]
i:select c:key t:value..widgets.title.text where value..widgets.title from deck.cards
index.value:raze each row in rows i
 rtext.make["" "" bullet],
 rtext.make["  "],
 rtext.make[("%s\n" format row.t) "mono" row.c]
end 

Does that help?

There's a lot of material in this thread that might be helpful.

There are a number of possible approaches for what you're describing. I'll assume that when you say "play a GIF" you intend to use a gif or colorgif contraption?

If you have set up a button to take you to another card, its script might look something like the following:

on click do
 go["otherCard"]
end

If you simply wanted to wait for time to elapse before changing cards, you could use the sleep[] function, which accepts a number of frames to wait as an argument. Decker runs at 60 frames per second, so a 5 second delay would look like this:

on click do
 sleep[5 * 60]
 go["otherCard"]
end

While Decker is sleeping, the user can't interact with other widgets, and contraptions that normally animate or otherwise update themselves on every frame will appear to be "frozen". Some contraptions are designed to allow an external script to explicitly tell them to update themselves; by convention this will often take the form of exposing an .animate[] function which can be called from the outside. I have updated the gif and colorgif contraptions (see above) to support this convention. (If you already have a gif or colorgif contraption in your deck, re-pasting the updated definition from the bazaar will "upgrade" any existing instances of the contraption.)

If the card contained a gif widget named "mygif", we could rewrite the above script to give it a chance to keep running while Decker waits for 5 seconds by using a loop and only sleeping one frame at a time:

on click do
 each in range 5 * 60
  mygif.animate[]
  sleep[1]
 end
 go["otherCard"]
end

You alluded to wanting the GIF to start playing only when the button was clicked in the first place. Perhaps you meant you want the contraption to appear during that interval? This sort of thing can be done by manipulating the .show attribute of the widget. Supposing the contraption was initially set to "Show None",

on click do
 mygif.show:"solid"
 each in range 5 * 60
  mygif.animate[]
  sleep[1]
 end
 mygif.show:"none"
 go["otherCard"]
end

(Note that I reset the GIF to be invisible again at the end; this is not essential, but makes testing easier!)

I'd also like to point out that it's very straightforward to script simple "slideshow" animations with sleep[] by putting each frame on its own card:

on click do
 go["firstCard"]
 sleep[30]
 go["secondCard"]
 sleep[30]
 go["thirdCard"]
 sleep[30]
 # and so on
end

Or more concisely, for many frames of the same delay,

on click do
 each cardName in ("firstCard","secondCard","thirdCard","fourthCard","fifthCard")
  go[cardName]
  sleep[30]
 end
end

Of course, having a very large number of frames in such an animation can also make your deck quite large!

Does any of this point you in the right direction?

&  is AND,   |  is OR.

if thing1.value & thing2.value # AND

if thing1.value | thing2.value # OR

if ! thing1.value # NOT

Do these examples work for what you need? There's more in this post as well.

Could you post the scripts you're trying that work and those which do not work? It's much easier to diagnose problems with scripts when I can read them and clearly understand what you have tried.

Scripts typically can only run while you're in Interact Mode (or from inside the Listener). Likewise, the canvas.brush attribute you mentioned, when it's used in a script it only meaningfully changes the brush setting for that one canvas when the canvas is clicked in Interact Mode, y'know? (I think you knew that, I'm just clarifying for anyone wandering by.)

So, yeah, I don't think it's possible to change your Drawing Mode tool or brush via scripting.

But, in case it's of use to you and your project: 

The Toolbars do extend downwards with an arrow at the bottom if you have more than the default amount of brushes.

 And as a further example, this is how the 'stamp'-style brushes from the brushes example deck appear on the toolbar:

The last one is quite a large stamp, relative to the others, but it's neatly constrained to it's own little rectangle and it's not too hard to figure out which one is which.

I hope this helps, I'm excited to hear that someone is making use of custom brushes!

raze of a table (like the .value of a grid widget) makes a dictionary mapping the first column to the second column. For example,

 insert k v with "Apple" 11 "Banana" 22 end
+----------+----+
| k        | v  |
+----------+----+
| "Apple"  | 11 |
| "Banana" | 22 |
+----------+----+
 raze insert k v with "Apple" 11 "Banana" 22 end
{"Apple":11,"Banana":22}

the dd.chat[] function will exit if the value corresponding to a key in that map is a number (instead of a string or rtext), so we just need to add another entry to that dictionary.

If you have a dictionary in a variable, you can modify it in-place:

 d:raze insert k v with "Apple" 11 "Banana" 22 end
{"Apple":11,"Banana":22}
 d["Cursed Fruit"]:33
{"Apple":11,"Banana":22,"Cursed Fruit":33}

You can also perform the equivalent amendment if the dictionary was yielded by a subexpression, as long as you wrap it in parentheses:

 (raze insert k v with "Apple" 11 "Banana" 22 end)["Cursed Fruit"]:33
{"Apple":11,"Banana":22,"Cursed Fruit":33}

You can also construct a dictionary functionally using "dict" and then take the union of some other dictionary and the new dictionary with ",":

 (list "Cursed Fruit") dict 33
{"Cursed Fruit":33}
 (()["Cursed Fruit"]:33) # (yet another way of saying the above)
{"Cursed Fruit":33}
 (raze insert k v with "Apple" 11 "Banana" 22 end),((list "Cursed Fruit") dict 33)
{"Apple":11,"Banana":22,"Cursed Fruit":33}

Or you could make a second table and join its rows to the original (also with ",") before razing:

 raze insert k v with "Apple" 11 "Banana" 22 end,insert k v with "Cursed Fruit" 33 end
{"Apple":11,"Banana":22,"Cursed Fruit":33}

Many ways to peel this particular apple. I strongly recommend using the Listener to experiment with examples like these whenever you find yourself puzzling over a tricky expression; building things up in little pieces helps you verify an idea as you go.

Do those examples make sense?