tea 0.6.1

data/doc/example/state_app.rb

@@ -0,0 +1,33 @@
+# Test that the app state is correctly reported.
+# Expected results: minimized app state, keybord and mouse focus is correctly
+# reported.
+
+require 'tea'
+
+puts <<TEST
+Try...
+
+ * minimising/restoring the window
+ * moving the mouse in/out of the window
+ * changing focus in/out of the window
+
+The app visibility, mouse and keyboard focus will be reported below.
+TEST
+
+Tea.init
+Tea::Screen.set_mode 320, 240
+e = nil
+puts '%19s %20s%20s%20s' % ['EVENT', 'APP VISIBILITY', 'KEYBOARD', 'MOUSE']
+puts '-' * 80
+loop do
+  visible = Tea::App.visible?  ? 'visible'     : 'not visible'
+  kbd     = Tea::Kbd.in_app?   ? 'keyboard in' : 'keyboard not in'
+  mouse   = Tea::Mouse.in_app? ? 'mouse in'    : 'mouse not in'
+  puts '%19s:%20s%20s%20s' % [e.class, visible, kbd, mouse]
+  begin
+    e = Tea::Event.get(true)
+    exit if e.class == Tea::App::Exit
+  end until [Tea::App::Minimized, Tea::App::Restored,
+             Tea::Kbd::Lost,      Tea::Kbd::Gained,
+             Tea::Mouse::Lost,    Tea::Mouse::Gained].include?(e.class)
+end

data/doc/example/state_keyboard.rb

@@ -0,0 +1,23 @@
+# Test that the keyboard state is being picked up.
+# Expected output is that all keyboard events will print if the 'A' key is
+# being pressed, and if Num Lock is active.
+
+require 'tea'
+
+puts <<TEST
+Press some keys.  Printed lines will tell if 'A' is being pressed,
+and if Num Lock is active.
+TEST
+
+Tea.init
+Tea::Screen.set_mode 320, 240
+loop do
+  a_down = Tea::Kbd.key_down?(Tea::Kbd::A) ? 'DOWN' : 'UP'
+  num_lock_active = Tea::Kbd.mod_active?(Tea::Kbd::NUM_LOCK) ? 'ON' : 'OFF'
+  puts "'A' is #{a_down}; Num Lock is #{num_lock_active}"
+  begin
+    e = Tea::Event.get(true)
+    exit if e.class == Tea::App::Exit
+  end until e.class == Tea::Kbd::Down || e.class == Tea::Kbd::Up
+  print "(#{e.key}); "
+end

data/doc/example/state_mouse.rb

@@ -0,0 +1,60 @@
+# Test that the mouse status is correctly reported.
+# Expected results include the mouse x, y, left, middle and right button down
+# status, printed whenever the mouse is used in the 400x300 screen window.
+
+require 'tea'
+
+puts <<TEST
+Move the mouse in the window.  Mouse x, y, and left/middle/right button down
+status should be reported here.
+TEST
+
+##############################################################################
+# Swiped from event_mouse.rb.  I'd make a module, but I don't want to clutter
+# this demo directory.
+
+# We can avoid flooding the terminal with VT100 codes.  Sorry Windows.
+$windows = RUBY_PLATFORM =~ /w(?:in)?32/
+SAVE_POSITION = "\x1b[s"
+RESTORE_POSITION = "\x1b[u"
+HIDE_CURSOR = "\x1b[?25l"
+UNHIDE_CURSOR = "\x1b[?25h"
+CLEAR_TO_LINE_END = "\x1b[K"
+
+# VT100-enhanced printing function that overwrites the current terminal line.
+def pr(*args)
+  print HIDE_CURSOR, SAVE_POSITION if !$windows
+  print *args
+  if $windows
+    puts
+  else
+    print CLEAR_TO_LINE_END, RESTORE_POSITION, UNHIDE_CURSOR
+  end
+end
+
+##############################################################################
+
+Tea.init
+Tea::Screen.set_mode 400, 300
+have_mouse = true
+loop do
+  begin
+    e = Tea::Event.get(true)
+    exit if e.class == Tea::App::Exit
+  end until [Tea::Mouse::Move,
+             Tea::Mouse::Down,
+             Tea::Mouse::Up,
+             Tea::Mouse::Gained,
+             Tea::Mouse::Lost].include?(e.class)
+
+  case e
+  when Tea::Mouse::Gained then have_mouse = true
+  when Tea::Mouse::Lost   then have_mouse = false
+  end
+
+  if have_mouse
+    pr "Mouse (#{Tea::Mouse.x}, #{Tea::Mouse.y}), [#{Tea::Mouse.left?}|#{Tea::Mouse.middle?}|#{Tea::Mouse.right?}]"
+  else
+    pr "Mouse is out of the house"
+  end
+end

