The Shoes Manual

Built-in Methods

These methods can be used anywhere throughout Shoes programs.

All of these commands are unusual because you don't attach them with a dot. Every other method in this manual must be attached to an object with a dot. But these are built-in methods (also called: Kernel methods.) Which means no dot!

A common one is alert:

 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:

 "Plaster of Paris".reverse
  #=> "siraP fo retsalP"
 [:dogs, :cows, :snakes].reverse
  #=> [:snakes, :cows, :dogs]

Most Shoes methods for drawing and making buttons and so on are attached to slots. See the section on Slots for more.

Built-in Constants

Shoes also has a handful of built-in constants which may prove useful if you are trying to sniff out what release of Shoes is running.

Shoes::RELEASE_NAME contains a string with the name of the Shoes release. All Shoes releases are named, starting with Curious.

Shoes::RELEASE_ID contains a number representing the Shoes release. So, for example, Curious is number 1, as it was the first official release.

Shoes::REVISION is the Subversion revision number for this build.

Shoes::FONTS is a complete list of fonts available to the app. This list includes any fonts loaded by the font method.

Pops up a window containing a short message.

 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 debug or info methods.

Pops up a window and asks a question. For example, you may want to ask someone their name.

 name = ask("Please, enter your name:")

When the above script is run, the person at the computer will see a window with a blank box for entering their name. The name will then be saved in the name variable.

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.

 backcolor = ask_color("Pick a background") do
  background backcolor
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.

 filename = ask_open_file do
ask_save_file() » a string

Pops up a "Save file..." window, similiar to ask_open_file, described previously.

 save_as = ask_save_file
ask_open_folder() » a string

Pops up an "Open folder..." window. It's the standard window which shows all of your folders and lets you select a folder to open. Hands you back the name of the folder.

 folder = ask_open_folder do
   para Dir.entries(folder)
ask_save_folder() » a string

Pops up a "Save folder..." window, similiar to ask_open_folder, described previously. On OS X, this method currently behaves like an alias of ask_open_folder.

 save_to = ask_save_folder

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.

 if confirm("Draw a circle?"){ oval top: 0, left: 0, radius: 50 }

Sends a debug message to the Shoes console. You can bring up the Shoes console by pressing Alt-/ on any Shoes window (or ⌘-/ on OS X.)

 debug("Running Shoes on " + RUBY_PLATFORM)

Also check out the error, warn and info methods.

Sends an error message to the Shoes console. This method should only be used to log errors. Try the debug method for logging messages to yourself.

Oh, and, rather than a string, you may also hand exceptions directly to this method and they'll be formatted appropriately.

Stops your program. Call this anytime you want to suddenly call it quits.

PLEASE NOTE: If you need to use Ruby's own exit method (like in a forked Ruby process,) call Kernel.exit.

font(message: a string) » an array of font family names

Loads a TrueType (or other type of font) from a file. While TrueType is supported by all platforms, your platform may support other types of fonts. Shoes uses each operating system's built-in font system to make this work.

Here's a rough idea of what fonts work on which platforms:

  • Bitmap fonts (.bdf, .pcf, .snf) - Linux
  • Font resource (.fon) - Windows
  • Windows bitmap font file (.fnt) - Linux, Windows
  • PostScript OpenType font (.otf) - Mac OS X, Linux, Windows
  • Type1 multiple master (.mmm) - Windows
  • Type1 font bits (.pfb) - Linux, Windows
  • Type1 font metrics (.pfm) - Linux, Windows
  • TrueType font (.ttf) - Mac OS X, Linux, Windows
  • TrueType collection (.ttc) - Mac OS X, Linux, Windows

If the font is properly loaded, you'll get back an array of font names found in the file. Otherwise, nil is returned if no fonts were found in the file.

Also of interest: the Shoes::FONTS constant is a complete list of fonts available to you on this platform. You can check for a certain font by using include?.

 if Shoes::FONTS.include? "Helvetica"
   alert "Helvetica is available on this system."
   alert "You do not have the Helvetica font."

If you have trouble with fonts showing up, make sure your app loads the font before it is used. Especially on OS X, if fonts are used before they are loaded, the font cache will tend to ignore loaded fonts.

gradient(color1, color2) » Shoes::Pattern

Builds a linear gradient from two colors. For each color, you may pass in a Shoes::Color object or a string describing the color.

Create a grayscale color from a level of darkness and, optionally, an alpha level.

 black = gray(0.0)
 white = gray(1.0)

Logs an informational message to the user in the Shoes console. So, where debug messages are designed to help the program figure out what's happening, info messages tell the user extra information about the program.

 info("You just ran the info example on Shoes #{Shoes::RELEASE_NAME}.")

For example, whenever a Shy file loads, Shoes prints an informational message in the console describing the author of the Shy and its version.

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.

 blueviolet = rgb(138, 43, 226)
 darkgreen = rgb(0, 100, 0)

Or, use a decimal number from 0.0 to 1.0.

 blueviolet = rgb(0.54, 0.17, 0.89)
 darkgreen = rgb(0, 0.4, 0)

This method may also be called as Shoes.rgb.

Logs a warning for the user. A warning is not a catastrophic error (see error for that.) It is just a notice that the program will be changing in the future or that certain parts of the program aren't reliable yet.

To view warnings and errors, open the Shoes console with Alt-/ (or ⌘-/ on OS X.)

Next: The App Object