lacci 0.2.1 → 0.3.0

data/docs/static/manual.md

@@ -1,3528 +0,0 @@
-# Hello!
-
-Shoes is a tiny graphics toolkit. It's simple and straightforward. Shoes was
-born to be easy!  Really, it was made for absolute beginners. There's really
-nothing to it.
-
-You see, the trivial Shoes program can be just one line:
-
-```ruby
- #!ruby
- Shoes.app { button("Click me!") { alert("Good job.") } }
-```
-
-Shoes programs are written in a language called Ruby.  When Shoes is handed
-this simple line of Ruby code, a window appears with a button inside reading
-"Click me!"  When the button is clicked, a message pops up.
-
-On Linux, here's how this might look: ![man-shot1.png](man-shot1.png)
-
-While lots of Shoes apps are graphical games and art programs, you can also
-layout text and edit controls easily. ![shoes-manual-apps.gif](shoes-manual-apps.gif)
-
-And, ideally, Shoes programs will run on any of the major platforms out there.
-Microsoft Windows, Apple's Mac OS X, Linux and many others.
-
-__So, welcome to Shoes' built-in manual. This manual is a Shoes program itself!__
-
-## Introducing Shoes
-
-How does Shoes look on OS X and Windows? Does it really look okay? Is it all
-ugly and awkward? People must immediately convulse! It must be so watered down
-trying to do everything.
-
-Well, before getting into the stuff about installing and running Shoes, time to
-just check out some screenshots, to give you an idea of what you can do.
-
-#### Mac OS X
-
-Shoes runs on Apple Mac OS X Leopard, as well as Tiger.  Shoes supports PowerPC
-machines as well, however, there is no video support on that platform.
-!man-look-tiger.png!
-
-This is the `simple-sphere.rb` sample running on Tiger.  Notice that the app
-runs inside a normal OS X window border.
-
-The whole sphere is drawn with blurred ovals and shadows. You can draw and
-animate shapes and apply effects to those shapes in Shoes.
-
-#### Windows
-
-Shoes runs on all versions of `'Microsoft Windows XP`', `'Windows Vista`',
-`'Windows 7`', and anything else `'Windows 2000`' compatible.
-!man-look-vista.png!
-
-Above is pictured the `simple-clock.rb` sample running on Windows Vista. This
-example is also draws ovals and lines to build the clock, which is animated to
-repaint itself several times each second.
-
-Notice the text on the top of the app, showing the current time. Shoes has the
-skills to layout words using any color, bold, italics, underlines, and supports
-loading fonts from a file.
-
-#### Linux
-
-Here's a screenshot of the `simple-downloader.rb` sample running on `'Ubuntu
-Linux`'. !man-look-ubuntu.png!
-
-Notice the buttons and progress bars. These types of controls look different on
-OS X and Windows. The text and links would look the same, though.
-
-Shapes, text, images and videos all look the same on every platforms.  However,
-native controls (like edit lines and edit boxes) will match the look of the
-window theme. Shoes will try to keep native controls all within the size you
-give them, only the look will vary.
-
-## Installing Shoes
-
-Okay, on to installing Shoes. I'm sure you're wondering: do I need to install
-Ruby? Do I need to unzip anything? What commands do I need to type?
-
-Nope. You don't need Ruby. You don't need WinZip. Nothing to type.
-
-On most systems, starting Shoes is just a matter of running the installer and
-clicking the Shoes icon.  Shoes comes with everything built in. We'll talk
-through all the steps, though, just to be clear about it.
-
-#### Step 1: Installing Shoes
-
-You'll want to visit [the site of Shoes](http://shoesrb.com/) to download
-the Shoes installer.  Usually, you'll just want one of the installers on the
-downloads page of the site. !man-builds1.png!
-
-Here's how to run the installer:
-
- * On `'Mac OS X`', you'll have a file ending with `'.dmg`'.  Double-click this file and a window should appear with a `'Shoes`' icon and an `'Applications`' folder.  Following the arrow, drag the Shoes icon into the `'Applications`' folder. !man-intro-dmg.png!
- * On `'Windows`', you'll download a `'.exe`' file.  Double-click this file and follow the instructions. !man-intro-exe.png!
- * On `'Linux`', you'll need to compile your own Shoes. Check out [this page](https://github.com/shoes/shoes/wiki/Building-Shoes-on-Linux) for more. We want to provide packages eventually!
-
-#### Step 2: Start a New Text File
-
-Shoes programs are just plain text files ending with a `'.rb`' extension.
-
-Here are a few ways to create a blank text file:
-
- * On `'Mac OS X`', visit your `'Applications`' folder and double-click on the `'TextEdit`' app.  A blank editor window should come up.  Now, go to the `'Format`' menu and select the `'Make Plain Text`' option.  Okay, you're all set! !man-editor-osx.png!
- * On `'Windows`', go to the Start menu.  Select `'All Programs`', then `'Accessories`', then `'Notepad`'. !man-editor-notepad.png!
- * On `'Linux`', most distros come with `'gedit`'.  You might try running that.  Or, if your distro is KDE-based, run `'kate`'.
-
-Now, in your blank window, type in the following:
-
-```ruby
- Shoes.app do
-   background "#DFA"
-   para "Welcome to Shoes"
- end
-```
-
-Save to your desktop as `welcome.rb`.
-
-#### Step 3: Run It! Go Shoes!
-
-To run your program:
-
- * On `'Mac OS X`', visit your `'Applications`' folder again.  This time, double-click the `'Shoes`' icon in that folder.  You should see the red shoes icon appear in the dock.  Drag your `welcome.rb` from the desktop on to that dock icon. !man-run-osx.png!
- * On `'Windows`', get to the Start menu.  Go into `'All Programs`', then `'Shoes`', then `'Shoes`'.  A file selector box should come up.  Browse to your desktop and select `welcome.rb`.  Click `'OK`' and you're on your way. !man-run-xp.png! !man-run-vista.png!
- * On `'Linux`', run Shoes just like you did in step one.  You should see a file selector box.  Browse to your desktop, select `welcome.rb` and hit `'OK`'.
-
-So, not much of a program yet.  But it's something!  You've got the knack of it, at least!
-
-#### What Can You Make With Shoes?
-
-Well, you can make windowing applications. But Shoes is inspired by the web, so
-applications tend to use images and text layout rather than a lot of widgets.
-For example, Shoes doesn't come with tabbed controls or toolbars. Shoes is a
-`tiny` toolkit, remember?
-
-Still, Shoes does have a few widgets like buttons and edit boxes. And many
-missing elements (like tabbed controls or toolbars) can be simulated with
-images.
-
-Shoes is written in part thanks to a very good art engine called Cairo, which
-is used for drawing with shapes and colors. In this way, Shoes is inspired by
-NodeBox and Processing, two very good languages for drawing animated graphics.
-
-## The Rules of Shoes
-
-Time to stop guessing how Shoes works.  Some of the tricky things will come
-back to haunt you.  I've boiled down the central rules to Shoes.  These are the
-things you MUST know to really make it all work.
-
-These are general rules found throughout Shoes.  While Shoes has an overall
-philosophy of simplicity and clarity, there are a few points that need to be
-studied and remembered.
-
-#### Shoes Tricky Blocks
-
-Okay, this is absolutely crucial.  Shoes does a trick with blocks.  This trick
-makes everything easier to read.  But it also can make blocks harder to use
-once you're in deep.
-
-`'Let's take a normal Ruby block:`'
-
-```ruby
- ary = ['potion', 'swords', 'shields']
- ary.each do |item|
-   puts item
- end
-```
-
-In Shoes, these sorts of blocks work the same.  This block above loops through
-the array and stores each object in the `item` variable.  The `item` variable
-disappears (goes out of scope) when the block ends.
-
-One other thing to keep in mind is that `self` stays the same inside normal
-Ruby blocks.  Whatever `self` was before the call to `each`, it is the same
-inside the `each` block.
-
-`'Both of these things are also true for most Shoes blocks.`'
-
-```ruby
- Shoes.app do
-   stack do
-     para "First"
-     para "Second"
-     para "Third"
-   end
- end
-```
-
-Here we have two blocks.  The first block is sent to `Shoes.app`.  This `app`
-block changes `self`.
-
-The other block is the `stack` block.  That block does NOT change self.
-
-`'For what reason does the `app` block change self?`'  Let's start by
-spelling out that last example completely.
-
-```ruby
- Shoes.app do
-   self.stack do
-     self.para "First"
-     self.para "Second"
-     self.para "Third"
-   end
- end
-```
-
-All of the `self`s in the above example are the App object.  Shoes uses Ruby's
-`instance_eval` to change self inside the `app` block.  So the method calls to
-`stack` and `para` get sent to the app.
-
-`'This also is why you can use instance variables throughout a Shoes app:`'
-
-```ruby
- Shoes.app do
-   @s = stack do
-     @p1 = para "First"
-     @p2 = para "Second"
-     @p3 = para "Third"
-   end
- end
-```
-
-These instance variables will all end up inside the App object.
-
-`'Whenever you create a new window, `self` is also changed.`'  So, this means
-the [[Element.window]] and [[Element.dialog]] methods, in addition to
-Shoes.app.
-
-```ruby
- Shoes.app title: "MAIN" do
-   para self
-   button "Spawn" do
-     window title: "CHILD" do
-       para self
-     end
-   end
- end
-```
-
-#### Block Redirection
-
-The `stack` block is a different story, though.  It doesn't change `self` and
-it's basically a regular block.
-
-`'But there's a trick:`' when you attach a `stack` and give it a block, the
-App object places that stack in its memory.  The stack gets popped off when the
-block ends.  So all drawing inside the block gets `'redirected`' from the
-App's top slot to the new stack.
-
-So those three `para`s will get drawn on the `stack`, even though they actually
-get sent to the App object first.
-
-```ruby
- Shoes.app do
-   stack do
-     para "First"
-     para "Second"
-     para "Third"
-   end
- end
-```
-
-A bit tricky, you see?  This can bite you even if you know about it.
-
-One way it'll get you is if you try to edit a stack somewhere else in your
-program, outside the `app` block.
-
-Like let's say you pass around a stack object.  And you have a class that edits
-that object.
-
-```ruby
- class Messenger
-   def initialize(stack)
-     @stack = stack
-   end
-   def add(msg)
-     @stack.append do
-       para msg
-     end
-   end
- end
-```
-
-So, let's assume you pass the stack object into your Messenger class when the
-app starts.  And, later, when a message comes in, the `add` method gets used to
-append a paragraph to that stack.  Should work, right?
-
-Nope, it won't work.  The `para` method won't be found.  The App object isn't
-around any more.  And it's the one with the `para` method.
-
-Fortunately, each Shoes object has an `app` method that will let you reopen the
-App object so you can do somefurther editing.
-
-```ruby
- class Messenger
-   def initialize(stack)
-     @stack = stack
-   end
-   def add(msg)
-     @stack.app do
-       @stack.append do
-         para msg
-       end
-     end
-   end
- end
-```
-
-As you can imagine, the `app` method changes `self` to the App object.
-
-So the rules here are:
-
-1. `'Methods named "app" or which create new windows alter `self` to the App
-object.`'[[BR]](This is true for both Shoes.app and Slot.app, as well as
-[[Element.window]] and [[Element.dialog]].)[[BR]]
-2. `'Blocks attached to stacks, flows or any manipulation method (such as
-append) do not change self. Instead, they pop the slot on to the app's editing
-stack.`'
-
-#### Careful With Fixed Heights
-
-Fixed widths on slots are great so you can split the window into columns.
-
-```ruby
- Shoes.app do
-   flow do
-     stack width: 200 do
-       caption "Column one"
-       para "is 200 pixels wide"
-     end
-     stack width: -200 do
-       caption "Column two"
-       para "is 100% minus 200 pixels wide"
-     end
-   end
- end
-```
-
-Fixed heights on slots should be less common.  Usually you want your text and
-images to just flow down the window as far as they can.  Height usually happens
-naturally.
-
-The important thing here is that fixed heights actually force slots to behave
-differently.  To be sure that the end of the slot is chopped off perfectly, the
-slot becomes a `'nested window`'.  A new layer is created by the operating
-system to keep the slot in a fixed square.
-
-One difference between normal slots and nested window slots is that the latter
-can have scrollbars.
-
-```ruby
- Shoes.app do
-   stack width: 200, height: 200, scroll: true do
-     background "#DFA"
-     100.times do |i|
-       para "Paragraph No. #{i}"
-     end
-   end
- end
-```
-
-These nested windows require more memory.  They tax the application a bit more.
-So if you're experiencing some slowness with hundreds of fixed-height slots,
-try a different approach.
-
-#### Image and Shape Blocks
-
-Most beginners start littering the window with shapes.  It's just easier to
-throw all your rectangles and ovals in a slot.
-
-`'However, bear in mind that Shoes will create objects for all those
-shapes!`'
-
-```ruby
- Shoes.app do
-   fill black(0.1)
-   100.times do |i|
-     oval i, i, i * 2
-   end
- end
-```
-
-In this example, one-hundred Oval objects are created.  This isn't too bad.
-But things would be slimmer if we made these into a single shape.
-
-```ruby
- Shoes.app do
-   fill black(0.1)
-   shape do
-     100.times do |i|
-       oval i, i, i * 2
-     end
-   end
- end
-```
-
-Oh, wait.  The ovals aren't filled in this time!  That's because the ovals have
-been combined into a single huge shape.  And Shoes isn't sure where to fill in
-this case.
-
-So you usually only want to combine into a single shape when you're dealing
-strictly with outlines.
-
-Another option is to combine all those ovals into a single image.
-
-```ruby
- Shoes.app do
-   fill black(0.1)
-   image 300, 300 do
-     100.times do |i|
-       oval i, i, i * 2
-     end
-   end
- end
-```
-
-There we go!  The ovals are all combined into a single 300 x 300 pixel image.
-In this case, storing that image in memory might be much bigger than having
-one-hundred ovals around.  But when you're dealing with thousands of shapes,
-the image block can be cheaper.
-
-The point is: it's easy to group shapes together into image or shape blocks, so
-give it a try if you're looking to gain some speed.  Shape blocks particularly
-will save you some memory and speed.
-
-#### UTF-8 Everywhere
-
-Ruby itself isn't Unicode aware.  And UTF-8 is a type of Unicode.  (See
-[Wikipedia](http://en.wikipedia.org/wiki/UTF-8) for a full explanation of
-UTF-8.)
-
-However, UTF-8 is common on the web.  And lots of different platforms support
-it.  So to cut down on the amount of conversion that Shoes has to do, Shoes
-expects all strings to be in UTF-8 format.
-
-This is great because you can show a myriad of languages (Russian, Japanese,
-Spanish, English) using UTF-8 in Shoes.  Just be sure that your text editor
-uses UTF-8!
-
-To illustrate:
-
-```ruby
- Shoes.app do
-   stack margin: 10 do
-     @edit = edit_box width: 1.0 do
-       @para.text = @edit.text
-     end
-     @para = para ""
-   end
- end
-```
-
-This app will copy anything you paste into the edit box and display it in a
-Shoes paragraph.  You can try copying some foreign text (such as Greek or
-Japanese) into this box to see how it displays.
-
-This is a good test because it proves that the edit box gives back UTF-8
-characters.  And the paragraph can be set to any UTF-8 characters.
-
-`'Important note:`' if some UTF-8 characters don't display for you, you will
-need to change the paragraph's font.  This is especially common on OS X.
-
-So, a good Japanese font on OS X is `'AppleGothic`' and on Windows is `'MS
-UI Gothic`'.
-
-```ruby
- Shoes.app do
-   para "てすと (te-su-to)", font: case RUBY_PLATFORM
-    when /mingw/; "MS UI Gothic"
-    when /darwin/; "AppleGothic, Arial"
-    else "Arial"
-    end
- end
-```
-
-Again, anything which takes a string in Shoes will need a UTF-8 string.  Edit
-boxes, edit lines, list boxes, window titles and text blocks all take UTF-8. If
-you give a string with bad characters in it, an error will show up in the
-console.
-
-#### The Main App and Its Requires
-
-`'NOTE:`' This rule is for Raisins. Policeman uses TOPLEVEL_BINDING. So, you
-can get `main`, Ruby top-level object, with the first snippet. Although you
-need to use `Shoes::Para` instead of `Para` outside `Shoes.app` block.
-
-Each Shoes app is given a little room where it can create itself.  You can
-create classes and set variables and they won't be seen by other Shoes
-programs.  Each program runs inside its own anonymous class.
-
-```ruby
- main = self
- Shoes.app do
-   para main.to_s
- end
-```
-
-This anonymous class is called `(shoes)` and it's just an empty, unnamed class.
-The `Shoes` module is mixed into this class (using `include Shoes`) so that you
-can use either `Para` or `Shoes::Para` when referring to the paragraph class.
-
-The advantages of this approach are:
-
- * Shoes apps cannot share local variables.
- * Classes created in the main app code are temporary.
- * The Shoes module can be mixed in to the anonymous class, but not the top-level environment of Ruby itself.
- * Garbage collection can clean up apps entirely once they complete.
-
-The second part is especially important to remember.
-
-```ruby
- class Storage; end
-
- Shoes.app do
-   para Storage.new
- end
-```
-
-The `Storage` class will disappear once the app completes.  Other apps aren't
-able to use the Storage class.  And it can't be gotten to from files that are
-loaded using `require`.
-
-When you `require` code, though, that code will stick around.  It will be kept
-in the Ruby top-level environment.
-
-So, the rule is: `'keep your temporary classes in the code with the app and
-keep your permanent classes in requires.`'
-
-# Shoes
-
-Shoes is all about drawing windows and the stuff inside those windows.  Let's
-focus on the window itself, for now.  The other sections [[Slots]] and
-[[Elements]] cover everything that goes inside the window.
-
-For here on, the manual reads more like a dictionary. Each page is mostly a
-list of methods you can use for each topic covered. The idea is to be very
-thorough and clear about everything.
-
-So, if you've hit this far in the manual and you're still hazy about getting
-started, you should probably either go back to the [[Hello! beginning]] of the
-manual. Or you could try [Nobody Knows Shoes](https://github.com/downloads/shoes/shoes/nks.pdf), the beginner's leaflet PDF.
-
-#### Finding Your Way
-
-This section covers:
-
- * [[Built-in Built-in methods]] - general methods available anywhere in a Shoes program.
- * [[App The App window]] - methods found attached to every main Shoes window.
- * [[Styles The Styles Master List]] - a complete list of every style in Shoes.
- * [[Classes The Classes list]] - a chart showing what Shoes classes subclass what.
- * [[Colors The Colors list]] - a chart of all built-in colors and the [[Built-in.rgb]] numbers for each.
-
-If you find yourself paging around a lot and not finding something, give the
-[[Search]] page a try. It's the quickest way to get around.
-
-After this general reference, there are two other more specific sections:
-
- * [[Slots]] - covering [[Element.stack]] and [[Element.flow]], the two types of slots.
- * [[Elements]] - documentation for all the buttons, shapes, images, and so on.
-
-Two really important pages in there are the [[Element Element Creation]] page
-(which lists all the elements you can add) and the [[Common Common Methods]]
-page (which lists methods you'll find on any slot or element.)
-
-## Built-in Methods
-
-These methods can be used anywhere throughout Shoes programs.
-
-All of these commands are unusual because you don't attach them with a dot.
-`'Every other method in this manual must be attached to an object with a dot.`'
-But these are built-in methods (also called: Kernel methods.) Which means no dot!
-
-A common one is `alert`:
-
-```ruby
- #!ruby
- alert "No dots in sight"
-```
-
-Compare that to the method `reverse`, which isn't a Kernel method and is only
-available for Arrays and Strings:
-
-```ruby
- #!ruby
- "Plaster of Paris".reverse
-  #=> "siraP fo retsalP"
- [:dogs, :cows, :snakes].reverse
-  #=> [:snakes, :cows, :dogs]
-```
-
-Most Shoes methods for drawing and making buttons and so on are attached to
-slots.  See the section on [[Slots]] for more.
-
-#### Built-in Constants
-
-Shoes also has a handful of built-in constants which may prove useful if you
-are trying to sniff out what release of Shoes is running.
-
-`'Shoes::RELEASE_NAME`' contains a string with the name of the Shoes release.
-All Shoes releases are named, starting with Curious.
-
-`'Shoes::RELEASE_ID`' contains a number representing the Shoes release.  So,
-for example, Curious is number 1, as it was the first official release.
-
-`'Shoes::REVISION`' is the Subversion revision number for this build.
-
-`'Shoes::FONTS`' is a complete list of fonts available to the app.  This list
-includes any fonts loaded by the [[Built-in.font]] method.
-
-### alert(message: a string) » nil
-
-Pops up a window containing a short message.
-
-```ruby
- #!ruby
- alert("I'm afraid I must interject!")
-```
-
-Please use alerts sparingly, as they are incredibly annoying!  If you are using
-alerts to show messages to help you debug your program, try checking out the
-[[Built-in.debug]] or [[Built-in.info]] methods.
-
-### ask(message: a string) » a string
-
-Pops up a window and asks a question. For example, you may want to ask someone
-their name.
-
-```ruby
- #!ruby
- name = ask("Please, enter your name:")
-```
-
-When the above script is run, the person at the computer will see a window with
-a blank box for entering their name. The name will then be saved in the `name`
-variable.
-
-### ask_color(title: a string) » Shoes::Color
-
-Pops up a color picker window. The program will wait for a color to be picked,
-then gives you back a Color object. See the `Color` help for some ways you can
-use this color.
-
-```ruby
- #!ruby
- backcolor = ask_color("Pick a background")
- Shoes.app do
-  background backcolor
- end
-```
-
-### ask_open_file() » a string
-
-Pops up an "Open file..." window. It's the standard window which shows all of
-your folders and lets you select a file to open. Hands you back the name of the
-file.
-
-```ruby
- #!ruby
- filename = ask_open_file
- Shoes.app do
-   para File.read(filename)
- end
-```
-
-### ask_save_file() » a string
-
-Pops up a "Save file..." window, similiar to `ask_open_file`, described
-previously.
-
-```ruby
- #!ruby
- save_as = ask_save_file
-```
-
-### ask_open_folder() » a string
-
-Pops up an "Open folder..." window. It's the standard window which shows all of
-your folders and lets you select a folder to open. Hands you back the name of
-the folder.
-
-```ruby
- #!ruby
- folder = ask_open_folder
- Shoes.app do
-   para Dir.entries(folder)
- end
-```
-
-### ask_save_folder() » a string
-
-Pops up a "Save folder..." window, similiar to `ask_open_folder`, described
-previously. On OS X, this method currently behaves like an alias of
-`ask_open_folder`.
-
-```ruby
- #!ruby
- save_to = ask_save_folder
-```
-
-
-### confirm(question: a string) » true or false
-
-Pops up a yes-or-no question. If the person at the computer, clicks `'yes`',
-you'll get back a `true`. If not, you'll get back `false`.
-
-```ruby
- #!ruby
- if confirm("Draw a circle?")
-  Shoes.app{ oval top: 0, left: 0, radius: 50 }
- end
-```
-
-### debug(message: a string) » nil
-
-Sends a debug message to the Shoes console.  You can bring up the Shoes console
-by pressing `Alt-/` on any Shoes window (or `⌘-/` on OS X.)
-
-```ruby
- #!ruby
- debug("Running Shoes on " + RUBY_PLATFORM)
-```
-
-Also check out the [[Built-in.error]], [[Built-in.warn]] and [[Built-in.info]]
-methods.
-
-### error(message: a string) » nil
-
-Sends an error message to the Shoes console.  This method should only be used
-to log errors.  Try the [[Built-in.debug]] method for logging messages to
-yourself.
-
-Oh, and, rather than a string, you may also hand exceptions directly to this
-method and they'll be formatted appropriately.
-
-### exit()
-
-Stops your program. Call this anytime you want to suddenly call it quits.
-
-`'PLEASE NOTE:`' If you need to use Ruby's own `exit` method (like in a
-forked Ruby process,) call `Kernel.exit`.
-
-### font(message: a string) » an array of font family names
-
-Loads a TrueType (or other type of font) from a file.  While TrueType is
-supported by all platforms, your platform may support other types of fonts.
-Shoes uses each operating system's built-in font system to make this work.
-
-Here's a rough idea of what fonts work on which platforms:
-
- * Bitmap fonts (.bdf, .pcf, .snf) - Linux
- * Font resource (.fon) - Windows
- * Windows bitmap font file (.fnt) - Linux, Windows
- * PostScript OpenType font (.otf) - Mac OS X, Linux, Windows
- * Type1 multiple master (.mmm) - Windows
- * Type1 font bits (.pfb) - Linux, Windows
- * Type1 font metrics (.pfm) - Linux, Windows
- * TrueType font (.ttf) - Mac OS X, Linux, Windows
- * TrueType collection (.ttc) - Mac OS X, Linux, Windows
-
-If the font is properly loaded, you'll get back an array of font names found in
-the file.  Otherwise, `nil` is returned if no fonts were found in the file.
-
-Also of interest: the `Shoes::FONTS` constant is a complete list of fonts
-available to you on this platform.  You can check for a certain font by using
-`include?`.
-
-```ruby
- if Shoes::FONTS.include? "Helvetica"
-   alert "Helvetica is available on this system."
- else
-   alert "You do not have the Helvetica font."
- end
-```
-
-If you have trouble with fonts showing up, make sure your app loads the font
-before it is used.  Especially on OS X, if fonts are used before they are
-loaded, the font cache will tend to ignore loaded fonts.
-
-### gradient(color1, color2) » Shoes::Pattern
-
-Builds a linear gradient from two colors.  For each color, you may pass in a
-Shoes::Color object or a string describing the color.
-
-### gray(the numbers: darkness, alpha) » Shoes::Color
-
-Create a grayscale color from a level of darkness and, optionally, an alpha
-level.
-
-```ruby
- black = gray(0.0)
- white = gray(1.0)
-```
-
-### info(message: a string) » nil
-
-Logs an informational message to the user in the Shoes console.  So, where
-debug messages are designed to help the program figure out what's happening,
-`info` messages tell the user extra information about the program.
-
-```ruby
- #!ruby
-
- info("You just ran the info example on Shoes #{Shoes::RELEASE_NAME}.")
-```
-
-For example, whenever a Shy file loads, Shoes prints an informational message
-in the console describing the author of the Shy and its version.
-
-### rgb(a series of numbers: red, green, blue, alpha) » Shoes::Color
-
-Create a color from red, green and blue components.  An alpha level (indicating
-transparency) can also be added, optionally.
-
-When passing in a whole number, use values from 0 to 255.
-
-```ruby
- blueviolet = rgb(138, 43, 226)
- darkgreen = rgb(0, 100, 0)
-```
-
-Or, use a decimal number from 0.0 to 1.0.
-
-```ruby
- blueviolet = rgb(0.54, 0.17, 0.89)
- darkgreen = rgb(0, 0.4, 0)
-```
-
-This method may also be called as `Shoes.rgb`.
-
-### warn(message: a string) » nil
-
-Logs a warning for the user.  A warning is not a catastrophic error (see
-[[Built-in.error]] for that.)  It is just a notice that the program will be
-changing in the future or that certain parts of the program aren't reliable
-yet.
-
-To view warnings and errors, open the Shoes console with `Alt-/` (or `⌘-/` on
-OS X.)
-
-## The App Object
-
-An App is a single window running code at a URL. When you switch URLs, a new
-App object is created and filled up with stacks, flows and other Shoes
-elements.
-
-The App is the window itself. Which may be closed or cleared and filled with
-new elements. ![man-app.png](man-app.png)
-
-The App itself, in slot/box terminology, is a flow.  See the `Slots` section
-for more, but this just means that any elements placed directly at the
-top-level will flow.
-
-### Shoes.app(styles) { ... } » Shoes::App
-
-Starts up a Shoes app window.  This is the starting place for making a Shoes
-program.  Inside the block, you fill the window with various Shoes elements
-(buttons, artwork, etc.) and, outside the block, you use the `styles` to
-describe how big the window is.  Perhaps also the name of the app or if it's
-resizable.
-
-```ruby
- #!ruby
- Shoes.app(title: "White Circle",
-   width: 200, height: 200, resizable: false) {
-     background black
-     fill white
-     oval top: 20, left: 20, radius: 160
- }
-```
-
-In the case above, a small window is built.  200 pixels by 200 pixels.  It's
-not resizable.  And, inside the window, two elements: a black background and a
-white circle.
-
-Once an app is created, it is added to the [[App.Shoes.APPS]] list.  If you
-want an app to spawn more windows, see the [[Element.window]] method and the
-[[Element.dialog]] method.
-
-### Shoes.APPS() » An array of Shoes::App objects
-
-Builds a complete list of all the Shoes apps that are open right now.  Once an
-app is closed, it is removed from the list.  Yes, you can run many apps at once
-in Shoes.  It's completely encouraged.
-
-### clipboard() » a string
-
-Returns a string containing all of the text that's on the system clipboard.
-This is the global clipboard that every program on the computer cuts and pastes
-into.
-
-### clipboard = a string
-
-Stores `a string` of text in the system clipboard.
-
-### close()
-
-Closes the app window.  If multiple windows are open and you want to close the
-entire application, use the built-in method `exit`.
-
-### download(url: a string, styles)
-
-Starts a download thread (much like XMLHttpRequest, if you're familiar with
-JavaScript.)  This method returns immediately and runs the download in the
-background.  Each download thread also fires `start`, `progress` and `finish`
-events.  You can send the download to a file or just get back a string (in the
-`finish` event.)
-
-If you attach a block to a download, it'll get called as the `finish` event.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     title "Searching Google", size: 16
-     @status = para "One moment..."
-
-     # Search Google for 'shoes' and print the HTTP headers
-     download "http://www.google.com/search?q=shoes" do |goog|
-       @status.text = "Headers: " + goog.response.headers.inspect
-     end
-   end
- end
-```
-
-And, if we wanted to use the downloaded data, we'd get it using
-`goog.response.body`.  This example is truly the simplest form of `download`:
-pulling some web data down into memory and handling it once it's done.
-
-Another simple use of `download` is to save some web data to a file, using the
-`:save` style.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     title "Downloading Google image", size: 16
-     @status = para "One moment..."
-
-     download "http://www.google.com/logos/nasa50th.gif",
-       save: "nasa50th.gif" do
-         @status.text = "Okay, is downloaded."
-     end
-   end
- end
-```
-
-In this case, you can still get the headers for the downloaded file, but
-`response.body` will be `nil`, since the data wasn't saved to memory.  You will
-need to open the file to get the downloaded goods.
-
-If you need to send certain headers or actions to the web server, you can use
-the `:method`, `:headers` and `:body` styles to customize the HTTP request.
-(And, if you need to go beyond these, you can always break out Ruby's OpenURI
-class.)
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     title "GET Google", size: 16
-     @status = para "One moment..."
-
-     download "http://www.google.com/search?q=shoes",
-         method: "GET" do |dump|
-       @status.text = dump.response.body
-     end
-   end
- end
-```
-
-As you can see from the above example, Shoes makes use of the "GET" method to
-query google's search engine.
-
-### location() » a string
-
-Gets a string containing the URL of the current app.
-
-### mouse() » an array of numbers: button, left, top
-
-Identifies the mouse cursor's location, along with which button is being
-pressed.
-
-```ruby
- #!ruby
- Shoes.app do
-   @p = para
-   animate do
-     button, left, top = self.mouse
-     @p.replace "mouse: #{button}, #{left}, #{top}"
-   end
- end
-```
-
-### owner() » Shoes::App
-
-Gets the app which launched this app.  In most cases, this will be `nil`.  But
-if this app was launched using the [[Element.window]] method, the owner will be
-the app which called `window`.
-
-### started?() » true or false
-
-Has the window been fully constructed and displayed?  This is useful for
-threaded code which may try to use the window before it is completely built.
-(Also see the `start` event which fires once the window is open.)
-
-### visit(url: a string)
-
-Changes the location, in order to view a different Shoes URL.
-
-Absolute URLs (such as http://google.com) are okay, but Shoes will be expecting
-a Shoes application to be at that address.  (So, google.com won't work, as it's
-an HTML app.)
-
-## The Styles Master List
-
-You want to mess with the look of things?  Well, throughout Shoes, styles are
-used to change the way elements appear.  In some cases, you can even style an
-entire class of elements.  (Like giving all paragraphs a certain font.)
-
-Styles are easy to spot.  They usually show up when the element is created.
-
-```ruby
- Shoes.app title: "A Styling Sample" do
-   para "Red with an underline", stroke: red, underline: "single"
- end
-```
-
-Here we've got a `:title` style on the app.  And on the paragraph inside the
-app, a red `:stroke` style and an `:underline` style.
-
-The style hash can also be changed by using the [[Common.style]] method,
-available on every element and slot.
-
-```ruby
- Shoes.app title: "A Styling Sample" do
-   @text = para "Red with an underline"
-   @text.style(stroke: red, underline: "single")
- end
-```
-
-Most styles can also be set by calling them as methods.  (I'd use the manual
-search to find the method.)
-
-```ruby
- Shoes.app title: "A Styling Sample" do
-   @text = para "Red with an underline"
-   @text.stroke = red
-   @text.underline = "single"
- end
-```
-
-Rather than making you plow through the whole manual to figure out what styles
-go where, this helpful page speeds through every style in Shoes and suggests
-where that style is used.
-
-### :align » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`
-
-The alignment of the text. It is either:
-
- * "left" - Align the text to the left.
- * "center" - Align the text in the center.
- * "right" - Align the text to the right.
-
-### :angle » a number
-
-For: `background, border, gradient`.
-
-The angle at which to apply a gradient.  Normally, gradient colors range from
-top to bottom.  If the `:angle` is set to 90, the gradient will rotate 90
-degrees counter-clockwise and the gradient will go from left to right.
-
-### :attach » a slot or element
-
-For: `flow, stack`.
-
-Pins a slot relative to another slot or element.  Also, one may write `attach: Window` to position the slot at the window's top, left corner.  Taking this
-a bit further, the style `top: 10, left: 10, attach: Window` would
-place the slot at (10, 10) in the window's coordinates.
-
-If a slot is attached to an element that moves, the slot will move with it.  If
-the attachment is reset to `nil`, the slot will flow in with the other objects
-that surround, as normal.
-
-### :autoplay » true or false
-
-For: `video`.
-
-Should this video begin playing after it appears?  If set to `true`, the video
-will start without asking the user.
-
-### :bottom » a number
-
-For: `all slots and elements`.
-
-Sets the pixel coordinate of an element's lower edge.  The edge is placed
-relative to its container's lower edge.  So, `bottom: 0` will align the
-element so that its bottom edge and the bottom edge of its slot touch.
-
-### :cap » :curve or :rect or :project
-
-For: `arc, arrow, border, flow, image, mask, rect, star, shape, stack`.
-
-Sets the shape of the line endpoint, whether curved or square.  See the
-[[Art.cap]] method for more explanation.
-
-### :center » true or false
-
-For: `arc, image, oval, rect, shape`.
-
-Indicates whether the `:top` and `:left` coordinates refer to the center of the
-shape or not.  If set to `true`, this is similar to setting the
-[[Art.transform]] method to `:center`.
-
-### :change » a proc
-
-For: `edit_box, edit_line, list_box`.
-
-The `change` event handler is stored in this style.  See the [[EditBox.change]]
-method for the edit_box, as an example.
-
-### :checked » true or false
-
-For: `check, radio`.
-
-Is this checkbox or radio button checked?  If set to `true`, the box is
-checked.  Also see the [[Check.checked=]] method.
-
-### :choose » a string
-
-For: `list_box`.
-
-Sets the currently chosen item in the list.  More information at
-[[ListBox.choose]].
-
-### :click » a proc
-
-For: `arc, arrow, banner, button, caption, check, flow, image, inscription,
-line, link, mask, oval, para, radio, rect, shape, stack, star, subtitle,
-tagline, title`.
-
-The `click` event handler is stored in this style.  See the [[Events.click]]
-method for a description.
-
-### :curve » a number
-
-For: `background, border, rect`.
-
-The radius of curved corners on each of these rectangular elements.  As an
-example, if this is set to 6, the corners of the rectangle are given a curve
-with a 6-pixel radius.
-
-### :displace_left » a number
-
-For: `all slots and elements`.
-
-Moves a shape, text block or any other kind of object to the left or right.  A
-positive number displaces to the right by the given number of pixels; a
-negative number displaces to the left.  Displacing an object doesn't effect the
-actual layout of the page.  Before using this style, be sure to read the
-[[Position.displace]] docs, since its behavior can be a bit surprising.
-
-### :displace_top » a number
-
-For: `all slots and elements`.
-
-Moves a shape, text block or any other kind of object up or down.  A positive
-number moves the object down by this number of pixels; a negative number moves
-it up.  Displacing doesn't effect the actual layout of the page or the object's
-true coordinates.  Read the [[Position.displace]] docs, since its behavior can
-be a bit surprising.
-
-### :emphasis » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Styles the text with an emphasis (commonly italicized.)
-
-This style recognizes three possible settings:
-
- * "normal" - the font is upright.
- * "oblique" - the font is slanted, but in a roman style.
- * "italic" - the font is slanted in an italic style.
-
-### :family » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Styles the text with a given font family.  The string should contain the family
-name or a comma-separated list of families.
-
-### :fill » a hex code, a Shoes::Color or a range of either
-
-For: `arc, arrow, background, banner, caption, code, del, em, flow, image,
-ins, inscription, line, link, mask, oval, para, rect, shape, span, stack, star,
-strong, sub, sup, subtitle, tagline, title`.
-
-The color of the background pen.  For shapes, this is the fill color, the paint
-inside the shape.  For text stuffs, this color is painted in the background (as
-if marked with a highlighter pen.)
-
-### :font » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Styles the text with a font description.  The string is pretty flexible, but
-can take the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is
-a comma separated list of families optionally terminated by a comma,
-STYLE_OPTIONS is a whitespace separated list of words where each WORD describes
-one of style, variant, weight, stretch, or gravity, and SIZE is a decimal
-number (size in points) or optionally followed by the unit modifier "px" for
-absolute size. Any one of the options may be absent. If FAMILY-LIST is absent,
-then the default font family (Arial) will be used.
-
-### :group » a string
-
-For: `radio`.
-
-Indicates what group a radio button belongs to.  Without this setting, radio
-buttons are grouped together with other radio buttons in their immediate slot.
-"Grouping" radio buttons doesn't mean they'll be grouped next to each other on
-the screen.  It means that only one radio button from the group can be selected
-at a time.
-
-By giving this style a string, the radio button will be grouped with other
-radio buttons that have the same group name.
-
-### :height » a number
-
-For: `all slots and elements`.
-
-Sets the pixel height of this object.  If the number is a decimal number, the
-height becomes a percentage of its parent's height (with 0.0 being 0% and 1.0
-being 100%.)
-
-### :hidden » true or false
-
-For: `all slots and elements`.
-
-Hides or shows this object.  Any object with `hidden: true` are not
-displayed on the screen.  Neither are its children.
-
-### :inner » a number
-
-For: `star`.
-
-The size of the inner radius (in pixels.)  The inner radius describes the solid
-circle within the star where the points begin to separate.
-
-### :items » an array
-
-For: `list_box`.
-
-The list of selections in the list box.  See the [[Element.list_box]] method
-for an example.
-
-### :justify » true or false
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`
-
-Evenly spaces the text horizontally.
-
-### :kerning » a number
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Adds to the natural spacing between letters, in pixels.
-
-### :leading » a number
-
-For: `banner, caption, inscription, para, subtitle, tagline, title`.
-
-Sets the spacing between lines in a text block.  Defaults to 4 pixels.
-
-### :left » a number
-
-For: `all slots and elements`.
-
-Sets the left coordinate of this object to a specific pixel.  Setting `left: 10` places the object's left edge ten pixels away from the left edge of the
-slot containing it.  If this style is left unset (or set to `nil`,) the object
-will flow in with the other objects surrounding it.
-
-You might also want to give it a :top, if it's acting a bit funny. Sometimes it needs both. :)
-
-### :margin » a number or an array of four numbers
-
-For: `all slots and elements`.
-
-Margins space an element out from its surroundings.  Each element has a left,
-top, right, and bottom margin.  If the `:margin` style is set to a single
-number, the spacing around the element uniformly matches that number.  In other
-words, if `margin: 8` is set, all the margins around the element are set to
-eight pixels in length.
-
-This style can also be given an array of four numbers in the form `[left, top,
-right, bottom]`.
-
-### :margin_bottom » a number
-
-For: `all slots and elements`.
-
-Sets the bottom margin of the element to a specific pixel size.
-
-### :margin_left » a number
-
-For: `all slots and elements`.
-
-Sets the left margin of the element to a specific pixel size.
-
-### :margin_right » a number
-
-For: `all slots and elements`.
-
-Sets the right margin of the element to a specific pixel size.
-
-### :margin_top » a number
-
-For: `all slots and elements`.
-
-Sets the top margin of the element to a specific pixel size.
-
-### :outer » a number
-
-For: `star`.
-
-Sets the outer radius (half of the `total` width) of the star, in pixels.
-
-### :points » a number
-
-For: `star`.
-
-How many points does this star have?  A style of `points: 5` creates a
-five-pointed star.
-
-### :radius » a number
-
-For: `arc, arrow, background, border, gradient, oval, rect, shape`.
-
-Sets the radius (half of the diameter or total width) for each of these
-elements.  Setting this is equivalent to setting both `:width` and `:height` to
-double this number.
-
-### :right » a number
-
-For: `all slots and elements`.
-
-Sets the pixel coordinate of an element's right edge.  The edge is placed
-relative to its container's rightmost edge.  So, `right: 0` will align the
-element so that its own right edge and the right edge of its slot touch.
-Whereas `right: 20` will position the right edge of the element off to the
-left of its slot's right edge by twenty pixels.
-
-### :rise » a number
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Lifts or plunges the font baseline for some text.  For example, a
-[[Element.sup]] has a `:rise` of 10 pixels.  Conversely, the [[Element.sub]]
-element has a `:rise` of -10 pixels.
-
-### :scroll » true or false
-
-For: `flow, stack`.
-
-Establishes this slot as a scrolling slot.  If `scroll: true` is set, the
-slot will show a scrollbar if any of its contents go past its height.  The
-scrollbar will appear and disappear as needed.  It will also appear inside the
-width of the slot, meaning the slot's width will never change, regardless of
-whether there is a scrollbar or not.
-
-### :secret » true or false
-
-For: `ask, edit_line`.
-
-Used for password fields, this setting keeps any characters typed in from
-becoming visible on the screen.  Instead, a replacement character (such as an
-asterisk) is show for each letter typed.
-
-### :size » a number
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Sets the pixel size for the font used inside this text block or text fragment.
-
-Font size may also be augmented, through use of the following strings:
-
- * "xx-small" - 57% of present size.
- * "x-small" - 64% of present size.
- * "small" - 83% of present size.
- * "medium" - no change in size.
- * "large" - 120% of present size.
- * "x-large" - 143% of present size.
- * "xx-large" - 173% of present size.
-
-### :state » a string
-
-For: `button, check, edit_box, edit_line, list_box, radio`.
-
-The `:state` style is for disabling or locking certain controls, if you don't
-want them to be edited.
-
-Here are the possible style settings:
-
- * nil - the control is active and editable.
- * "readonly" - the control is active but cannot be edited.
- * "disabled" - the control is not active (grayed out) and cannot be edited.
-
-### :stretch » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Sets the font stretching used for a text object.
-
-Possible settings are:
-
- * "condensed" - a smaller width of letters.
- * "normal" - the standard width of letters.
- * "expanded" - a larger width of letters.
-
-### :strikecolor » a Shoes::Color
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-The color used to paint any lines stricken through this text.
-
-### :strikethrough » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Is this text stricken through?  Two options here:
-
- * "none" - no strikethrough
- * "single" - a single-line strikethrough.
-
-### :stroke » a hex code, a Shoes::Color or a range of either
-
-For: `arc, arrow, banner, border, caption, code, del, em, flow, image, ins,
-inscription, line, link, mask, oval, para, rect, shape, span, stack, star,
-strong, sub, sup, subtitle, tagline, title`.
-
-The color of the foreground pen.  In the case of shapes, this is the color the
-lines are drawn with.  For paragraphs and other text, the letters are printed
-in this color.
-
-### :strokewidth » a number
-
-For: `arc, arrow, border, flow, image, line, mask, oval, rect, shape, star, stack`.
-
-The thickness of the stroke, in pixels, of the line defining each of these
-shapes.  For example, the number two would set the strokewidth to 2 pixels.
-
-### :text » a string
-
-For: `button, edit_box, edit_line`.
-
-Sets the message displayed on a button control, or the contents of an edit_box
-or edit_line.
-
-### :top » a number
-
-For: `all slots and elements`.
-
-Sets the top coordinate for an object, relative to its parent slot.  If an
-object is set with `top: 40`, this means the object's top edge will be
-placed 40 pixels beneath the top edge of the slot that contains it.  If no
-`:top` style is given, the object is automatically placed in the natural flow
-of its slot.
-
-You should probably give it a :left, too, if it's acting strange. It likes to have both. :)
-
-### :undercolor » a Shoes::Color
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-The color used to underline text.
-
-### :underline » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Dictates the style of underline used in the text.
-
-The choices for this setting are:
-
- * "none" - no underline at all.
- * "single" - a continuous underline.
- * "double" - two continuous parallel underlines.
- * "low" - a lower underline, beneath the font baseline.  (This is generally recommended only for single characters, particularly when showing keyboard accelerators.)
- * "error" - a wavy underline, usually found indicating a misspelling.
-
-### :variant » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Vary the font for a group of text.  Two choices:
-
- * "normal" - standard font.
- * "smallcaps" - font with the lower case characters replaced by smaller variants of the capital characters.
-
-### :weight » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`.
-
-Set the boldness of the text.  Commonly, this style is set to one of the
-following strings:
-
- * "ultralight" - the ultralight weight (= 200)
- * "light" - the light weight (= 300)
- * "normal" - the default weight (= 400)
- * "semibold" - a weight intermediate between normal and bold (= 600)
- * "bold" - the bold weight (= 700)
- * "ultrabold" - the ultrabold weight (= 800)
- * "heavy" - the heavy weight (= 900)
-
-However, you may also pass in the numerical weight directly.
-
-### :width » a number
-
-For: `all slots and elements`.
-
-Sets the pixel width for the element.  If the number is a decimal, the width is
-converted to a percentage (with 0.0 being 0% and 1.0 being 100%.)  A width of
-100% means the object fills its parent slot.
-
-### :wrap » a string
-
-For: `banner, caption, code, del, em, ins, inscription, link, para, span,
-strong, sub, sup, subtitle, tagline, title`
-
-How should the text wrap when it fills its width? Possible options are:
-
- * "word" - Break lines at word breaks.
- * "char" - Break lines between characters, thus breaking some words.
- * "trim" - Cut the line off with an ellipsis if it goes too long.
-
-## Classes List
-
-Here is a complete list of all the classes introduced by Shoes.  This chart is
-laid out according to how classes inherits from each other.  Subclasses are
-indented one level to the right, beneath their parent class.
-
-{INDEX}
-
-## Colors List
-
-The following list of colors can be used throughout Shoes.  As background
-colors or border colors.  As stroke and fill colors.  Most of these colors come
-from the X11 and HTML palettes.
-
-All of these colors can be used by name.  (So calling the `tomato` method from
-inside any slot will get you a nice reddish color.)  Below each color, also
-find the exact numbers which can be used with the [[Built-in.rgb]] method.
-
-{COLORS}
-
-# Slots
-
-Slots are boxes used to lay out images, text and so on. The two most common
-slots are `stacks` and `flows`. Slots can also be referred to as "boxes" or
-"canvases" in Shoes terminology.
-
-Since the mouse wheel and PageUp and PageDown are so pervasive on every
-platform, vertical scrolling has really become the only overflow that matters.
-So, in Shoes, just as on the web, width is generally fixed. While height goes
-on and on.
-
-Now, you can also just use specific widths and heights for everything, if you
-want. That'll take some math, but everything could be perfect.
-
-Generally, I'd suggest using stacks and flows. The idea here is that you want
-to fill up a certain width with things, then advance down the page, filling up
-further widths. You can think of these as being analogous to HTML's "block" and
-"inline" styles.
-
-#### Stacks
-
-A stack is simply a vertical stack of elements. Each element in a stack is
-placed directly under the element preceding it.
-
-A stack is also shaped like a box. So if a stack is given a width of 250, that
-stack is itself an element which is 250 pixels wide.
-
-To create a new stack, use the [[Element.stack]] method, which is available
-inside any slot.  So stacks can contain other stacks and flows.
-
-#### Flows
-
-A flow will pack elements in as tightly as it can. A width will be filled, then
-will wrap beneath those elements. Text elements placed next to each other will
-appear as a single paragraph. Images and widgets will run together as a series.
-
-Like the stack, a flow is a box. So stacks and flows can safely be embedded
-and, without respect to their contents, are identical. They just treat their
-contents differently.
-
-Making a flow means calling the [[Element.flow]] method.  Flows may contain
-other flows and stacks.
-
-Last thing: The Shoes window itself is a flow.
-
-## Art for Slots
-
-Each slot is like a canvas, a blank surface which can be covered with an
-assortment of colored shapes or gradients.
-
-Many common shapes can be drawn with methods like `oval` and `rect`.  You'll
-need to set up the paintbrush colors first, though.
-
-The `stroke` command sets the line color.  And the `fill` command sets the
-color used to paint inside the lines.
-
-```ruby
- #!ruby
- Shoes.app do
-   stroke red
-   fill blue
-   oval top: 10, left: 10,
-     radius: 100
- end
-```
-
-That code gives you a blue pie with a red line around it.  One-hundred pixels
-wide, placed just a few pixels southeast of the window's upper left corner.
-
-The `blue` and `red` methods above are Color objects.  See the section on
-Colors for more on how to mix colors.
-
-#### Inspiration from Processing and NodeBox
-
-The artful methods generally come verbatim from NodeBox, a drawing kit for
-Python.  In turn, NodeBox gets much of its ideas from Processing, a Java-like
-language for graphics and animation.  I owe a great debt to the creators of
-these wonderful programs!
-
-Shoes does a few things differently from NodeBox and Processing.  For example,
-Shoes has different color methods, including having its own Color objects,
-though these are very similar to Processing's color methods.  And Shoes also
-allows images and gradients to be used for drawing lines and filling in shapes.
-
-Shoes also borrows some animation ideas from Processing and will continue to
-closely consult Processing's methods as it expands.
-
-### arc(left, top, width, height, angle1, angle2) » Shoes::Shape
-
-Draws an arc shape (a section of an oval) at coordinates (left, top).  This
-method just give you a bit more control than [[oval]], by offering the
-`:angle1` and `:angle2` styles.  (In fact, you can mimick the `oval` method by
-setting `:angle1` to 0 and `:angle2` to `Shoes::TWO_PI`.)
-
-### arrow(left, top, width) » Shoes::Shape
-
-Draws an arrow at coordinates (left, top) with a pixel `width`.
-
-### cap(:curve or :rect or :project) » self
-
-Sets the line cap, which is the shape at the end of every line you draw.  If
-set to `:curve`, the end is rounded.  The default is `:rect`, a line which ends
-abruptly flat.  The `:project` cap is also fat, but sticks out a bit longer.
-
-### fill(pattern) » pattern
-
-Sets the fill bucket to a specific color (or pattern.)  Patterns can be colors,
-gradients or images.  So, once the fill bucket is set, you can draw shapes and
-they will be colored in with the pattern you've chosen.
-
-To draw a star with an image pattern:
-
-```ruby
- #!ruby
- Shoes.app do
-   fill "static/avatar.png"
-   star 200, 200, 5
- end
-```
-
-To clear the fill bucket, use `nofill`.  And to set the line color (the border
-of the star,) use the `stroke` method.
-
-### nofill() » self
-
-Blanks the fill color, so that any shapes drawn will not be filled in.
-Instead, shapes will have only a lining, leaving the middle transparent.
-
-### nostroke() » self
-
-Empties the line color.  Shapes drawn will have no outer line.  If `nofill` is
-also set, shapes drawn will not be visible.
-
-### line(left, top, x2, y2) » Shoes::Shape
-
-Draws a line using the current line color (aka "stroke") starting at
-coordinates (left, top) and ending at coordinates (x2, y2).
-
-### oval(left, top, radius) » Shoes::Shape
-
-Draws a circular form at pixel coordinates (left, top) with a width and height
-of `radius` pixels.  The line and fill colors are used to draw the shape.  By
-default, the coordinates are for the oval's leftmost, top corner, but this can
-be changed by calling the [[Art.transform]] method or by using the `:center`
-style on the next method below.
-
-```ruby
- #!ruby
- Shoes.app do
-   stroke blue
-   strokewidth 4
-   fill black
-   oval 10, 10, 50
- end
-```
-
-To draw an oval of varied proportions, you may also use the syntax: `oval(left, top, width, height)`.
-
-### oval(styles) » Shoes::Shape
-
-Draw circular form using a style hash.  The following styles are supported:
-
- * `top`: the y-coordinate for the oval pen.
- * `left`: the x-coordinate for the oval pen.
- * `radius`: the width and height of the circle.
- * `width`: a specific pixel width for the oval.
- * `height`: a specific pixel height for the oval.
- * `center`: do the coordinates specific the oval's center? (true or false)
-
-These styles may also be altered using the `style` method on the Shape object.
-
-### rect(top, left, width, height, corners = 0) » Shoes::Shape
-
-Draws a rectangle starting from coordinates (top, left) with dimensions of
-width x height.  Optionally, you may give the rectangle rounded corners with a
-fifth argument: the radius of the corners in pixels.
-
-As with all other shapes, the rectangle is drawn using the stroke and fill colors.
-
-```ruby
- #!ruby
- Shoes.app do
-   stroke rgb(0.5, 0.5, 0.7)
-   fill rgb(1.0, 1.0, 0.9)
-   rect 10, 10, self.width - 20, self.height - 20
- end
-```
-
-The above sample draws a rectangle which fills the area of its parent box,
-leaving a margin of 10 pixels around the edge.  Also see the `background`
-method for a rectangle which defaults to filling its parent box.
-
-### rect(styles) » Shoes::Shape
-
-Draw a rectangle using a style hash.  The following styles are supported:
-
- * `top`: the y-coordinate for the rectangle.
- * `left`: the x-coordinate for the rectangle.
- * `curve`: the pixel radius of the rectangle's corners.
- * `width`: a specific pixel width for the rectangle.
- * `height`: a specific pixel height for the rectangle.
- * `center`: do the coordinates specific the rectangle's center? (true or false)
-
-These styles may also be altered using the `style` method on the Shape object.
-
-### rotate(degrees: a number) » self
-
-Rotates the pen used for drawing by a certain number of `degrees`, so that any
-shapes will be drawn at that angle.
-
-In this example below, the rectangle drawn at (30, 30) will be rotated 45 degrees.
-
-```ruby
- #!ruby
- Shoes.app do
-   fill "#333"
-   rotate 45
-   rect 30, 30, 40, 40
- end
-```
-
-### shape(left, top) { ... } » Shoes::Shape
-
-Describes an arbitrary shape to draw, beginning at coordinates (left, top) and
-continued by calls to `line_to`, `move_to`, `curve_to` and `arc_to` inside the
-block.  You can look at it as sketching a shape with a long line that curves
-and arcs and bends.
-
-```ruby
- #!ruby
- Shoes.app do
-   fill red(0.2)
-   shape do
-     move_to(90, 55)
-     arc_to(50, 55, 50, 50, 0, PI/2)
-     arc_to(50, 55, 60, 60, PI/2, PI)
-     arc_to(50, 55, 70, 70, PI, TWO_PI-PI/2)
-     arc_to(50, 55, 80, 80, TWO_PI-PI/2, TWO_PI)
-   end
- end
-```
-
-A shape can also contain other shapes.  So, you can place an [[Art.oval]], a
-[[Art.rect]], a [[Art.line]], a [[Art.star]] or an [[Art.arrow]] (and all of
-the other methods in this [[Art]] section) inside a shape, but they will not be
-part of the line.  They will be more like a group of shapes are all drawn as
-one.
-
-### star(left, top, points = 10, outer = 100.0, inner = 50.0) » Shoes::Shape
-
-Draws a star using the stroke and fill colors.  The star is positioned with its
-center point at coordinates (left, top) with a certain number of `points`.  The
-`outer` width defines the full radius of the star; the `inner` width specifies
-the radius of the star's middle, where points stem from.
-
-### stroke(pattern) » pattern
-
-Set the active line color for this slot.  The `pattern` may be a color, a
-gradient or an image, all of which are categorized as "patterns."  The line
-color is then used to draw the borders of any subsequent shape.
-
-So, to draw an arrow with a red line around it:
-
-```ruby
- #!ruby
- Shoes.app do
-   stroke red
-   arrow 0, 100, 10
- end
-```
-
-To clear the line color, use the `nostroke` method.
-
-### strokewidth(a number) » self
-
-Sets the line size for all drawing within this slot.  Whereas the `stroke`
-method alters the line color, the `strokewidth` method alters the line size in
-pixels.  Calling `strokewidth(4)` will cause lines to be drawn 4 pixels wide.
-
-### transform(:center or :corner) » self
-
-Should transformations (such as `skew` and `rotate`) be performed around the
-center of the shape?  Or the corner of the shape?  Shoes defaults to `:corner`.
-
-### translate(left, top) » self
-
-Moves the starting point of the drawing pen for this slot.  Normally, the pen
-starts at (0, 0) in the top-left corner, so that all shapes are drawn from that
-point.  With `translate`, if the starting point is moved to (10, 20) and a
-shape is drawn at (50, 60), then the shape is actually drawn at (60, 80) on the
-slot.
-
-## Element Creation
-
-Shoes has a wide variety of elements, many cherry-picked from HTML.  This page
-describes how to create these elements in a slot.  See the Elements section of
-the manual for more on how to modify and use these elements after they have
-been placed.
-
-### animate(fps) { |frame| ... } » Shoes::Animation
-
-Starts an animation timer, which runs parallel to the rest of the app.  The
-`fps` is a number, the frames per seconds.  This number dictates how many times
-per second the attached block will be called.
-
-The block is given a `frame` number.  Starting with zero, the `frame` number
-tells the block how many frames of the animation have been shown.
-
-```ruby
- #!ruby
- Shoes.app do
-   @counter = para "STARTING"
-   animate(24) do |frame|
-     @counter.replace "FRAME #{frame}"
-   end
- end
-```
-
-The above animation is shown 24 times per second.  If no number is given, the
-`fps` defaults to 10.
-
-### background(pattern) » Shoes::Background
-
-Draws a Background element with a specific color (or pattern.)  Patterns can be
-colors, gradients or images.  Colors and images will tile across the
-background.  Gradients stretch to fill the background.
-
-`'PLEASE NOTE:`' Backgrounds are actual elements, not styles.  HTML treats
-backgrounds like styles.  Which means every box can only have one background.
-Shoes layers background elements.
-
-```ruby
- #!ruby
- Shoes.app do
-   background black
-   background white, width: 50
- end
-```
-
-The above example paints two backgrounds.  First, a black background is painted
-over the entire app's surface area.  Then a 50 pixel white stripe is painted
-along the left side.
-
-### banner(text) » Shoes::Banner
-
-Creates a Banner text block.  Shoes automatically styles this text to 48 pixels high.
-
-### border(text, strokewidth: a number) » Shoes::Border
-
-Draws a Border element using a specific color (or pattern.)  Patterns can be
-colors, gradients or images.  Colors and images will tile across the border.
-Gradients stretch to fill the border.
-
-`'PLEASE NOTE:`' Like Backgrounds, Borders are actual elements, not styles.
-HTML treats backgrounds and borders like styles.  Which means every box can
-only have one borders.  Shoes layers border and background elements, along with
-text blocks, images, and everything else.
-
-### button(text) { ... } » Shoes::Button
-
-Adds a push button with the message `text` written across its surface.  An
-optional block can be attached, which is called if the button is pressed.
-
-### caption(text) » Shoes::Caption
-
-Creates a Caption text block.  Shoes styles this text to 14 pixels high.
-
-### check() » Shoes::Check
-
-Adds a check box.
-
-### code(text) » Shoes::Code
-
-Create a Code text fragment.  This text defaults to a monospaced font.
-
-### del(text) » Shoes::Del
-
-Creates a Del text fragment (short for "deleted") which defaults to text with a
-single strikethrough in its middle.
-
-### dialog(styles) { ... } » Shoes::App
-
-Opens a new app window (just like the [[Element.window]] method does,) but the
-window is given a dialog box look.
-
-### edit_box(text) » Shoes::EditBox
-
-Adds a large, multi-line textarea to this slot.  The `text` is optional and
-should be a string that will start out the box.  An optional block can be
-attached here which is called any type the user changes the text in the box.
-
-```ruby
- #!ruby
- Shoes.app do
-   edit_box
-   edit_box "HORRAY EDIT ME"
-   edit_box "small one", width: 100, height: 160
- end
-```
-
-### edit_line(text) » Shoes::EditLine
-
-Adds a single-line text box to this slot.  The `text` is optional and should be
-a string that will start out the box.  An optional block can be attached here
-which is called any type the user changes the text in the box.
-
-### em(text) » Shoes::Em
-
-Creates an Em text fragment (short for "emphasized") which, by default, is
-styled with italics.
-
-### every(seconds) { |count| ... } » Shoes::Every
-
-A timer similar to the `animation` method, but much slower.  This timer fires a
-given number of seconds, running the block attached.  So, for example, if you
-need to check a web site every five minutes, you'd call `every(300)` with a
-block containing the code to actually ping the web site.
-
-### flow(styles) { ... } » Shoes::Flow
-
-A flow is an invisible box (or "slot") in which you place Shoes elements.  Both
-flows and stacks are explained in great detail on the main [[Slots]] page.
-
-Flows organize elements horizontally.  Where one would use a [[Element.stack]]
-to keep things stacked vertically, a flow places its contents end-to-end across
-the page.  Once the end of the page is reached, the flow starts a new line of
-elements.
-
-### image(path) » Shoes::Image
-
-Creates an [[Image]] element for displaying a picture.  PNG, JPEG and GIF
-formats are allowed.
-
-The `path` can be a file path or a URL.  All images loaded are temporarily
-cached in memory, but remote images are also cached locally in the user's
-personal Shoes directory.  Remote images are loaded in the background; as with
-browsers, the images will not appear right away, but will be shown when they
-are loaded.
-
-### imagesize(path) » [width, height]
-
-Quickly grab the width and height of an image.  The image won't be loaded into
-the cache or displayed.
-
-URGENT NOTE: This method cannot be used with remote images (loaded from HTTP,
-rather than the hard drive.)
-
-### ins(text) » Shoes::Ins
-
-Creates an Ins text fragment (short for "inserted") which Shoes styles with a
-single underline.
-
-### inscription(text) » Shoes::Inscription
-
-Creates an Inscription text block.  Shoes styles this text at 10 pixels high.
-
-### link(text, click: proc or string) » Shoes::Link
-
-Creates a Link text block, which Shoes styles with a single underline and
-colors with a #06E (blue) colored stroke.
-
-The default LinkHover style is also single-underlined with a #039 (dark blue) stroke.
-
-### list_box(items: [strings, ...]) » Shoes::ListBox
-
-Adds a drop-down list box containing entries for everything in the `items`
-array.  An optional block may be attached, which is called if anything in the
-box becomes selected by the user.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack margin: 10 do
-     para "Pick a card:"
-     list_box items: ["Jack", "Ace", "Joker"]
-   end
- end
-```
-
-Call `ListBox#text` to get the selected string.  See the `ListBox` section
-under `Native` controls for more help.
-
-### progress() » Shoes::Progress
-
-Adds a progress bar.
-
-### para(text) » Shoes::Para
-
-Create a Para text block (short for "paragraph") which Shoes styles at 12
-pixels high.
-
-### radio(group name: a string or symbol) » Shoes::Radio
-
-Adds a radio button.  If a `group name` is given, the radio button is
-considered part of a group.  Among radio buttons in the same group, only one
-may be checked.  (If no group name is given, the radio button is grouped with
-any other radio buttons in the same slot.)
-
-### span(text) » Shoes::Span
-
-Creates a Span text fragment, unstyled by default.
-
-### stack(styles) { ... } » Shoes::Stack
-
-Creates a new stack.  A stack is a type of slot.  (See the main [[Slots]] page
-for a full explanation of both stacks and flows.)
-
-In short, stacks are an invisible box (a "slot") for placing stuff.  As you add
-things to the stack, such as buttons or images, those things pile up
-vertically.  Yes, they stack up!
-
-### strong(text) » Shoes::Strong
-
-Creates a Strong text fragment, styled in bold by default.
-
-### sub(text) » Shoes::Sub
-
-Creates a Sub text fragment (short for "subscript") which defaults to lowering
-the text by 10 pixels and styling it in an x-small font.
-
-### subtitle(text) » Shoes::Subtitle
-
-Creates a Subtitle text block.  Shoes styles this text to 26 pixels high.
-
-### sup(text) » Shoes::Sup
-
-Creates a Sup text fragment (short for "superscript") which defaults to raising
-the text by 10 pixels and styling it in an x-small font.
-
-### tagline(text) » Shoes::Tagline
-
-Creates a Tagline text block.  Shoes styles this text to 18 pixels high.
-
-### timer(seconds) { ... } » Shoes::Timer
-
-A one-shot timer.  If you want to schedule to run some code in a few seconds
-(or minutes, hours) you can attach the code as a block here.
-
-To display an alert box five seconds from now:
-
-```ruby
- #!ruby
- Shoes.app do
-   timer(5) do
-     alert("Your five seconds are up.")
-   end
- end
-```
-
-### title(text) » Shoes::Title
-
-Creates a Title text block.  Shoes styles these elements to 34 pixels high.
-
-### video(path or url) » Shoes::Video
-
-Embeds a movie in this slot.
-
-### window(styles) { ... } » Shoes::App
-
-Opens a new app window.  This method is almost identical to the
-[[App.Shoes.app]] method used to start an app in the first place.  The
-difference is that the `window` method sets the new window's [[App.owner]]
-property.  (A normal Shoes.app has its `owner` set to `nil`.)
-
-So, the new window's `owner` will be set to the Shoes::App which launched the
-window.  This way the child window can call the parent.
-
-```ruby
- #!ruby
- Shoes.app title: "The Owner" do
-   button "Pop up?" do
-     window do
-       para "Okay, popped up from #{owner}"
-     end
-   end
- end
-```
-
-## Events
-
-Wondering how to catch stray mouse clicks or keyboard typing?  Events are sent
-to a slot whenever a mouse moves inside the slot.  Or whenever a key is
-pressed.  Even when the slot is created or destroyed.  You can attach a block
-to each of these events.
-
-Mouse events include `motion`, `click`, `hover` and `leave`.  Keyboard typing
-is represented by the `keypress` event.  And the `start` and `finish` events
-indicate when a canvas comes into play or is discarded.
-
-So, let's say you want to change the background of a slot whenever the mouse
-floats over it.  We can use the `hover` event to change the background when the
-mouse comes inside the slot.  And `leave` to change back when the mouse floats
-away.
-
-```ruby
- #!ruby
- Shoes.app do
-   s = stack width: 200, height: 200 do
-     background red
-     hover do
-       s.clear { background blue }
-     end
-     leave do
-       s.clear { background red }
-     end
-   end
- end
-```
-
-### click { |button, left, top| ... } » self
-
-The click block is called when a mouse button is clicked.  The `button` is the
-number of the mouse button which has been pressed.  The `left` and `top` are
-the mouse coordinates at which the click happened.
-
-To catch the moment when the mouse is unclicked, see the [[Events.release]] event.
-
-### finish { |self| ... } » self
-
-When a slot is removed, it's finish event occurs.  The finish block is
-immediately handed `self`, the slot object which has been removed.
-
-### hover { |self| ... } » self
-
-The hover event happens when the mouse enters the slot.  The block gets `self`,
-meaning the object which was hovered over.
-
-To catch the mouse exiting the slot, check out the [[Events.leave]] event.
-
-### keypress { |key| ... } » self
-
-Whenever a key (or combination of keys) is pressed, the block gets called.  The
-block is sent a `key` which is a string representing the character (such as the
-letter or number) on the key.  For special keys and key combos, a Ruby symbol
-is sent, rather than a string.
-
-So, for example, if `Shift-a` is pressed, the block will get the string `"A"`.
-
-However, if the F1 key is pressed, the `:f1` symbol is received.  For
-`Shift-F1`, the symbol would be `:shift_f1`.
-
-The modifier keys are `control`, `shift` and `alt`.  They appear in that order.
-If `Shift-Control-Alt-PgUp` is pressed, the symbol will be
-`:control_shift_alt_page_up`.
-
-One thing about the shift key.  You won't see the shift key on most keys.  On
-US keyboards, `Shift-7` is an ampersand.  So you'll get the string `"&"` rather
-than `:shift_5`.  And, if you press `Shift-Alt-7` on such a keyboard, you'll
-get the symbol: `:alt_&`.  You'll only see the shift modifier on the special
-keys listed a few paragraphs down.
-
-```ruby
- #!ruby
- Shoes.app do
-   @info = para "NO KEY is PRESSED."
-   keypress do |k|
-     @info.replace "#{k.inspect} was PRESSED."
-   end
- end
-```
-
-Keep in mind that Shoes itself uses a few hotkeys.  Alt-Period (`:alt_.`),
-Alt-Question (`:alt_?`) and Alt-Slash (`:alt_/`) are reserved for Shoes.
-
-The list of special keys is as follows: `:escape`, `:delete`, `:backspace`,
-`:tab`, `:page_up`, `:page_down`, `:home`, `:end`, `:left`, `:up`, `:right`,
-`:down`, `:f1`, `:f2`, `:f3`, `:f4`, `:f5`, `:f6`, `:f7`, `:f8`, `:f9`, `:f10`,
-`:f11` and `:f12`.
-
-One caveat to all of those rules: normally the Return key gives you a string
-`"\n"`.  When pressed with modifier keys, however, you end up with
-`:control_enter`, `:control_alt_enter`, `:shift_alt_enter` and the like.
-
-### leave { |self| ... } » self
-
-The leave event takes place when the mouse cursor exits a slot.  The moment it
-no longer is inside the slot's edges.  When that takes place, the block is
-called with `self`, the slot object which is being left.
-
-Also see [[Events.hover]] if you'd like to detect the mouse entering a slot.
-
-### motion { |left, top| ... } » self
-
-The motion block gets called every time the mouse moves around inside the slot.
-The block is handed the cursor's `left` and `top` coordinates.
-
-```ruby
- #!ruby
- Shoes.app width: 200, height: 200 do
-   background black
-   fill white
-   @circ = oval 0, 0, 100, 100
-
-   motion do |top, left|
-     @circ.move top - 50, left - 50
-   end
- end
-```
-
-### release { |button, left, top| ... } » self
-
-The release block runs whenever the mouse is unclicked (on mouse up).  When the
-finger is lifted.  The `button` is the number of the button that was depressed.
-The `left` and `top` are the coordinates of the mouse at the time the button
-was released.
-
-To catch the actual mouse click, use the [[Events.click]] event.
-
-### start { |self| ... } » self
-
-The first time the slot is drawn, the start event fires.  The block is handed
-`self`, the slot object which has just been drawn.
-
-## Manipulation Blocks
-
-The manipulation methods below make quick work of shifting around slots and
-inserting new elements.
-
-### append() { ... } » self
-
-Adds elements to the end of a slot.
-
-```ruby
- #!ruby
- Shoes.app do
-   @slot = stack { para 'Good Morning' }
-   timer 3 do
-     @slot.append do
-       title "Breaking News"
-       tagline "Astronauts arrested for space shuttle DUI."
-     end
-   end
- end
-```
-
-The `title` and `tagline` elements will be added to the end of the `@slot`.
-
-### after(element) { ... } » self
-
-Adds elements to a specific place in a slot, just after the `element` which is
-a child of the slot.
-
-### before(element) { ... } » self
-
-Adds elements to a specific place in a slot, just before the `element` which is
-a child of the slot.
-
-### clear() » self
-
-Empties the slot of any elements, timers and nested slots.  This is effectively
-identical to looping through the contents of the slot and calling each
-element's `remove` method.
-
-### clear() { ... } » self
-
-The clear method also takes an optional block.  The block will be used to
-replace the contents of the slot.
-
-```ruby
- #!ruby
- Shoes.app do
-   @slot = stack { para "Old text" }
-   timer 3 do
-     @slot.clear { para "Brand new text" }
-   end
- end
-```
-
-In this example, the "Old text" paragraph will be cleared out, replaced by the
-"Brand new text" paragraph.
-
-### prepend() { ... } » self
-
-Adds elements to the beginning of a slot.
-
-```ruby
- #!ruby
- Shoes.app do
-   @slot = stack { para 'Good Morning' }
-   timer 3 do
-     @slot.prepend { para "Your car is ready." }
-   end
- end
-```
-
-The `para` element is added to the beginning of the `@slot`.
-
-## Position of a Slot
-
-Like any other element, slots can be styled and customized when they are created.
-
-To set the width of a stack to 150 pixels:
-
-```ruby
- #!ruby
- Shoes.app do
-   stack(width: 150) { para "Now that's precision." }
- end
-```
-
-Each style setting also has a method, which can be used to grab that particular
-setting.  (So, like, the `width` method returns the width of the slot in
-pixels.)
-
-### displace(left: a number, top: a number) » self
-
-A shortcut method for setting the :displace_left and :displace_top styles.
-Displacing is a handy way of moving a slot without altering the layout.  In
-fact, the `top` and `left` methods will not report displacement at all.  So,
-generally, displacement is only for temporary animations.  For example,
-jiggling a button in place.
-
-The `left` and `top` numbers sent to `displace` are added to the slot's own
-top-left coordinates.  To subtract from the top-left coordinate, use negative
-numbers.
-
-### gutter() » a number
-
-The size of the scrollbar area.  When Shoes needs to show a scrollbar, the
-scrollbar may end up covering up some elements that touch the edge of the
-window.  The `gutter` tells you how many pixels to expect the scrollbar to
-cover.
-
-This is commonly used to pad elements on the right, like so:
-
-```ruby
- #!ruby
- Shoes.app do
-   stack margin_right: 20 + gutter do
-     para "Insert fat and ratified declaration of independence here..."
-   end
- end
-```
-
-### height() » a number
-
-The vertical size of the viewable slot in pixels.  So, if this is a scrolling
-slot, you'll need to use `scroll_height()` to get the full size of the slot.
-
-### hide() » self
-
-Hides the slot, so that it can't be seen.  See also [[Position.show]] and [[Position.toggle]].
-
-### left() » a number
-
-The left pixel location of the slot.  Also known as the x-axis coordinate.
-
-### move(left, top) » self
-
-Moves the slot to specific coordinates, the (left, top) being the upper left
-hand corner of the slot.
-
-### remove() » self
-
-Removes the slot. It will no longer be displayed and will not be listed in its
-parent's contents. It's gone.
-
-### scroll() » true or false
-
-Is this slot allowed to show a scrollbar? True or false. The scrollbar will
-only appear if the height of the slot is also fixed.
-
-### scroll_height() » a number
-
-The vertical size of the full slot, including any of it which is hidden by scrolling.
-
-### scroll_max() » a number
-
-The top coordinate which this slot can be scrolled down to.  The top coordinate
-of a scroll bar is always zero.  The bottom coordinate is the full height of
-the slot minus one page of scrolling.  This bottom coordinate is what
-`scroll_max` returns.
-
-This is basically a shortcut for writing `slot.scroll_height - slot.height`.
-
-To scroll to the bottom of a slot, use `slot.scroll_top = slot.scroll_max`.
-
-### scroll_top() » a number
-
-The top coordinate which this slot is scrolled down to.  So, if the slot is
-scrolled down twenty pixels, this method will return `20`.
-
-### scroll_top = a number
-
-Scrolls the slot to a certain coordinate.  This must be between zero and
-`scroll_max`.
-
-### show() » self
-
-Reveals the slot, if it is hidden.  See also [[Position.hide]] and
-[[Position.toggle]].
-
-### style() » styles
-
-Calling the `style` method with no arguments returns a hash of the styles
-presently applied to this slot.
-
-While methods such as `height` and `width` return the true pixel dimensions of
-the slot, you can use `style[:height]` or `style[:width]` to get the dimensions
-originally requested.
-
-```ruby
- #!ruby
- Shoes.app do
-   @s = stack width: "100%"
-   para @s.style[:width]
- end
-```
-
-In this example, the paragraph under the stack will display the string "100%".
-
-### style(styles) » styles
-
-Alter the slot using a hash of style settings.  Any of the methods on this page
-(aside from this method, of course) can be used as a style setting.  So, for
-example, there is a `width` method, thus there is also a `width` style.
-
-```ruby
- #!ruby
- Shoes.app do
-   @s = stack { background green }
-   @s.style(width: 400, height: 200)
- end
-```
-
-### toggle() » self
-
-Hides the slot, if it is shown.  Or shows the slot, if it is hidden.
-
-### top() » a number
-
-The top pixel location of the slot.  Also known as the y-axis coordinate.
-
-### width() » a number
-
-The horizontal size of the slot in pixels.
-
-## Traversing the Page
-
-You may find yourself needing to loop through the elements inside a slot. Or
-maybe you need to climb the page, looking for a stack that is the parent of an
-element.
-
-On any element, you may call the `parent` method to get the slot directly above
-it. And on slots, you can call the `contents` method to get all of the
-children. (Some elements, such as text blocks, also have a `contents` method
-for getting their children.)
-
-### contents() » an array of elements
-
-Lists all elements in a slot.
-
-### parent() » a Shoes::Stack or Shoes::Flow
-
-Gets the object for this element's container.
-
-# Elements
-
-Ah, here's the stuff of Shoes. An element can be as simple as an oval shape. Or
-as complex as a video stream. You've encountered all of these elements before
-in the Slots section of the manual.
-
-Shoes has seven native controls: the Button, the EditLine, the EditBox, the
-ListBox, the Progress meter, the Check box and the Radio.  By "native"
-controls, we mean that each of these seven elements is drawn by the operating
-system.  So, a Progress bar will look one way on Windows and another way on OS
-X.
-
-Shoes also has seven basic other types of elements: Background, Border, Image,
-Shape, TextBlock, Timer and Video.  These all should look and act the same on
-every operating system.
-
-Once an element is created, you will often still want to change it. To move it
-or hide it or get rid of it. You'll use the commands in this section to do that
-sort of stuff. (Especially check out the [[Common Common Methods]] section for
-commands you can use on any element.)
-
-So, for example, use the `image` method of a Slot to place a PNG on the screen.
-The `image` method gives you back an Image object. Use the methods of the Image
-object to change things up.
-
-## Common Methods
-
-A few methods are shared by every little element in Shoes.  Moving, showing,
-hiding.  Removing an element.  Basic and very general things.  This list
-encompasses those common commands.
-
-One of the most general methods of all is the `style` method (which is also
-covered as the [[Position.style]] method for slots.)
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     # Background, text and a button: both are elements!
-     @back  = background green
-     @text  = banner "A Message for You, Rudy"
-     @press = button "Stop your messin about!"
-
-     # And so, both can be styled.
-     @text.style size: 12, stroke: red, margin: 10
-     @press.style width: 400
-     @back.style height: 10
-   end
- end
-```
-
-For specific commands, see the other links to the left in the Elements section.
-Like if you want to pause or play a video file, check the [[Video]] section,
-since pausing and playing is peculiar to videos.  No sense pausing a button.
-
-### displace(left: a number, top: a number) » self
-
-Displacing an element moves it.  But without changing the layout around it.
-This is great for subtle animations, especially if you want to reserve a place
-for an element while it is still animating.  Like maybe a quick button shake or
-a slot sliding into view.
-
-When you displace an element, it moves relative to the upper-left corner where
-it was placed.  So, if an element is at the coordinates (20, 40) and you
-displace it 2 pixels left and 6 pixels on top, you end up with the coordinates
-(22, 46).
-
-```ruby
- #!ruby
- Shoes.app do
-   flow margin: 12 do
-     # Set up three buttons
-     button "One"
-     @two = button "Two"
-     button "Three"
-
-     # Bounce the second button
-     animate do |i|
-       @two.displace(0, (Math.sin(i) * 6).to_i)
-     end
-   end
- end
-```
-
-Notice that while the second button bounces, the other two buttons stay put.
-If we used a normal `move` in this situation, the second button would be moved
-out of the layout and the buttons would act as if the second button wasn't
-there at all.  (See the [[Common.move]] example.)
-
-`'Of particular note:`' if you use the `left` and `top` methods to get the
-coordinates of a displaced element, you'll just get back the normal
-coordinates.  As if there was no displacement.  Displacing is just intended for
-quick animations!
-
-### height() » a number
-
-The vertical screen size of the element in pixels. In the case of images, this
-is not the full size of the image. This is the height of the element as it is
-shown right now.
-
-If you have a 150x150 pixel image and you set the width to 50 pixels, this
-method will return 50.
-
-Also see the [[Common.width]] method for an example and some other comments.
-
-### hide() » self
-
-Hides the element, so that it can't be seen.  See also [[Common.show]] and
-[[Common.toggle]].
-
-### left() » a number
-
-Gets you the pixel position of the left edge of the element.
-
-### move(left: a number, top: a number) » self
-
-Moves the element to a specific pixel position within its slot.  The element is
-still inside the slot.  But it will no longer be stacked or flowed in with the
-other stuff in the slot.  The element will float freely, now absolutely
-positioned instead.
-
-```ruby
- #!ruby
- Shoes.app do
-   flow margin: 12 do
-     # Set up three buttons
-     button "One"
-     @two = button "Two"
-     button "Three"
-
-     # Bounce the second button
-     animate do |i|
-       @two.move(40, 40 + (Math.sin(i) * 6).to_i)
-     end
-   end
- end
-```
-
-The second button is moved to a specific place, allowing the third button to
-slide over into its place.  If you want to move an element without shifting
-other pieces, see the [[Common.displace]] method.
-
-### parent() » a Shoes::Stack or Shoes::Flow
-
-Gets the object for this element's container.  Also see the slot's
-[[Traversing.contents]] to do the opposite: get a container's elements.
-
-### remove() » self
-
-Removes the element from its slot.  (In other words: throws it in the garbage.)
-The element will no longer be displayed.
-
-### show() » self
-
-Reveals the element, if it is hidden.  See also [[Common.hide]] and
-[[Common.toggle]].
-
-### style() » styles
-
-Gives you the full set of styles applied to this element, in the form of a
-Hash.  While methods like `width` and `height` and `top` give you back specific
-pixel dimensions, using `style[:width]` or `style[:top]`, you can get the
-original setting (things like "100%" for width or "10px" for top.)
-
-```ruby
- #!ruby
- Shoes.app do
-   # A button which take up the whole page
-   @b = button "All of it", width: 1.0, height: 1.0
-
-   # When clicked, show the styles
-   @b.click { alert(@b.style.inspect) }
- end
-```
-
-### style(styles) » styles
-
-Changes the style of an element.  This could include the `:width` and `:height`
-of an element, the font `:size` of some text, the `:stroke` and `:fill` of a
-shape.  Or any other number of style settings.
-
-### toggle() » self
-
-Hides an element if it is shown.  Or shows the element, if it is hidden.
-
-### top() » a number
-
-Gets the pixel position of the top edge of the element.
-
-### width() » a number
-
-Gets the pixel width for the full size of the element.  This method always
-returns an exact pixel size.  In the case of images, this is not the full width
-of the image, just the size it is shown at.  See the [[Common.height]] method
-for more.
-
-Also, if you create an element with a width of 100% and that element is inside
-a stack which is 120 pixels wide, you'll get back `120`.  However, if you call
-`style[:width]`, you'll get `"100%"`.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack width: 120 do
-     @b = button "Click me", width: "100%" do
-       alert "button.width = #{@b.width}\n" +
-         "button.style[:width] = #{@b.style[:width]}"
-     end
-   end
- end
-```
-
-In order to set the width, you'll have to go through the [[Common.style]]
-method again.  So, to set the button to 150 pixels wide: `@b.style(width: 150)`.
-
-To let Shoes pick the element's width, go with `@b.style(width: nil)` to
-empty out the setting.
-
-## Background
-
-A background is a color, a gradient or an image that is painted across an
-entire slot.  Both backgrounds and borders are a type of Shoes::Pattern.
-![man-ele-background.png](man-ele-background.png)
-
-Even though it's called a `background`, you may still place this element in
-front of other elements.  If a background comes after something else painted on
-the slot (like a `rect` or an `oval`,) the background will be painted over that
-element.
-
-The simplest background is just a plain color background, created with the
-[[Element.background]] method, such as this black background:
-
-```ruby
- #!ruby
- Shoes.app do
-   background black
- end
-```
-
-A simple background like that paints the entire slot that contains it.  (In
-this case, the whole window is painted black.)
-
-You can use styles to cut down the size or move around the background to your liking.
-
-To paint a black background across the top fifty pixels of the window:
-
-```ruby
- #!ruby
- Shoes.app do
-   background black, height: 50
- end
-```
-
-Or, to paint a fifty pixel column on the right-side of the window:
-
-```ruby
- #!ruby
- Shoes.app do
-   background black, width: 50, right: 50
- end
-```
-
-Since Backgrounds are normal elements as well, see also the start of the
-[[Elements]] section for all of its other methods.
-
-### to_pattern() » a Shoes::Pattern
-
-Yanks out the color, gradient or image used to paint this background and places
-it in a normal Shoes::Pattern object.  You can then pass that object to other
-backgrounds and borders.  Reuse it as you like.
-
-## Border
-
-A border is a color, gradient or image painted in a line around the edge of any
-slot.  Like the Background element in the last section, a Border is a kind of
-Shoes::Pattern. ![man-ele-border.png](man-ele-border.png)
-
-The first, crucial thing to know about border is that all borders paint a line
-around the `'inside`' of a slot, not the outside.  So, if you have a slot
-which is fifty pixels wide and you paint a five pixel border on it, that means
-there is a fourty pixel wide area inside the slot which is surrounded by the
-border.
-
-This also means that if you paint a Border on top of a [[Background]], the
-edges of the background will be painted over by the border.
-
-Here is just such a slot:
-
-```ruby
- #!ruby
- Shoes.app do
-   stack width: 50 do
-     border black, strokewidth: 5
-     para "=^.^=", stroke: green
-   end
- end
-```
-
-If you want to paint a border around the outside of a slot, you'll need to wrap
-that slot in another slot.  Then, place the border in the outside slot.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack width: 60 do
-     border black, strokewidth: 5
-     stack width: 50 do
-       para "=^.^=", stroke: green
-     end
-   end
- end
-```
-
-In HTML and many other languages, the border is painted on the outside of the
-box, thus increasing the overall width of the box.  Shoes was designed with
-consistency in mind, so that if you say that a box is fifty pixels wide, it
-stays fifty pixels wide regardless of its borders or margins or anything else.
-
-Please also check out the [[Elements]] section for other methods used on borders.
-
-### to_pattern() » a Shoes::Pattern
-
-Creates a basic pattern object based on the color, gradient or image used to
-paint this border.  The pattern may then be re-used in new borders and
-backgrounds.
-
-## Button
-
-Buttons are, you know, push buttons.  You click them and they do something.
-Buttons are known to say "OK" or "Are you sure?"  And, then, if you're sure,
-you click the button. ![man-ele-button.png](man-ele-button.png)
-
-```ruby
- #!ruby
- Shoes.app do
-   button "OK!"
-   button "Are you sure?"
- end
-```
-
-The buttons in the example above don't do anything when you click them. In
-order to get them to work, you've got to hook up a block to each button.
-
-```ruby
- #!ruby
- Shoes.app do
-   button "OK!" do
-     append { para "Well okay then." }
-   end
-   button "Are you sure?" do
-     append { para "Your confidence is inspiring." }
-   end
- end
-```
-
-So now we've got blocks for the buttons. Each block appends a new paragraph to
-the page. The more you click, the more paragraphs get added.
-
-It doesn't go much deeper than that. A button is just a clickable phrase.
-
-Just to be pedantic, though, here's another way to write that last example.
-
-```ruby
- #!ruby
- Shoes.app do
-   @b1 = button "OK!"
-   @b1.click { para "Well okay then." }
-   @b2 = button "Are you sure?"
-   @b2.click { para "Your confidence is inspiring." }
- end
-```
-
-This looks dramatically different, but it does the same thing.  The first
-difference: rather than attaching the block directly to the button, the block
-is attached later, through the `click` method.
-
-The second change isn't related to buttons at all.  The `append` block was
-dropped since Shoes allows you to add new elements directly to the slot.  So we
-can just call `para` directly.  (This isn't the case with the `prepend`,
-`before` or `after` methods.)
-
-Beside the methods below, buttons also inherit all of the methods that are
-[[Common]].
-
-### click() { |self| ... } » self
-
-When a button is clicked, its `click` block is called.  The block is handed
-`self`.  Meaning: the button which was clicked.
-
-### focus() » self
-
-Moves focus to the button.  The button will be highlighted and, if the user
-hits Enter, the button will be clicked.
-
-## Check
-
-Check boxes are clickable square boxes than can be either checked or unchecked.
-A single checkbox usually asks a "yes" or "no" question.  Sets of checkboxes
-are also seen in to-do lists. ![man-ele-check.png](man-ele-check.png)
-
-Here's a sample checklist.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     flow { check; para "Frances Johnson" }
-     flow { check; para "Ignatius J. Reilly" }
-     flow { check; para "Winston Niles Rumfoord" }
-   end
- end
-```
-
-You basically have two ways to use a check.  You can attach a block to the
-check and it'll get called when the check gets clicked.  And/or you can just
-use the `checked?` method to go back and see if a box has been checked or not.
-
-Okay, let's add to the above example.
-
-```ruby
- #!ruby
- Shoes.app do
-   @list = ['Frances Johnson', 'Ignatius J. Reilly',
-     'Winston Niles Rumfoord']
-
-   stack do
-     @list.map! do |name|
-       flow { @c = check; para name }
-       [@c, name]
-     end
-
-     button "What's been checked?" do
-       selected = @list.map { |c, name| name if c.checked? }.compact
-       alert("You selected: " + selected.join(', '))
-     end
-   end
- end
-```
-
-So, when the button gets pressed, each of the checks gets asked for its status,
-using the `checked?` method.
-
-Button methods are listed below, but also see the list of [[Common]] methods,
-which all elements respond to.
-
-### checked?() » true or false
-
-Returns whether the box is checked or not.  So, `true` means "yes, the box is checked!"
-
-### checked = true or false
-
-Marks or unmarks the check box.  Using `checked = false`, for instance,
-unchecks the box.
-
-### click() { |self| ... } » self
-
-When the check is clicked, its `click` block is called.  The block is handed
-`self`, which is the check object which was clicked.
-
-Clicks are sent for both checking and unchecking the box.
-
-### focus() » self
-
-Moves focus to the check.  The check will be highlighted and, if the user hits
-Enter, the check will be toggled between its checked and unchecked states.
-
-## EditBox
-
-Edit boxes are wide, rectangular boxes for entering text.  On the web, they
-call these textareas.  These are multi-line edit boxes for entering longer
-descriptions.  Essays, even![man-ele-editbox.png](man-ele-editbox.png)
-
-Without any other styling, edit boxes are sized 200 pixels by 108 pixels.  You
-can also use `:width` and `:height` styles to set specific sizes.
-
-```ruby
- #!ruby
- Shoes.app do
-   edit_box
-   edit_box width: 100, height: 100
- end
-```
-
-Other controls (like [[Button]] and [[Check]]) have only click events, but both
-[[EditLine]] and EditBox have a `change` event.  The `change` block is called
-every time someone types into or deletes from the box.
-
-```ruby
- #!ruby
- Shoes.app do
-   edit_box do |e|
-     @counter.text = e.text.size
-   end
-   @counter = strong("0")
-   para @counter, " characters"
- end
-```
-
-Notice that the example also uses the [[EditBox.text]] method inside the block.
-That method gives you a string of all the characters typed into the box.
-
-More edit box methods are listed below, but also see the list of [[Common]]
-methods, which all elements respond to.
-
-### change() { |self| ... } » self
-
-Each time a character is added to or removed from the edit box, its `change`
-block is called. The block is given `self`, which is the edit box object which
-has changed.
-
-### focus() » self
-
-Moves focus to the edit box. The edit box will be highlighted and the user will
-be able to type into the edit box.
-
-### text() » self
-
-Return a string of characters which have been typed into the box.
-
-### text = a string
-
-Fills the edit box with the characters of `a string`.
-
-## EditLine
-
-Edit lines are a slender, little box for entering text. While the EditBox is
-multi-line, an edit line is just one. Line, that is. Horizontal, in fact.
-![man-ele-editline.png](man-ele-editline.png)
-
-The unstyled edit line is 200 pixels wide and 28 pixels wide. Roughly. The
-height may vary on some platforms.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     edit_line
-     edit_line width: 400
-   end
- end
-```
-
-You can change the size by styling both the `:width` and the `:height`.
-However, you generally only want to style the `:width`, as the height will be
-sized to fit the font. (And, in current versions of Shoes, the font for edit
-lines and edit boxes cannot be altered anyway.)
-
-If a block is given to an edit line, it receives `change` events. Check out the
-[[EditBox]] page for an example of using a change block. In fact, the edit box
-has all the same methods as an edit line. Also see the list of [[Common]]
-methods, which all elements respond to.
-
-### change() { |self| ... } » self
-
-Each time a character is added to or removed from the edit line, its `change`
-block is called. The block is given `self`, which is the edit line object which
-has changed.
-
-### focus() » self
-
-Moves focus to the edit line. The edit line will be highlighted and the user
-will be able to type into the edit line.
-
-### text() » self
-
-Return a string of characters which have been typed into the box.
-
-### text = a string
-
-Fills the edit line with the characters of `a string`.
-
-## Image
-
-An image is a picture in PNG, JPEG or GIF format. Shoes can resize images or
-flow them in with text. Images can be loaded from a file or directly off the
-web. ![man-ele-image.png](man-ele-image.png)
-
-To create an image, use the `image` method in a slot:
-
-```ruby
- #!ruby
- Shoes.app do
-   para "Nice, nice, very nice.  Busy, busy, busy."
-   image "static/shoes-manual-apps.gif"
-  end
-```
-
-When you load any image into Shoes, it is cached in memory. This means that if
-you load up many image elements from the same file, it'll only really load the
-file once.
-
-You can use web URLs directly as well.
-
-```ruby
- #!ruby
- Shoes.app do
-   image "http://hacketyhack.heroku.com/images/logo.png"
- end
-```
-
-When an image is loaded from the web, it's cached on the hard drive as well as
-in memory. This prevents a repeat download unless the image has changed. (In
-case you're wondering: Shoes keeps track of modification times and etags just
-like a browser would.)
-
-Shoes also loads remote images in the background using system threads. So,
-using remote images will not block Ruby or any intense graphical displays you
-may have going on.
-
-### full_height() » a number
-
-The full pixel height of the image. Normally, you can just use the
-[[Common.height]] method to figure out how many pixels high the image is. But
-if you've resized the image or styled it to be larger or something, then
-`height` will return the scaled size.
-
-The `full_height` method gives you the height of image (in pixels) as it was
-stored in the original file.
-
-### full_width() » a number
-
-The full pixel width of the image. See the [[Image.full_height]] method for an
-explanation of why you might use this method rather than [[Common.width]].
-
-### path() » a string
-
-The URL or file name of the image.
-
-### path = a string
-
-Swaps the image with a different one, loaded from a file or URL.
-
-## ListBox
-
-List boxes (also called "combo boxes" or "drop-down boxes" or "select boxes" in
-some places) are a list of options that drop down when you click on the box.
-![man-ele-listbox.png](man-ele-listbox.png)
-
-A list box gets its options from an array.  An array (a list) of strings,
-passed into the `:items` style.
-
-```ruby
- #!ruby
- Shoes.app do
-   para "Choose a fruit:"
-   list_box items: ["Grapes", "Pears", "Apricots"]
- end
-```
-
-So, the basic size of a list box is about 200 pixels wide and 28 pixels high.
-You can adjust this length using the `:width` style.
-
-```ruby
- #!ruby
- Shoes.app do
-   para "Choose a fruit:"
-   list_box items: ["Grapes", "Pears", "Apricots"],
-     width: 120, choose: "Apricots" do |list|
-       @fruit.text = list.text
-   end
-
-   @fruit = para "No fruit selected"
- end
-```
-
-Next to the `:width` style, the example uses another useful option. The
-`:choose` option tells the list box which of the items should be highlighted
-from the beginning. (There's also a [[ListBox.choose]] method for highlighting
-an item after the box is created.)
-
-List boxes also have a [[ListBox.change]] event. In the last example, we've got
-a block hooked up to the list box. Well, okay, see, that's a `change` block.
-The block is called each time someone changes the selected item.
-
-Those are the basics. Might you also be persuaded to look at the [[Common]]
-methods page, a complete list of the methods that all elements have?
-
-### change() { |self| ... } » self
-
-Whenever someone highlights a new option in the list box (by clicking on an
-item, for instance,) its `change` block is called. The block is given `self`,
-which is the list box object which has changed.
-
-### choose(item: a string) » self
-
-Selects the option in the list box that matches the string given by `item`.
-
-### focus() » self
-
-Moves focus to the list box. The list box will be highlighted and, if the user
-hits the up and down arrow keys, other options in the list will be selected.
-
-### items() » an array of strings
-
-Returns the complete list of strings that the list box presently shows as its options.
-
-### items = an array of strings
-
-Replaces the list box's options with a new list of strings.
-
-### text() » a string
-
-A string containing whatever text is shown highlighted in the list box right
-now. If nothing is selected, `nil` will be the reply.
-
-## Progress
-
-Progress bars show you how far along you are in an activity. Usually, a
-progress bar represents a percentage (from 0% to 100%.) Shoes thinks of
-progress in terms of the decimal numbers 0.0 to 1.0. ![man-ele-progress.png](man-ele-progress.png)
-
-A simple progress bar is 200 pixels wide, but you can use the `:width` style
-(as with all Shoes elements) to lengthen it.
-
-```ruby
- Shoes.app do
-   stack margin: 0.1 do
-     title "Progress example"
-     @p = progress width: 1.0
-
-     animate do |i|
-       @p.fraction = (i % 100) / 100.0
-     end
-   end
- end
-```
-
-Take a look at the [[Common]] methods page for a list of methods found an all
-elements, including progress bars.
-
-### fraction() » a decimal number
-
-Returns a decimal number from 0.0 to 1.0, indicating how far along the progress bar is.
-
-### fraction = a decimal number
-
-Sets the progress to a decimal number between 0.0 and 1.0.
-
-## Radio
-
-Radio buttons are a group of clickable circles. Click a circle and it'll be
-marked. Only one radio button can be marked at a time. (This is similar to the
-ListBox, where only one option can be selected at a time.) ![man-ele-radio.png](man-ele-radio.png)
-
-So, how do you decide when to use radio buttons and when to use list boxes?
-Well, list boxes only show one highlighted item unless you click on the box and
-the drop-down appears. But radio buttons are all shown, regardless of which is
-marked.
-
-```ruby
- #!ruby
- Shoes.app do
-   para "Among these films, which do you prefer?\n"
-   radio; para strong("The Taste of Tea"), " by Katsuhito Ishii\n"
-   radio; para strong("Kin-Dza-Dza"), " by Georgi Danelia\n"
-   radio; para strong("Children of Heaven"), " by Majid Majidi\n"
- end
-```
-
-Only one of these three radios can be checked at a time, since they are grouped
-together in the same slot (along with a bunch of `para`.)
-
-If we move them each into their own slot, the example breaks.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     para "Among these films, which do you prefer?"
-     flow { radio; para "The Taste of Tea by Katsuhito Ishii" }
-     flow { radio; para "Kin-Dza-Dza by Georgi Danelia" }
-     flow { radio; para "Children of Heaven by Majid Majidi" }
-   end
- end
-```
-
-This can be fixed, though. You can group together radios from different slots,
-you just have to give them all the same group name.
-
-Here, let's group all these radios in the `:films` group.
-
-```ruby
- #!ruby
- Shoes.app do
-   stack do
-     para "Among these films, which do you prefer?"
-     flow do
-       radio :films
-       para "The Taste of Tea by Katsuhito Ishii"
-     end
-     flow do
-       radio :films
-       para "Kin-Dza-Dza by Georgi Danelia"
-     end
-     flow do
-       radio :films
-       para "Children of Heaven by Majid Majidi"
-     end
-   end
- end
-```
-
-For more methods beyond those listed below, also look into the [[Common]]
-methods page. Because you get those methods on every radio as well.
-
-### checked?() » true or false
-
-Returns whether the radio button is checked or not. So, `true` means "yes, it
-is checked!"
-
-### checked = true or false
-
-Marks or unmarks the radio button. Using `checked = false`, for instance,
-clears the radio.
-
-### click() { |self| ... } » self
-
-When the radio button is clicked, its `click` block is called. The block is
-handed `self`, which is an object representing the radio which was clicked.
-
-Clicks are sent for both marking and unmarking the radio.
-
-### focus() » self
-
-Moves focus to the radio. The radio will be highlighted and, if the user hits
-Enter, the radio will be toggled between its marked and unmarked states.
-
-## Shape
-
-A shape is a path outline usually created by drawing methods like `oval` and
-`rect`. ![man-ele-shape.png](man-ele-shape.png)
-
-See the [[Common]] methods page.  Shapes respond to all of those methods.
-
-## TextBlock
-
-The TextBlock object represents a group of text organized as a single element.
-A paragraph containing bolded text, for example. A caption containing links and
-bolded text. (So, a `caption` is a TextBlock type.  However, `link` and
-`strong` are TextClass types.) ![man-ele-textblock.png](man-ele-textblock.png)
-
-All of the various types of TextBlock are found on the [[Element Element
-Creation]] page.
-
- * [[Element.banner]], a 48 pixel font.
- * [[Element.title]], a 34 pixel font.
- * [[Element.subtitle]], a 26 pixel font.
- * [[Element.tagline]], an 18 pixel font.
- * [[Element.caption]], a 14 pixel font.
- * [[Element.para]], a 12 pixel font.
- * [[Element.inscription]], a 10 pixel font.
-
-### contents() » an array of elements
-
-Lists all of the strings and styled text objects inside this block.
-
-### replace(a string)
-
-Replaces the text of the entire block with the characters of `a string`.
-
-### text() » a string
-
-Return a string of all of the characters in this text box. This will strip off
-any style or text classes and just return the actual characters, as if seen on
-the screen.
-
-### text = a string
-
-Replaces the text of the entire block with the characters of `a string`.
-
-### to_s() » a string
-
-An alias for [[TextBlock.text]]. Returns a flattened string of all of this
-TextBlock's contents.
-
-## Timers
-
-Shoes contains three timer classes: the Animation class, the Every class and
-the Timer class. Both Animations and Everies loop over and over after they
-start.  Timers happen once. A one-shot timer.
-
-Animations and Everies are basically the same thing. The difference is that
-Animations usually happen many, many times per second. And Everies happen only
-once every few seconds or rarely.
-
-### start() » self
-
-Both types of timers automatically start themselves, so there's no need to use
-this normally. But if you [[Timers.stop]] a timer and would like to start it up
-again, then by all means: use this!
-
-### stop() » self
-
-Pauses the animation or timer. In the case of a one-shot timer that's already
-happened, it's already stopped and this method will have no effect.
-
-### toggle() » self
-
-If the animation or timer is stopped, it is started. Otherwise, if it is
-already running, it is stopped.
-
-## Video
-
-Shoes supports embedding of QuickTime, Flash video (FLV), DivX, Xvid and
-various other popular video formats. This is all thanks to VideoLAN and ffmpeg,
-two sensational open source libraries. Use the `video` method on a slot to
-setup a Shoes::Video object. ![man-ele-video.png](man-ele-video.png)
-
-In addition to video formats, some audio formats are also supported, such as
-MP3, WAV and Ogg Vorbis.
-
-Video support is optional in Shoes and some builds do not support video. For
-example, video support is unavailable for PowerPC. When you download Shoes, the
-build for your platform will be marked `novideo` in the filename if no video
-support is available.
-
-### hide() » self
-
-Hides the video. If already playing, the video will continue to play. This just
-turns off display of the video. One possible use of this method is to collapse
-the video area when it is playing an audio file, such as an MP3.
-
-### length() » a number
-
-The full length of the video in milliseconds. Returns nil if the video is not
-yet loaded.
-
-### move(left, top) » self
-
-Moves the video to specific coordinates, the (left, top) being the upper left
-hand corner of the video.
-
-### pause() » self
-
-Pauses the video, if it is playing.
-
-### playing?() » true of false
-
-Returns true if the video is currently playing. Or, false if the video is
-paused or stopped.
-
-### play() » self
-
-Starts playing the video, if it isn't already playing. If already playing, the
-video is restarted from the beginning.
-
-### position() » a decimal
-
-The position of the video as a decimanl number (a Float) between the beginning
-(0.0) and the end (1.0). For instance, a Float value of 0.5 indicates the
-halfway point of the video.
-
-### position = a decimal
-
-Sets the position of the video using a Float value. To move the video to its
-25% position: `@video.position = 0.25`.
-
-### remove() » self
-
-Removes the video from its slot. This will stop the video as well.
-
-### show() » self
-
-Reveals the video, if it has been hidden by the `hide()` method.
-
-### stop() » self
-
-Stops the video, if it is playing.
-
-### time() » a number
-
-The time position of the video in milliseconds. So, if the video is 10 seconds
-into play, this method would return the number 10000.
-
-### time = a number
-
-Set the position of the video to a time in milliseconds.
-
-### toggle() » self
-
-Toggles the visibility of the video. If the video can be seen, then `hide` is
-called. Otherwise, `show` is called.
-
-# AndSoForth
-
-A place for some other information.
-
-## Sample Apps
-
-Have fun!
-
-{SAMPLES}
-
-## FAQ
-
-Hope this helps:
-
- * You can join [Shoes ML](http://librelist.com/browser/shoes/) and feel free ask your questions.
- * [Official Current Source Code](http://github.com/shoes/shoes/) is on GitHub.
- * [Wiki](https://github.com/shoes/shoes/wiki) for Shoes general info.