data/doc/key_constants.textile

@@ -0,0 +1,129 @@
+These key constants are returned by key events and can be passed into keyboard status checking methods.  The all live in Tea::Kbd, so the 'A' key on your keyboard would be Tea::Kbd::A, for example.
+
+The value of each constant is a Ruby symbol with the same name, which should make debugging easier.
+
+BACKSPACE
+TAB
+ENTER
+PAUSE
+ESCAPE
+SPACE
+EXCLAMATION_MARK
+DOUBLE_QUOTE
+HASH
+DOLLAR
+AMPERSAND
+QUOTE
+OPEN_PAREN
+CLOSE_PAREN
+ASTERISK
+PLUS
+COMMA
+MINUS
+PERIOD
+SLASH
+K0
+K1
+K2
+K3
+K4
+K5
+K6
+K7
+K8
+K9
+COLON
+SEMICOLON
+LESS_THAN
+EQUALS
+GREATER_THAN
+QUESTION_MARK
+AT
+OPEN_SQUARE_BRACKET
+BACKSLASH
+CLOSE_SQUARE_BRACKET
+CARET
+UNDERSCORE
+BACKTICK
+A
+B
+C
+D
+E
+F
+G
+H
+I
+J
+K
+L
+M
+N
+O
+P
+Q
+R
+S
+T
+U
+V
+W
+X
+Y
+Z
+DELETE
+NP0
+NP1
+NP2
+NP3
+NP4
+NP5
+NP6
+NP7
+NP8
+NP9
+NP_PERIOD
+NP_DIVIDE
+NP_MULTIPLY
+NP_MINUS
+NP_PLUS
+NP_ENTER
+NP_EQUALS
+UP
+DOWN
+RIGHT
+LEFT
+INSERT
+HOME
+END
+PAGE_UP
+PAGE_DOWN
+F1
+F2
+F3
+F4
+F5
+F6
+F7
+F8
+F9
+F10
+F11
+F12
+NUM_LOCK
+CAPS_LOCK
+SCROLL_LOCK
+R_SHIFT
+L_SHIFT
+R_CTRL
+L_CTRL
+R_ALT
+L_ALT
+L_SUPER
+R_SUPER
+ALT_GR
+PRINT_SCREEN
+SYS_REQ
+BREAK
+MENU
+EURO

data/doc/key_modifiers.textile

@@ -0,0 +1,19 @@
+Key modifiers are things like Shift or Num Lock that change the meaning of some keys when they're held down or toggled on.  Tea::Kbd::Down and Tea::Kbd::Up events provide modifier information.
+
+The following constants are valid modifiers that also happen to match their keys.  Like the [[Key Constants]], they also live in Tea::Kbd, so the left Shift  key would be Tea::Kbd::L_SHIFT.
+
+L_SHIFT
+R_SHIFT
+L_CTRL
+R_CTRL
+L_ALT
+R_ALT
+NUM_LOCK
+CAPS_LOCK
+ALT_GR
+
+These extra constants can used for convenience. They also live in Tea::Kbd, but aren't physical keys.
+
+SHIFT
+CTRL
+ALT

data/doc/reference.textile

