Halyard tutorial

From HalyardWiki

Note: this tutorial is under construction. It is incomplete, and many of the examples may not work or make sense.

This is a basic introduction to Halyard for the general public. It assumes no prior knowledge of Scheme or object oriented programming, though some familiarity with some kind of programming or scripting language would be helpful. There is also a Halyard object model tutorial for people with some basic familiarity with Scheme and object oriented programming, if you want to learn just about the object model, and Halyard object model details for experienced language hackers who want to know about the details of the object mode.

As mentioned above, this tutorial is woefully incomplete. We welcome edits to this and the halyard-test project to make learning Halyard considerably easier.

[edit] Getting Started

The easiest way to get started is to download the example code halyard-test-x.y.z.tar.gz from our downloads page. After extracting the contents of this, you should have an example project you can explore and extend. You should be able to place the example code given here into Scripts/start.ss in the example project (possibly replacing the code that already exists), and press the Reload button to test your changes.

[edit] Cards

The fundamental unit of a Halyard program is a card. A card is self-contained, and contains a set of graphics, text, and media that will be displayed or played when you go to that card. The program will begin on the start card, so here's an example program that just displays "Hello World!"

(card start ()
  (setup (draw-white-background))
  (centered-text hello ($audio-stream-style "Hello World!")))

Let's take a look at that line-by-line.

(card start ()

This defines the start card with (card start, and says that it does not use any pre-defined templates, which is why there are empty parentheses (). That means that the card will be completely empty unless we do anything. You'll also notice that the entire card is enclosed in parentheses: ( and ). This lets the program know where the card begins and ends. Each piece inside also uses parentheses to tell Halyard where that piece begins and ends. To make it easier to read, we also indent each line that is inside a set of parentheses a little bit so it's easier to tell where each part begins and ends.

  (setup (draw-white-background))

This tells the program to draw a white background when setting up the card. That means that the card will always have a white background, unless you change it.

  (centered-text hello ($audio-stream-style "Hello, World!")))

This draws some text on the screen. The text object is named hello, so you can refer to it later, and is displayed using $audio-stream-style, a pre-defined stylesheet that includes information about the font, text color, etc. At the end, we include a closing ) to indicate that we are done defining the card.

[edit] Jumping

Our program would be fairly boring if it just displayed "Hello, World!" In order to provide several different screens of content, you can put them each on a separate card (like separate web pages), and jump between them. Here's a new card that will display a message, and then jump back to the start card.

(card another-card ()
  (setup (draw-white-background))
  (centered-text message ($audio-stream-style "Goodbye, Cruel World!"))
  (run 
    (nap 10)
    (jump start)))

This introduces a few new concepts. We do a setup and centered-text just like the start card, but now we add a new section (run. This is for all of the movies, animations, and actions that your card takes after someone jumps to it. We'll cover the difference between setup and run in more detail later.

Now, in the run section, we start with a call to nap. nap is a function, that is, it's a command that does something or computes something. In this case, it waits for the specified amount of time, in tenths of seconds. So, (nap 10) will wait for one second before executing the next function.

Finally, we come to the jump function. Jump causes us to jump from one card to another. In this case, we jump back to the start card. Jumping means that everything on the current card goes away, and everything on the screen is replaced with the contents of the new card.

Now, once we add this code and Reload, how do we get to this card? You should see on the left hand side of your screen a list of all of the cards and sequences in the program. It should start with the start card, and then have another-card. You can jump directly to a card by double-clicking the card you want to go to in that list. Try double-clicking on another-card, and watch it jump back to the start card.