purple_shoes 0.0.101

data/static/manual-en.txt

@@ -0,0 +1,3969 @@
+# -*- encoding: utf-8 -*-
+= 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. Purple Shoes is one of colorful Shoes. It is written in JRuby 
+with SWT.
+
+You see, the trivial Shoes program can be just one line:
+
+{{{
+ #!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 Windows 7, here's how this might look: !{margin_left: 100}man-shot1.png!
+
+While lots of Shoes apps are graphical games and art programs, you can also
+layout text and edit controls easily. !{margin_left: 80}shoes-manual-apps.png!
+
+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 Purple Shoes' built-in manual. This manual is a Purple Shoes program itself!^
+
+== Introducing Purple Shoes ==
+
+How does Purple Shoes look on OS X and Linux? 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 Purple Shoes, time to
+just check out some screenshots, to give you an idea of what you can do.
+
+==== Mac OS X ====
+
+Purple Shoes is confirmed on Apple Mac OSX10.5 PPC via X11. 
+!{margin_left: 100}../snapshots/sample3-osx.png!
+
+This is the `sample3.rb` on Mac OS X.  
+
+All circles are drawn randomly. You can draw and animate shapes in Purple Shoes.
+
+==== Windows ====
+
+Purple Shoes is confirmed to run on '''Microsoft Windows XP''' and '''Windows 7'''.
+!{margin_left: 0}../snapshots/sample33.png!
+
+Above is pictured the `sample33.rb` running on Windows 7.  Purple Shoes 
+has three extended libraries for chipmunk physics, bloopsaphone and 3D texture 
+mapping. First two are binary libraries, so far work on Windows only.
+
+==== Linux ====
+
+Here's a screenshot of the `sample44.rb` running on '''Ubuntu
+on VirtualBox for Windows'''. !{margin_left: 130}../snapshots/sample44-linux.png!
+
+This example is also draws ovals and lines to build the clock, which is animated to
+show or hide itself several times each second.
+
+Notice the text on the top of the app, showing the current time. Purple Shoes has the
+skills to layout words using any color, bold, italics, underlines, and supports
+loading fonts.
+
+== Installing Purple Shoes ==
+
+Okay, on to installing Purple 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?
+
+Yeah. You need to install Ruby and Gems. But, no need to worry about it.
+We'll talk through all the steps.
+
+==== Step 1: Installing Purple Shoes ====
+
+At first, install Ruby. On '''Windows''', 
+visit the site of [[http://rubyinstaller.org/ RubyInstaller for Windows]] to 
+download the latest '''RubyInstaller 1.9.2 or 1.9.3'''.
+
+Then just do the following one line.
+
+ * gem install green_shoes
+
+That's all. Too easy?
+
+'''Note:''' green_shoes gem is on [[http://rubygems.org/gems/green_shoes RubyGems.org]].
+If you get some errors of rdoc, try to add `--no-ri --no-rdoc` option.
+
+==== 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:
+
+{{{
+ require 'green_shoes'
+ Shoes.app do
+   para "Welcome to Shoes"
+ end
+}}}
+
+Save to your desktop as `welcome.rb`.
+
+==== Step 3: Run It! Go Shoes! ====
+
+To run your program, just open console window and run the following.
+
+ * ruby welcome.rb !man-editor-osx.png!
+
+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. Also thanks to an awesome text 
+lay out engine called Pango. In this way, Shoes is inspired by
+NodeBox and Processing, two very good languages for drawing animated graphics.
+
+== The Rules of Purple Shoes ==
+
+Time to stop guessing how Purple Shoes works.  Some of the tricky things will come
+back to haunt you.  I've boiled down the central rules to Purple Shoes.  These are the
+things you MUST know to really make it all work.
+
+These are general rules found throughout Purple Shoes.  While Purple 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.  Purple 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:'''
+
+{{{
+ Shoes.app do
+   ary = ['potion', 'swords', 'shields']
+   ary.each do |item|
+     puts item
+   end
+ end
+}}}
+
+In Purple 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 Purple Shoes blocks.'''
+
+{{{
+ 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.
+
+{{{
+ 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.  Purple 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:'''
+
+{{{
+ 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 Shoes.app window, `self` is also changed.'''
+
+{{{
+ Shoes.app title: "MAIN" do
+   para self
+   button "Spawn" do
+     Shoes.app 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.
+
+{{{
+ 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.
+
+{{{
+ class Messenger
+   def initialize slot
+     @slot = slot
+   end
+   def add msg
+     para msg rescue puts $!
+   end
+ end
+ 
+ Shoes.app do
+   slot = stack
+   m = Messenger.new slot
+   m.add 'hello'
+ 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 some further editing.
+
+{{{
+ class Messenger
+   def initialize slot
+     @slot = slot
+   end
+   def add msg
+     @slot.app do
+       para msg rescue puts $!
+     end
+   end
+ end
+ 
+ Shoes.app do
+   slot = stack
+   m = Messenger.new slot
+   m.add 'hello'
+ end
+}}}
+
+As you can imagine, the `app` object 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.
+
+{{{
+ Shoes.app do
+   flow do
+     stack :width => 200 do
+       background lavender
+       caption "Column one"
+       para "is 200 pixels wide"
+     end
+     stack :width => -200 do
+       background bisque
+       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.
+
+{{{
+ Shoes.app do
+   stack width: 200, height: 200, scroll: true do
+     background "#DFA"
+     100.times do |i|
+       para "Paragraph No. #{i}"
+     end
+     flush
+   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.
+
+'''Note:''' Fixed height magic (the slot becomes a nested window) is implemented 
+in Purple Shoes as a trial so far. Need to add `flush` method.
+
+{{{
+ Shoes.app do
+   stack :width => 200 do
+     background "#DFA"
+     100.times do |i|
+       para "Paragraph No. #{i}"
+     end
+   end
+ end
+}}}
+
+==== 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!'''
+
+{{{
+ Shoes.app do
+   fill black.push(0.1)
+   100.times do |i|
+     oval i, i, i * 2 if i > 0
+   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.
+
+{{{
+ # Not yet available
+ Shoes.app do
+   fill black(0.1)
+   shape do
+     100.times do |i|
+       oval i, i, i * 2 if i > 0
+     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.
+
+{{{
+ # Not yet available
+ 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.
+
+''Note:'' Purple Shoes doesn't support this magic (grouping shapes together 
+into image or shape blocks) so far.
+
+==== UTF-8 Everywhere ====
+
+Ruby itself isn't Unicode aware.  And UTF-8 is a type of Unicode.  (See
+[[http://en.wikipedia.org/wiki/UTF-8 Wikipedia]] 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 Purple Shoes has to do, 
+Purple 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 Purple Shoes.  Just be sure that your text editor
+uses UTF-8!
+
+To illustrate:
+
+{{{
+ Shoes.app do
+   stack :margin => 10 do
+     @edit = edit_box 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
+Purple 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'''.
+
+{{{
+ 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 Purple 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 and Purple Shoes use 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.
+
+{{{
+ 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.
+
+{{{
+ 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 =
+
+Purple 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 [[https://cloud.github.com/downloads/shoes/shoes/nks.pdf Nobody Knows
+Shoes]], the beginner's leaflet PDF.
+
+==== Finding Your Way ====
+
+This section covers:
+
+ * [[Built-in Built-in methods]] - general methods available anywhere in a Purple Shoes program.
+ * [[App The App window]] - methods found attached to every main Purple Shoes window.
+ * [[Styles The Styles Master List]] - a complete list of every style in Purple Shoes.
+ * [[Classes The Classes list]] - a chart showing what Purple 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 Purple 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`:
+
+{{{
+  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
+ Shoes.app do
+   para "Plaster of Paris".reverse
+   #=> "siraP fo retsalP"
+   para [:dogs, :cows, :snakes].reverse
+   #=> [:snakes, :cows, :dogs]
+ end
+}}}
+
+Most Purple Shoes methods for drawing and making buttons and so on are attached to
+slots.  See the section on [[Slots]] for more.
+
+==== Built-in Constants ====
+
+Purple Shoes also has a handful of built-in constants which may prove useful if you
+are trying to sniff out what release of Purple Shoes is running.
+
+'''DIR''' is a full path of `purple_shoes/lib`. 
+
+'''COLORS''' is a complete list of colors available to the app. 
+
+'''FONTS''' is a complete list of fonts available to the app. 
+
+'''VERSION''' is a Purple Shoes version. 
+
+{{{
+ Shoes.app do
+   para VERSION
+   para fg(DIR, red)
+   image File.join(DIR, '../static/gshoes-icon.png')
+   para fg(FONTS.join(', '), green)
+   para COLORS.map{|k, v| [k, v]}
+ end
+}}}
+
+=== alert(message: a string, :block => true or false, title: a string) » nil ===
+
+Pops up a window containing a short message.
+
+{{{
+ #!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
+standard Ruby method `puts` or `p` methods.
+
+If you want to make alert() thread safe, i.e. unblock main thread, use `:block => false` option.
+If you want to change window title, use `:title => a string` option.
+
+=== 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
+ if name = ask("Please, enter your name:")
+   Shoes.app{para "Welcome, #{name}!"}
+ end
+}}}
+
+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) » a RGB array ===
+
+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
+ 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
+ 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
+ save_as = ask_save_file
+ Shoes.app do
+   para save_as
+ end
+}}}
+
+=== 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
+ 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. 
+
+{{{
+ #!ruby
+ save_to = ask_save_folder
+ Shoes.app do
+   para save_to
+ end
+}}}
+
+
+=== 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
+ if confirm("Draw a circle?")
+  Shoes.app{ oval top: 0, left: 0, radius: 50 }
+ end
+}}}
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support font method so far.
+
+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?`.
+
+{{{
+  if Shoes::FONTS.include? "Coolvetica"
+    alert "Coolvetica is available on this system."
+  else
+    alert "You do not have the Coolvetica 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) » a range of RGB array ===
+
+Builds a linear gradient from two colors. For each color, you may pass in 
+a color/rgb method or a string describing the color. The `gradient(green, red)` is 
+the same as `green..red` for example. Also possible to use different kind of args 
+like this: `gradient(green, '#FA3')`
+
+{{{
+ Shoes.app do
+   oval 100, 100, 100,
+     fill: gradient(green, '#FA3'), angle: 45
+ end
+}}}
+
+=== gray(the numbers: darkness, alpha) » a RGB array ===
+
+Create a grayscale color from a level of darkness and, optionally, an alpha
+level.
+
+{{{
+ Shoes.app do
+  nostroke
+  11.times do |i|
+    y = x = 50 + 10 * i
+    r = 200 - 10 * i
+    oval x, y, r, fill: gray(1-i*0.1)
+  end
+ end
+}}}
+
+=== rgb(red, green, blue, alpha) » an array of decimal numbers ===
+
+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.
+
+{{{
+ Shoes.app do
+   blueviolet = rgb(138, 43, 226, 0.5)
+   darkgreen = rgb(0, 100, 0, 0.5)
+   oval 100, 100, 100,
+     fill: [blueviolet, darkgreen].sample(1)
+ end
+}}}
+
+Or, use a decimal number from 0.0 to 1.0.
+
+{{{
+ Shoes.app do
+   blueviolet = rgb(0.54, 0.17, 0.89)
+   darkgreen = rgb(0, 0.4, 0)
+   oval 100, 100, 100,
+     fill: [blueviolet, darkgreen].sample(1)
+ end
+}}}
+
+== 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 Purple Shoes
+elements.
+
+The App is the window itself. Which may be closed or cleared and filled with
+new elements. !{:margin_left => 100}../snapshots/sample46.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 Purple Shoes app window.  This is the starting place for making a Purple 
+Shoes program.  Inside the block, you fill the window with various Purple 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.
+
+{{{
+ #!ruby
+ Shoes.app title: "White Circle",
+   width: 200, height: 200 do
+   background black
+   fill white
+   oval top: 20, left: 20, radius: 160
+ end
+}}}
+
+In the case above, a small window is built.  200 pixels by 200 pixels.
+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 Purple 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 Purple Shoes.  It's completely encouraged.
+
+{{{
+ Shoes.app do
+   button('Open a new app'){Shoes.app{}}
+   button('Print Shoes.APPS'){p Shoes.APPS}
+ end
+}}}
+
+=== 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`.
+
+{{{
+ Shoes.app do
+  para 'hello'
+  button 'spawn' do
+   Shoes.app do
+    para 'hello'
+    button('close: close this window only'){close}
+    button('exit: quit Purple Shoes'){exit}
+   end
+  end
+  button('close: close this window only'){close}
+  button('exit: quit Purple Shoes'){exit}
+ end
+}}}
+
+=== 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.
+
+{{{
+ Shoes.app do
+   stack do
+     title "Searching Google", size: 16
+     @status = para "One moment..."
+ 
+     download "http://is.gd/bXTVY7" do |goog|
+       @status.text = "Headers: #{goog.meta}"
+     end
+   end
+ end
+}}}
+
+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.
+
+{{{
+ Shoes.app do
+   stack do
+     title "Downloading Google image", size: 16
+     @status = para "One moment..."
+ 
+     download "http://is.gd/GVAGF7",
+       :save => "nasa50th.gif" do
+	@status.text = "Okay, is downloaded."
+	image "nasa50th.gif", top: 100
+     end
+   end
+ end
+}}}
+
+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
+ # Not yet available
+ Shoes.app do
+   stack do
+     title "GET Google", size: 16
+     @status = para "One moment..."
+ 
+     download "http://is.gd/bXTVY7", 
+         :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.
+
+'''Note:''' Purple Shoes doesn't support the `:method`, `:headers` and `:body` styles.
+
+{{{
+ include Hpricot
+ Shoes.app do
+   status = para "One moment..."
+   download 'http://is.gd/BatiRt' do |dl|
+     samples = []
+     Hpricot(dl).inner_text.each_line do |line|
+       samples.push($1) if line =~ /(sample.*\.rb)/
+     end
+     status.text = samples.join(', ')
+     flush
+   end
+ end
+}}}
+
+As you can see from the above example, Purple Shoes includes the Hpricot
+library for parsing HTML.
+
+'''Note:''' Windows platform only so far.
+
+=== 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
+ 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.)
+
+'''Note:''' Purple Shoes doesn't support started? method so far.
+
+=== 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 Purple Shoes will be expecting
+a Purple 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 Purple 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 links without an underline.)
+
+Styles are easy to spot.  They usually show up when the element is created.
+
+{{{
+ Shoes.app title: "A Styling Sample" do
+   para 'Purple Shoes', align: 'center', size: 50
+ end
+}}}
+
+Here we've got a `:title` style on the app.  And on the paragraph inside the
+app, a center `:align` style and 50 font `:size` style.
+
+The style hash can also be changed by using the [[Common.style]] method,
+available on every element and slot.
+
+'''Note:''' Purple Shoes can change style hash on Shape element only so far.
+
+{{{
+ Shoes.app title: "A Styling Sample" do
+   choose = 
+     lambda{[red, blue, green, yellow].sample}
+   s = star 100, 50, 30, 200, 180, strokewidth: 5
+   button 'change colors' do
+     s.style stroke: choose.call, fill: choose.call
+   end
+ end
+}}}
+
+Most styles can also be set by calling them as methods.  (I'd use the manual
+search to find the method.)
+
+'''Note:''' Purple Shoes doesn't support them as methods.
+
+{{{
+ # Not yet available
+ Shoes.app title: "A Styling Sample" do
+   choose = 
+     lambda{[red, blue, green, yellow].sample}
+   s = star 100, 50, 30, 200, 180, strokewidth: 5
+   button 'change colors' do
+     s.stroke = choose.call; s.fill = choose.call
+   end
+ 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 Purple Shoes and suggests
+where that style is used.
+
+=== :align » a string ===
+
+For: ''banner, caption, inscription, para, 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, line, oval, rect, shape, star''.
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `:attach` style.
+
+=== :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.
+
+'''Note:''' Purple Shoes doesn't support ''video''.
+
+=== :back » true or false ===
+
+For: ''shapes, image, textblocks''.
+
+Comes to the back of the other elements.
+
+{{{
+ Shoes.app do
+   rect 100, 100, 100, 100, fill: green
+   rect 120, 120, 100, 100, fill: yellow
+   para 'hello', left: 150, top: 150, front: true
+   oval 150, 150, 100, 100, fill: red
+   oval 180, 180, 100, 100, fill: gray, back: true
+ end
+}}}
+
+=== :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.
+
+'''Note:''' Purple Shoes doesn't support `:bottom` style.
+
+=== :cap » :curve or :rect or :project ===
+
+For: ''arc, line, shape''.
+
+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`.
+
+'''Note:''' Purple Shoes doesn't support `:center` style.
+
+=== :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, button, check, flow, image, 
+line, link, oval, radio, rect, shape, stack, star''.
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `:displace_left` style.
+
+=== :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.
+
+'''Note:''' Purple Shoes doesn't support `:displace_top` style.
+
+=== :emphasis » a string ===
+
+For: ''banner, caption, inscription, para, span, 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, inscription, para, span, 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 rgb array or a range of either ===
+
+For: ''background, banner, border, caption, inscription, para, line, oval, 
+rect, shape, star, subtitle, tagline, title''.
+
+The color of the background pen.  For shapes, this is the fill color, the paint
+inside the shape. For textblock, this color is painted in the background
+(as if marked with a highlighter pen.) 
+
+=== :font » a string ===
+
+For: ''banner, caption, inscription, para, 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.
+
+=== :front » true or false ===
+
+For: ''shapes, image, textblocks''.
+
+Comes to the front of the other elements.
+
+=== :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.
+
+{{{
+ Shoes.app do
+   slot = stack hidden: true do
+     title 'hello'
+     flow do
+       image File.join DIR, '../samples/loogink.png'
+     end
+     para link('Go go!'){alert 'hi'}
+   end
+   timer(2){slot.show}
+   timer(5){slot.hide}
+ end
+}}}
+
+'''Note:''' Purple Shoes supports `:hidden` style for only slots, shapes, textblocks 
+and images so far.
+
+=== :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, inscription, para, 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.
+
+'''Note:''' Purple Shoes doesn't support `:kerning` style.
+
+=== :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.
+
+=== :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: ''oval''.
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `:right` style.
+
+=== :rise » a number ===
+
+For: ''banner, caption, inscription, para, span, 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.
+
+'''Note:''' Purple Shoes has restrictions. `:scroll` style is just a trial so far.
+
+ * common Slot instance methods, i.e. clear, hide, etc., don't work well
+ * doesn't manage any mouse events 
+ * need to write `flush` explicitly
+
+{{{
+ Shoes.app do
+   s = stack left: 100, top: 50, width: 300, 
+     height: 100, scroll: true do
+     background gold
+     image File.join(DIR, '../samples/loogink.png')
+     10.times{para 'hello'}
+     flush
+   end
+ end
+}}}
+
+=== :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, inscription, para, span, subtitle, tagline, title''.
+
+Sets the pixel size for the font used inside this text block.
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `:stretch` style.
+
+=== :strikecolor » a RGB array ===
+
+For: ''banner, caption, inscription, para, span, subtitle, tagline, title''.
+
+The color used to paint any lines stricken through this text.
+
+=== :strikethrough » a string ===
+
+For: ''banner, caption, inscription, para, span, subtitle, tagline, title''.
+
+Is this text stricken through?  Two options here:
+
+ * "none" - no strikethrough
+ * "single" - a single-line strikethrough.
+
+=== :stroke » a hex code, a rgb array or a range of either ===
+
+For: ''background, banner, border, caption, inscription, para, line, oval, 
+rect, shape, star, subtitle, tagline, title''.
+
+The color of the foreground pen.  In the case of shapes, this is the color the
+lines are drawn with. For textblock, the letters are printed in this color.
+
+=== :strokewidth » a number ===
+
+For: ''background, border, line, oval, rect, shape, star''.
+
+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: ''edit_box, edit_line''.
+
+Sets the message displayed on the contents of edit_box or edit_line.
+
+=== :top » a number ===
+
+For: ''all slots and elements''.
+
+Sets the top coordinate for an object, relative to the top slot (window).  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 top slot (window).  If no
+`:top` style is given, the object is automatically placed in the natural flow
+of the slot it contains.
+
+=== :undercolor » a RGB array ===
+
+For: ''banner, caption, inscription, para, span, subtitle, tagline, title''.
+
+The color used to underline text.
+
+=== :underline » a string ===
+
+For: ''banner, caption, inscription, para, span, 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. 
+
+'''Note:''' Purple Shoes doesn't support `:variant` style.
+
+=== :weight » a string ===
+
+For: ''banner, caption, inscription, para, span, 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, inscription, para, span, 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 ==
+
+There is a complete list of all the classes introduced by Purple Shoes.  
+
+Look at [[http://rdoc.info/github/ashbb/green_shoes/master/frames/file/README.md Green Shoes RDoc]].
+
+== Colors List ==
+
+The following list of colors can be used throughout Purple 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 Purple 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 Purple 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 Purple 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
+ 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 RGB array.  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!
+
+Purple Shoes does a few things differently from NodeBox and Processing.  For example,
+Purple Shoes has different color methods, including having its own RGB array,
+though these are very similar to Processing's color methods.  And Purple 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::Oval ===
+
+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 `2*Math::PI`.)
+
+{{{
+ Shoes.app do
+   fill yellow..green
+   stroke red..blue
+   strokewidth 10
+   cap :curve
+ 
+   a = animate 12 do |i|
+     @e.remove if @e
+     r = i * (Math::PI * 0.01)
+     @e = arc 100, 50, 180, 360, 0, r
+     a.stop if r >= 2*Math::PI
+   end
+ end
+}}}
+
+=== arrow(left, top, width) » Shoes::Shape ===
+
+Draws an arrow at coordinates (left, top) with a pixel `width`.
+
+{{{
+ Shoes.app do
+   para 'An arrow shape:', left: 20, top: 10
+   arrow 30, 40, 70
+ end
+}}}
+
+=== 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.
+
+{{{
+ Shoes.app do
+   nofill
+   strokewidth 20
+   stroke green
+   cap :curve
+   line 100, 100, 300, 100
+   line 100, 250, 300, 300
+   cap :rect
+   line 100, 150, 300, 150
+   stroke blue
+   cap :project
+   line 100, 200, 300, 200
+   line 200, 100, 200, 300
+   strokewidth 1
+   stroke red
+   rect 100, 100, 200, 200
+ end
+}}}
+
+=== 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
+ Shoes.app do
+   fill File.join(DIR, "../static/gshoes-icon.png")
+   star 200, 200, 5, 100, 50
+ 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::Line ===
+
+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::Oval ===
+
+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
+ 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::Oval ===
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `center` style.
+
+=== rect(top, left, width, height) » Shoes::Rect ===
+
+Draws a rectangle starting from coordinates (top, left) with dimensions of
+width x height. 
+
+As with all other shapes, the rectangle is drawn using the stroke and fill colors.
+
+{{{
+ #!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::Rect ===
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `center` style.
+
+=== 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
+ 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.
+
+{{{
+ Shoes.app do
+   fill yellow
+   shape do
+     move_to 50, 30
+     curve_to 100, 100, 10, 20, 100, 50
+     line_to 20, 100
+     line_to 30, 30
+   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.
+
+'''Note:''' The above `line_to`, `move_to` and `curve_to` are Cairo::Context methods. 
+Purple Shoes uses them directly inside the block. So, Purple Shoes doesn't support `arc_to`.
+Also Purple Shoes shape can not contain other shapes.
+
+=== star(left, top, points = 10, outer = 100.0, inner = 50.0) » Shoes::Star ===
+
+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 a star with a red line around it:
+
+{{{
+ #!ruby
+ Shoes.app do
+   stroke red
+   nofill
+   star 100, 100
+ 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`.
+
+'''Note:''' Purple Shoes doesn't support `transform` method.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support `translate` method.
+
+== Element Creation ==
+
+Purple 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::Anim ===
+
+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
+ 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.
+Purple Shoes layers background elements.
+
+{{{
+ #!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.  Purple 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.  Purple 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.  Purple Shoes styles this text to 14 pixels high.
+
+=== check() » Shoes::Check ===
+
+Adds a check box.
+
+=== code(text) » String ===
+
+Create a Code text fragment.  This text defaults to a monospaced font.
+
+=== del(text) » String ===
+
+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.
+
+'''Note:''' Purple Shoes doesn't support `dialog` method.
+
+=== edit_box(text, :accepts_tab => true or false) » 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.
+
+If `accepts_tab` is true a tab character is inserted. 
+If `accepts_tab` is false the keyboard focus is moved to the next element 
+in the focus chain. This accepts_tab defaults to false.
+
+{{{
+ #!ruby
+ Shoes.app do
+   edit_box
+   edit_box text: "HORRAY EDIT ME"
+   edit_box text: "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) » String ===
+
+Creates an Em text fragment (short for "emphasized") which, by default, is
+styled with italics.
+
+=== every(seconds) { |count| ... } » Shoes::Anim ===
+
+A timer similar to the `animate` 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 Purple 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.
+
+'''Note:''' Purple Shoes doesn't support the above personal Shoes directory.
+
+=== 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) » String ===
+
+Creates an Ins text fragment (short for "inserted") which Purple Shoes styles with a
+single underline.
+
+=== inscription(text) » Shoes::Inscription ===
+
+Creates an Inscription text block.  Purple Shoes styles this text at 10 pixels high.
+
+=== link(text, :click => proc or string) » Shoes::Link ===
+
+Creates a Link text block, which Purple 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.
+
+=== link(text){ ... } » Shoes::Link ===
+
+Creates a Link text block. You can also write with this style. When user clicks the link text, 
+the block will be launched.
+
+=== 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
+ Shoes.app do
+  stack  margin: 10 do
+   para "Pick a card:"
+   list_box items: ["Jac", "Ace", "Jok"] do |item|
+    @p.text = "#{item} was picked!"
+   end
+   @p = para
+  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 Purple 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.
+
+{{{
+ Shoes.app do
+   tagline "\n", 'hello ' * 5, 
+     span(em('Purple Shoes'), size: 8, rise: 15)
+ end
+}}}
+
+=== 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) » String ===
+
+Creates a Strong text fragment, styled in bold by default.
+
+=== sub(text) » String ===
+
+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) » String ===
+
+Creates a Subtitle text block.  Purple Shoes styles this text to 26 pixels high.
+
+=== sup(text) » String ===
+
+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.  Purple Shoes styles this text to 18 pixels high.
+
+=== timer(seconds) { ... } » Fixnum ===
+
+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
+ Shoes.app do
+   timer 5 do
+     alert "Your five seconds are up."
+   end
+ end
+}}}
+
+=== title(text) » Shoes::Title ===
+
+Creates a Title text block.  Purple Shoes styles these elements to 34 pixels high.
+
+=== video(path or url) » Shoes::Video ===
+
+Embeds a movie or plays an audio.
+
+=== 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
+ Shoes.app title: "The Owner" do
+  button "Pop up?" do
+   window do
+    para "Okay, popped up from [#{owner.inspect}]."
+   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`, `release`, `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
+ Shoes.app do
+   s = stack width: 200, height: 200 do
+     background red
+   end
+   s.hover do
+     s.clear { background blue }
+   end
+   s.leave do
+     s.clear { background red }
+   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.
+
+'''Note:''' Purple Shoes doesn't support `finish` method.
+
+=== 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. 
+
+So, for example, if `Shift-a` is pressed, the block will get the string `"Shift_L"` and `"A"`.
+
+And if the `F1` key is pressed, the `"F1"` string is received. 
+
+The left side modifier keys are `"Control_L"`, `"Shift_L"` and `"Alt_L"`.  They appear in that order.
+If `Shift-Control-Alt-PgUp` is pressed, the strings will be
+`"Shift_L"`, `"Control_L"`, `"Alt_L"` and `"Page_Up"`.
+
+One thing about the shift key.  On
+US keyboards, `Shift-7` is an ampersand.  So you'll get the string `"Shift_L"` and `"ampersand"` rather
+than `"Shift_L"` and `"7"`.  And, if you press `Shift-Alt-7` on such a keyboard, you'll
+get the strings: `"Shift_L"`, `"Alt_L"` and `"ampersand"`.  
+
+{{{
+ #!ruby
+ Shoes.app do
+   info = para "NO KEY is PRESSED."
+   keypress do |k|
+     info.replace "#{k.inspect} was PRESSED."
+   end
+ end
+}}}
+
+
+=== 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
+ 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.
+
+'''Note:''' Purple Shoes doesn't support `start` method.
+
+== 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
+ 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
+ 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
+ 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
+ Shoes.app do
+   stack width: 150 do
+     background yellow
+     para "Now that's precision." 
+   end
+ 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.
+
+'''Note:''' Purple Shoes doesn't support `displace` method.
+
+=== gutter() » a number ===
+
+The size of the scrollbar area.  When Purple 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:
+
+{{{
+ 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.
+
+'''Note:''' Purple Shoes doesn't support `move` method.
+
+=== remove() » self ===
+
+Removes the slot. It will no longer be displayed and will not be listed in its
+parent's contents. It's gone.
+
+'''Note:''' Purple Shoes doesn't support `remove` method. Use `clear` method.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support `scroll` method.
+
+=== scroll_height() » a number ===
+
+The vertical size of the full slot, including any of it which is hidden by scrolling.
+
+'''Note:''' Purple Shoes doesn't support `scroll_height` method.
+
+=== 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`.
+
+'''Note:''' Purple Shoes doesn't support `scroll_max` method.
+
+=== 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`.
+
+'''Note:''' Purple Shoes doesn't support `scroll_top` method.
+
+=== scroll_top = a number ===
+
+Scrolls the slot to a certain coordinate.  This must be between zero and
+`scroll_max`.
+
+'''Note:''' Purple Shoes doesn't support `scroll_top=` method.
+
+=== 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
+ Shoes.app do
+   s = stack width: 1.0
+   para s.style[:width]
+   button('Then..'){s.append{para s.style[:width]}}
+ end
+}}}
+
+In this example, the paragraph under the stack will display "1.0". 
+After click the button, will show you "600" pixels.
+
+=== 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
+ 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 shapes, are not included in any slots.)
+
+=== 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.
+
+{{{
+ Shoes.app do
+   s = stack do
+     para 'Purple'
+     @p = para 'Shoes'
+   end
+   para s
+   para s.contents
+   para @p.parent
+ end
+}}}
+
+= Elements =
+
+Ah, here's the stuff of Purple Shoes. An element can be as simple as an oval shape. Or
+as complex as a para text string. You've encountered all of these elements before
+in the Slots section of the manual.
+
+Purple 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 SWT apis 
+directly.  So, a Progress bar will never convert to the PNG image data.
+
+Greem Shoes also has seven basic other types of elements: Background, Border, Image,
+Shape, TextBlock, Animate 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 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 Purple 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
+ 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, 
+       markup: fg(@text.text, 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
+ # Not yet available
+ 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!
+
+'''Note:''' Purple Shoes doesn't support `displace` method.
+
+=== 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.  The element is no longer
+inside the slot.  So, it will not be stacked or flowed in with the
+other stuff in the slot.  The element will float freely, now absolutely
+positioned instead.
+
+{{{
+ #!ruby
+ Shoes.app do
+   # Set up three buttons
+   b = button "One"
+   @two = button "Two"
+   button "Three"
+ 
+   # Bounce the second button
+   animate do |i|
+     @two.move(33, 33 + (Math.sin(i) * 6).to_i)
+   end
+ end
+}}}
+
+The second button is moved to a specific place, allowing the third button to
+slide over into its place.  But it will not happen until you resize the window.
+If you want to slide the third button without resizing the window, add `flush` 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
+ Shoes.app do
+   # A button which take up the whole page
+   @b = button "All of it", 
+     width: width, height: height
+ 
+   # 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 1.0 and that element is inside
+a stack which is 120 pixels wide, you'll get back `120`.  And, if you call
+`style[:width]`, you'll get `120`.
+
+{{{
+ #!ruby
+ Shoes.app do
+   stack width: 120 do
+     @b = button "Click me", width: 1.0 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)`.
+
+== 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.
+!{:margin_left => 100}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
+ 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
+ Shoes.app do
+   background black, height: 50
+ end
+}}}
+
+Or, to paint a fifty pixel column on the left-side of the window:
+
+{{{
+ #!ruby
+ Shoes.app do
+   background black, width: 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.
+
+'''Note:''' Purple Shoes doesn't support `to_pattern` method.
+
+== 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. !{:margin_left => 100}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
+ Shoes.app do
+   stack width: 50 do
+     border black, strokewidth: 5
+     para fg "=^.^=", 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
+ Shoes.app do
+   stack width: 60 do
+     border black, strokewidth: 5
+     stack width: 50 do
+       para fg "=^.^=", 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.  Purple 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.
+
+'''Note:''' Purple Shoes doesn't support `to_pattern` method.
+
+== 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. !{:margin_left => 100}man-ele-button.png!
+
+{{{
+ #!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
+ 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
+ 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 Purple 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. !{:margin_left => 100}man-ele-check.png!
+
+Here's a sample checklist.
+
+{{{
+ #!ruby
+ Shoes.app do
+   stack do
+     flow do
+       check; para "Frances Johnson", width: 200
+     end
+     flow do
+       check; para "Ignatius J. Reilly", width: 200
+     end
+     flow do
+       check
+       para "Winston Niles Rumfoord", width: 200
+     end
+   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
+ Shoes.app do
+   @list = ['Frances Johnson', 'Ignatius J. Reilly',
+     'Winston Niles Rumfoord']
+ 
+   stack do
+     @list.map! do |name|
+       flow { @c = check; para name, width: 200 }
+       [@c, name]
+     end
+ 
+     button "What's been checked?" do
+       selected = 
+         @list.map{|c, n| n 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! !{:margin_left => 100}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
+ 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
+ Shoes.app do
+   edit_box do |e|
+     @counter.text = 
+       strong("#{e.text.size}") + " characters"
+   end
+   @counter = para strong("0"), " 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.
+!{:margin_left => 100}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
+ 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 Purple 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. Purple Shoes can resize images or
+flow them in with text. Images can be loaded from a file or directly off the
+web. !{:margin_left => 100}man-ele-image.png!
+
+To create an image, use the `image` method in a slot:
+
+{{{
+ #!ruby
+ Shoes.app do
+   para "Nice, nice, very nice.  Busy, busy, busy."
+   image File.join DIR,
+     "../static/shoes-manual-apps.png"
+  end
+}}}
+
+When you load any image into Purple 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
+ Shoes.app do
+   image "http://is.gd/c0mBtb"
+ 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.)
+
+'''Note:''' Purple Shoes doesn't support the hard drive cache management feature like Red Shoes.
+
+Purple 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.
+
+=== rotate(degrees: a number) » self ===
+
+Rotates the Image element by a certain number of `degrees`.
+
+{{{
+ Shoes.app do
+   img = image File.join(DIR, '../samples/cy.png')
+   img.move 200, 200
+   animate do |i|
+     img.rotate i*10
+   end
+ end
+}}}
+
+== 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.
+!{:margin_left => 100}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
+ 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
+ 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%.) Purple Shoes thinks of
+progress in terms of the decimal numbers 0.0 to 1.0. !{:margin_left =>
+100}man-ele-progress.png!
+
+A simple progress bar is 150 pixels wide, but you can use the `:width` style
+(as with all Purple Shoes elements) to lengthen it.
+
+'''Note:''' The minimum size is 150 pixels wide in Purple Shoes.
+
+{{{
+ Shoes.app do
+   title "Progress example"
+   @p = progress left: 10, top: 100, width: width-20
+ 
+   animate do |i|
+     @p.fraction = (i % 100) / 100.0
+   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.) !{:margin_left =>
+100}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
+ Shoes.app do
+   para "Among these films, which do you prefer?\n"
+   radio
+   para strong("The Taste of Tea"), 
+     " by Katsuhito Ishii\n", width: 570
+   radio
+   para strong("Kin-Dza-Dza"), 
+     " by Georgi Danelia\n", width: 570
+   radio
+   para strong("Children of Heaven"), 
+     " by Majid Majidi\n", width: 570
+ 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
+ Shoes.app do
+   stack do
+     para "Among these films, which do you prefer?"
+     flow do
+       radio
+       para "The Taste of Tea by Katsuhito Ishii", 
+         width: 300
+     end
+     flow do
+       radio
+       para "Kin-Dza-Dza by Georgi Danelia",
+         width: 300
+     end
+     flow do
+       radio
+       para "Children of Heaven by Majid Majidi",
+         width: 300
+     end
+   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
+ 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",
+         width: 300
+     end
+     flow do
+       radio :films
+       para "Kin-Dza-Dza by Georgi Danelia",
+         width: 300
+     end
+     flow do
+       radio :films
+       para "Children of Heaven by Majid Majidi",
+         width: 300
+     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.
+
+== Shape ==
+
+A shape is a path outline usually created by drawing methods like `oval` and
+`rect`. !{:margin_left => 100}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 Text types.) !{:margin_left => 100}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.
+
+'''Note:''' Purple Shoes doesn't support `contents` method.
+
+=== cursor() » an index ===
+
+Return a text cursor position. That is an index of the text which is a string
+of all of the characters in this text box.
+
+=== cursor = an index or nil ===
+
+Shows or hides the text cursor.
+Using `cursor = 3`, for instance, shows the text cursor at index 3 from the front.
+Using `cursor = -1` shows the text cursor at the end of the text.
+Using `cursor = nil` hides the text cursor.
+
+{{{
+ Shoes.app do
+  msg = para 'hello ' * 20
+  msg.cursor = -1
+  keypress do |k|
+    n = case k
+      when 'Left'; -1
+      when 'Right'; 1
+      else
+        next
+    end
+    n += msg.cursor
+    len = msg.text.length
+    n = len unless n > -1
+    msg.cursor = n % (len+1)
+    flush
+  end
+ end
+}}}
+
+=== highlight() » an array ===
+
+Return an array which includes a text marker start position and highlighted length. 
+
+=== hit(left, top) » an index or nil ===
+
+Return an index of the text at which the mouse cursor points on. 
+The `left` and `top` are the mouse coordinates. 
+
+{{{
+ Shoes.app do
+   para 'index: ', width: 50
+   index = para '', width: 20
+   msg = title 'hello ' * 5
+   click do |b, x, y|
+     index.text = msg.hit x, y
+   end
+ end
+}}}
+
+=== marker() » an index ===
+
+Return a text marker start position. 
+
+=== marker = an index ===
+
+Highlight a part of text from marker start position to cursor position.
+
+{{{
+ Shoes.app do
+   background gainsboro
+   extend HH::Markup
+   code = 'alert "Hello Purple Shoes! " * 5'
+   msg = para highlight code, nil
+   button 'marker' do
+     msg.cursor = 17
+     msg.marker = 14
+     msg.text = highlight msg.markup, nil
+     para msg.highlight
+     flush
+   end
+ end
+}}}
+
+=== markup() » a text ===
+
+Return some marked-up text for Pango. 
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support `to_s` method.
+
+== Timers ==
+
+Purple Shoes contains three timers: the animate, every and
+timer. Both animate and every loop over and over after they
+start.  The timer happens once. A one-shot timer.
+
+The animate and every are basically the same thing. The difference is that
+the animate usually happen many, many times per second. And the every happens only
+once every few seconds or rarely.
+
+The animate and every automatically start themselves.
+
+=== 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!
+
+'''Note:''' Purple Shoes doesn't support `start` method.
+
+=== stop() » self ===
+
+Stops the animate or every loop.
+
+=== pause() » self ===
+
+Pauses the animate or every loop. If the animate or every loop is stopped, it is started. Otherwise, if it is
+already running, it is stopped.
+
+== Video ==
+
+Purple Shoes supports embedding of MP4, AVI, WMV, QuickTime and various other popular video formats. 
+This is all thanks to Ruby/GStreamer. Use the `video` method to setup a Shoes::Video object. !{:margin_left => 70}man-ele-video.png!
+
+{{{
+ Shoes.app width: 400, height: 300 do
+   background gold..cyan, angle: 90
+   space = ' ' * 3
+   v = video 'http://is.gd/xZ6Jih'
+   links = para space, 
+     link('play'){v.play; links.move(0, 300)}, 
+     space, link('pause'){v.pause}, 
+     space, link('-1sec'){v.time -= 1000},
+     space, link('+1sec'){v.time += 1000}, 
+     top: 250
+   msg = para left: 250, top: 300
+   every do
+     msg.text = fg("#{(v.position*100).to_i}% " + 
+       "(#{v.time/1000}/#{v.length.to_i/1000}sec)", 
+       darkcyan)
+   end
+ end
+}}}
+
+In addition to video formats, some audio formats are also supported, such as MP3, WAV and Ogg Vorbis.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support hide method so far.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support move method so far.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support remove method so far.
+
+=== show() » self ===
+
+Reveals the video, if it has been hidden by the `hide()` method.
+
+'''Note:''' Purple Shoes doesn't support show method so far.
+
+=== 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.
+
+'''Note:''' Purple Shoes doesn't support tobble method so far.
+
+= AndSoForth =
+
+A place for some other information. 
+
+== Sample Apps ==
+
+Have fun!
+
+{SAMPLES}
+
+== FAQ ==
+
+Hope this helps:
+
+ * You can join [[http://librelist.com/browser/shoes/ Shoes ML]] and feel free ask your questions. 
+ * [[https://github.com/ashbb/purple_shoes/ Current Source Code]] is on GitHub.
+ * Purple Shoes Gem is on [[http://rubygems.org/gems/purple_shoes RubyGems.org]].
+
+== vs.RedShoes ==
+
+Purple Shoes is following Red Shoes, but not fully compatible.
+
+==== TextBlock ====
+
+The following two snippets are same in Red Shoes.
+
+{{{
+ Shoes.app do
+   para 'hello ' * 20
+ end
+}}}
+
+{{{
+ Shoes.app do
+   20.times{para 'hello '}
+ end
+}}}
+
+But in Purple Shoes, need to add `:width` size explicitly.
+
+{{{
+ Shoes.app do
+   20.times{para 'hello ', width: 40}
+ end
+}}}
+
+If you don't specify the `:width` size, Purple Shoes makes a TextBlock object with 
+the `parent.width`.
+
+For more information, go to [[http://ashbb.github.com/green_shoes/Red_Shoes_and_Green_Shoes.html Red Shoes and Green Shoes]]. 
+
+== gshoes ==
+
+'''gshoes''' is a gem executable command which has some options. Just open console window and try to run `gshoes (options or app.rb or app.gsy)`. 
+
+=== -m, -men ===
+
+Open the built-in English manual.
+
+=== -mjp ===
+
+Open the built-in Japanese manual.
+
+=== -p ===
+
+Package a Purple Shoes app as a .gsy file. GSY, which stands for Purple Shoes YAML.
+
+=== -v ===
+
+Display the version info.
+
+=== -h ===
+
+Show the help message.