@@ -0,0 +1,421 @@
+This page is manually assembled, so parts of it may become out of date. If something's missing or doesn't exist, let me know.
+
+
+h1. Tea
+
+h2. Tea.init()
+
+Intialise Tea.  This needs to be called before using any of Tea's objects or methods.  May throw Tea::Error if initialisation fails.
+
+h2. Tea::Error
+
+This is the exception class raised when Bad Things happen in any of Tea's objects or methods.
+
+
+h1. Graphics
+
+h2. Tea::Color
+
+This module holds utility methods for working with colours.  It exists for convenience; colours can still be passed around in the form 0xRRGGBBAA.
+
+There are some pre-mixed colour constants available in it:
+
+|_. Color        |_. Red |_. Green |_. Blue |_. Alpha |
+|   CLEAR        |>.   0 |>.     0 |>.    0 |>.     0 |
+|   BLACK        |>.   0 |>.     0 |>.    0 |>.   255 |
+|   DARK_RED     |>. 128 |>.     0 |>.    0 |>.   255 |
+|   DARK_GREEN   |>.   0 |>.   128 |>.    0 |>.   255 |
+|   DARK_YELLOW  |>. 128 |>.   128 |>.    0 |>.   255 |
+|   DARK_BLUE    |>.   0 |>.     0 |>.  128 |>.   255 |
+|   DARK_MAGENTA |>. 128 |>.     0 |>.  128 |>.   255 |
+|   DARK_CYAN    |>.   0 |>.   128 |>.  128 |>.   255 |
+|   DARK_GRAY    |>. 128 |>.   128 |>.  128 |>.   255 |
+|   GRAY         |>. 192 |>.   192 |>.  192 |>.   255 |
+|   RED          |>. 255 |>.     0 |>.    0 |>.   255 |
+|   GREEN        |>.   0 |>.   255 |>.    0 |>.   255 |
+|   YELLOW       |>. 255 |>.   255 |>.    0 |>.   255 |
+|   BLUE         |>.   0 |>.     0 |>.  255 |>.   255 |
+|   MAGENTA      |>. 255 |>.     0 |>.  255 |>.   255 |
+|   CYAN         |>.   0 |>.   255 |>.  255 |>.   255 |
+|   WHITE        |>. 255 |>.   255 |>.  255 |>.   255 |
+
+h3. Tea::Color.mix(red, green, blue, alpha=255)
+
+Create a colour of the form 0xRRGGBBAA.  Each argument should be an integer between 0..255 inclusive.  The colours returned by this method can be used throughout the graphics API.
+
+h3. Tea::Color.split(color)
+
+Split a colour of the form 0xRRGGBBAA into its red, green, blue and alpha parts.  A 4-element array is returned, of the form [red, green, blue, alpha], where each element is between 0..255 inclusive.
+
+h2. Tea::Bitmap
+
+A Bitmap is a grid of pixels that holds graphics.  It can be drawn onto and drawn with.
+
+h3. Tea::Bitmap included mixins
+
+Instances of Tea::Bitmap share methods from the following modules:
+
+Tea::Blitting:
+* blit(source_blittable, x, y)
+
+Tea::Clipping:
+* clip
+* clip(x, y, w, h)
+* clip(x, y, w, h) { ... }
+
+These clip methods get, set and run a block with a clipping rectangle respectively.  While a clipping rectangle is set, drawing will be clipped inside it.
+
+Tea::Grabbing:
+* grab([x, y, w, h])
+
+This grab method copies a sub-section of the Bitmap (or all of it if no arguments are given) and returns it as a new Bitmap object.
+
+Tea::ImageSaving:
+* save(path)
+
+The save method saves the Bitmap as an image file.  Supported formats: BMP, PNG.
+
+Tea::Primitive:
+* clear()
+* [x, y]
+* [x, y] = color
+* rect(x, y, w, h, color[, {:mix => :blend (alt. :replace)}])
+* line(x1, y1, x2, y2, color[, {:antialias => false, :mix => :blend (alt. :replace)}])
+* circle(x, y, radius, color[, {:outline => false, :antialias => false, :mix => :blend (alt. :replace)}])
+
+Note that colours are of the form 0xRRGGBBAA, and can be conveniently made using Tea::Color.mix().
+
+h3. Tea::Bitmap.new(*args)
+
+Create a new Bitmap.  This can be done in 2 ways:
+
+1. Tea::Bitmap.new(image_path): load from an image file.
+2. Tea::Bitmap.new(width, height, color): create with the given size and colour.
+
+ArgumentError is raised if you don't call it in one of these ways.  Tea::Error may be raised if one of these initialisations fail.
+
+h3. Tea::Bitmap#w()
+
+The width of the Bitmap in pixels.
+
+h3. Tea::Bitmap#h()
+
+The height of the Bitmap in pixels.
+
+h2. Tea::Screen
+
+Tea::Screen acts much like a Bitmap, except things drawn to it will be displayed on the screen once Tea::Screen.update() is called.
+
+h3. Tea::Screen mixins
+
+Since Tea::Screen is an object and not a class, its mixins add methods to Tea::Screen itself.
+
+Tea::Blitting:
+* blit(source_blittable, x, y)
+
+Tea::Clipping:
+* clip
+* clip(x, y, w, h)
+* clip(x, y, w, h) { ... }
+
+These clip methods get, set and run a block with a clipping rectangle respectively.  While a clipping rectangle is set, drawing will be clipped inside it.
+
+Tea::Grabbing:
+* grab([x, y, w, h])
+
+This grab method copies a sub-section of the screen (or all of it if no arguments are given) and returns it as a new Bitmap object.
+
+Tea::ImageSaving:
+* save(path)
+
+The save method saves the Screen as an image file.  Supported formats: BMP, PNG.
+
+Tea::Primitive:
+* clear()
+* [x, y]
+* [x, y] = color
+* rect(x, y, w, h, color[, {:mix => :blend (alt. :replace)}])
+* line(x1, y1, x2, y2, color[, {:antialias => false, :mix => :blend (alt. :replace)}])
+* circle(x, y, radius, color[, {:outline => false, :antialias => false, :mix => :blend (alt. :replace)}])
+
+Note that colours are of the form 0xRRGGBBAA, and can be conveniently made with Tea::Color.mix().
+
+h3. Tea::Screen.set_mode(width, height)
+
+Create a screen window with the given dimensions.  After this, you can start drawing on the screen.  May raise Tea::Error if it fails.
+
+h3. Tea::Screen.update()
+
+Make what has been drawn on the screen visible.
+
+h3. Tea::Screen.w()
+
+The width of the screen in pixels.
+
+h3. Tea::Screen.h()
+
+The height of the screen in pixels.
+
+
+h1. Input and other events
+
+Event handling is the heart and soul of most games, so this subsystem is quite important.
+
+h2. Tea::Event
+
+The Event module allows access to the event queue, and the classes of events that come out.
+
+Events rely on having a screen window, so call Tea::Screen.set_mode before using any of these.
+
+h3. Tea::Event.get(wait=false)
+
+Get the next event in the event queue.  If wait is true and there are no events to return, this method will wait until there is one and return it.  Otherwise, an empty event queue will return nil.  The events that can be returned include:
+
+* *Tea::App::Exit*
+* *Tea::App::Minimized*
+* *Tea::App::Restored*
+
+* *Tea::Kbd::Lost*
+  - i.e. keyboard input focus lost
+* *Tea::Kbd::Gained*
+  - i.e. keyboard input focus gained
+* *Tea::Kbd::Down*
+  - key - keyboard key that was pressed (see [[Key Constants]])
+  - mods - a hash of modifiers active when key was pressed (see [[Key Modifiers]])
+  - char - character generated when the key is typed
+* *Tea::Kbd::Up*
+  - key - keyboard key that was released (see [[Key Constants]])
+  - mods - modifiers active when the key was released (see [[Key Modifiers]])
+
+* *Tea::Mouse::Move*
+  - x, y - coordinates of the mouse
+  - buttons - a hash of mouse buttons to true/false: Tea::Mouse::LEFT, MIDDLE and RIGHT
+* *Tea::Mouse::Lost*
+  - i.e. mouse is no longer in the screen window
+* *Tea::Mouse::Gained*
+  - i.e. mouse is within the screen window
+* *Tea::Mouse::Down*
+  - x, y - coordinates of the mouse when the button was pressed
+  - button - one of Tea::Mouse::LEFT, MIDDLE or RIGHT
+* *Tea::Mouse::Up*
+  - x, y - coordinates of the mouse when the button was released
+  - button - mouse button constant, same as for Tea::Mouse::Down#button
+* *Tea::Mouse::Scroll*
+  - x, y - coordinates of the mouse when the scroll wheel was used
+  - delta - 1 for a downward scroll, -1 for an upward scroll
+
+These returned event objects may have methods that give extra information about the event itself.
+
+May raise Tea::Error if getting an event fails.
+
+h2. Tea::Event::Dispatch mixin
+
+This mixin gives the class a dispatch_event method that, when called, will call a specially-named method that matches the event's class name.
+
+<pre>
+require 'tea'
+
+class MyEventHandler
+  attr_reader :done
+  def initialize
+    @done = false
+  end
+
+  include Tea::Event::Dispatch
+
+  def kbd_down(e)
+    puts "You typed: #{e.char}"
+    if e.key == Tea::Kbd::ESCAPE
+      puts 'Bye bye!'
+      @done = true
+    end
+  end
+end
+
+Tea.init
+Tea::Screen.set_mode 400, 300
+
+handler = MyEventHandler.new
+until handler.done
+  handler.dispatch_event Tea::Event.get(true)
+end
+</pre>
+
+This example shows:
+
+1. the Tea::Event::Dispatch mixin being included in a class,
+2. a sample event handling function kbd_down, matching Tea::Kbd::Down, and
+3. dispatch_event being called with an event passed into it.
+
+Event names are matched to method names as follows:
+
+1. Get the original class name, e.g. Tea::Kbd::Down.
+2. Get rid of the 'Tea::' part, e.g. Kbd::Down.
+3. Substitute the '::' for '_', e.g. Kbd_Down.
+4. Convert to all lower case, e.g. kbd_down.
+
+This mixin may not be needed for simpler games, but it can help when using classes to organise game code.
+
+h2. Tea::App
+
+As well as the app-related events that spawn from here, this module also provides some app-related status checking.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::App.visible?
+
+Returns true if the screen window is visible, i.e. not minimised.
+
+h2. Tea::Kbd
+
+As well as the keyboard-related events that spawn from here, this module also lets you check the status of keys and modifiers.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::Kbd.in_app?()
+
+Returns true if the keyboard focus is within the screen window. Most of the time, this means the screen window is in the foreground.
+
+h3. Tea::Kbd.key_down?(key)
+
+Returns true if the key given is being pressed.  See [[Key Constants]].
+
+h3. Tea::Kbd.mod_active?(mod)
+
+Returns true if the modifier is 'active'.
+
+For Shift, Ctrl, Alt and AltGr (not sure on the last one) this means they're being held down.
+
+For Num Lock and Caps Lock, this means their toggle is on.
+
+Tea::Kbd::SHIFT, CTRL and ALT can be passed in for convenience.  See [[Key Modifiers]].
+
+h2. Tea::Mouse
+
+As well as the mouse-related events that spawn from here, this module also lets you check the state of the mouse.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::Mouse.in_app?()
+
+Returns true if the mouse cursor is over the screen window.  If there are other windows in front of the screen window, this can still return true, depending on your environment.
+
+h3. Tea::Mouse.x()
+
+Get the x part of the mouse coordinates.
+
+h3. Tea::Mouse.y()
+
+Get the y part of the mouse coordinates.
+
+h3. Tea::Mouse.left?()
+
+Returns true when the left mouse button is held down.
+
+h3. Tea::Mouse.middle?()
+
+Returns true when the middle mouse button is held down.
+
+h3. Tea::Mouse.right?()
+
+Returns true when the right mouse button is held down.
+
+
+h1. Sound
+
+h2. Tea::Sound
+
+A Sound represents a loaded audio file that can be played through the computer's speakers.
+
+For now, the supported formats are: OGG, WAV, AIFF, RIFF, VOC.
+
+h3. Tea::Sound.volume()
+
+Get the master volume.  Returns a value between 0 (min) and 128 (max) inclusive.
+
+h3. Tea::Sound.volume=(new_volume)
+
+Set the master volume.  new_volume should be between 0 (min) and 128 (max) inclusive.
+
+h3. Tea::Sound.pause_all()
+
+Pause all playing sounds.
+
+h3. Tea::Sound.resume_all()
+
+Resume all paused sounds.
+
+h3. Tea::Sound.stop_all()
+
+Stop all playing and paused sounds.
+
+h3. Tea::Sound.new(path)
+
+Load a new sound from an audio file.
+
+h3. Tea::Sound#volume()
+
+Get the volume of the sound.  Returns a value between 0 (min) and 128 (max) inclusive.
+
+h3. Tea::Sound#volume=(new_volume)
+
+Set the volume of the sound.  new_volume should be between 0 (min) and 128 (max) inclusive.
+
+h3. Tea::Sound#play(loops=0)
+
+Play the sound.  If it's already playing, cut it off and start over.  loops should be the number of times to repeat the sound; use -1 to repeat it forever.
+
+h3. Tea::Sound#pause()
+
+Pause the sound if it's playing, otherwise do nothing.
+
+h3. Tea::Sound#resume()
+
+Resume playing the sound if it was paused, otherwise do nothing.
+
+h3. Tea::Sound#stop()
+
+Stop the sound if it's playing, otherwise do nothing.
+
+h3. Tea::Sound#state()
+
+Check if the sound is stopped, playing or paused.  Returns one of Tea::Sound::STOPPED, Tea::Sound::PLAYING or Tea::Sound::PAUSED.
+
+
+h1. Fonts
+
+h2. Tea::Font
+
+A font is a set of images (glyphs) that controls how text appears when it is drawn.
+
+Currently, bitmap fonts and Karl Bartel's SFont formats are supported.
+
+Bitmap fonts are 256 character images in a row, in a single BMP or PNG, in ASCII order.
+
+SFont files are 94 character images in a row, also in a single BMP or PNG, in ASCII order, starting with ASCII code 33.  Letters are variable width, and are separated with magenta gaps (255, 0, 255) in the top row.  The SFont alphabet is as follows:
+
+<pre>
+    ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @
+    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ `
+    a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
+</pre>
+
+h3. Tea::Font.new(path, type[, {:transparent_color => Tea::Color::MAGENTA}])
+
+Load a font from a file.  Type may be Tea::Font::BITMAP_FONT or Tea::Font::SFONT.  Setting transparent_color will cause that color to be treated as transparent when the font is loaded.
+
+h3. Tea::Font#string_w(string)
+
+Get the width of a string rendered with the font, in pixels.
+
+h3. Tea::Font#h()
+
+Get the height of the font's characters, in pixels.
+
+h3. Tea::Font#word_wrap(string, width, initial_left_margin=0)
+
+Split the string into lines that, when drawn with this font, do not exceed width.  Setting initial_left_margin will treat the string as starting that many pixels away from the left "edge" of wrapping.  Returns an instance of WrappedLines, which is an Array in all ways except that it also has the position of the end of the final line from the left "edge", accessible as end_x.
+
+h3. Tea::Font#draw_to(dest_blittable, x, y, string)
+
+Render the string using the font onto dest_blittable (a Bitmap or the Screen), with the top-left corner at (x, y).