allegro4r 0.0.1

data/examples/exflip.rb

@@ -0,0 +1,87 @@
+#
+# Example program (C Version) for the Allegro library, by Shawn Hargreaves.
+#   (Ruby port by Jason Frey)
+#
+# This program moves a circle across the screen, first with a
+# double buffer and then using page flips.
+#
+
+require 'rubygems'
+require 'allegro4r'
+include Allegro4r::API
+
+exit 1 if allegro_init != 0
+install_timer
+install_keyboard
+
+# Some platforms do page flipping by making one large screen that you
+# can then scroll, while others give you several smaller, unique
+# surfaces. If you use the create_video_bitmap() function, the same
+# code can work on either kind of platform, but you have to be careful
+# how you set the video mode in the first place. We want two pages of
+# 320x200 video memory, but if we just ask for that, on DOS Allegro
+# might use a VGA driver that won't later be able to give us a second
+# page of vram. But if we ask for the full 320x400 virtual screen that
+# we want, the call will fail when using DirectX drivers that can't do
+# this. So we try two different mode sets, first asking for the 320x400
+# size, and if that doesn't work, for 320x200.
+if set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 400) != 0
+  if set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0
+    if set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0
+      set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+      allegro_message("Unable to set any graphic mode\n%s\n" % allegro_error)
+      exit 1
+    end
+  end
+end
+
+set_palette(desktop_palette)
+
+# allocate the memory buffer
+buffer = create_bitmap(SCREEN_W(), SCREEN_H())
+
+# first with a double buffer...
+clear_keybuf
+c = retrace_count + 32
+while retrace_count - c <= SCREEN_W() + 32
+  clear_to_color(buffer, makecol(255, 255, 255))
+  circlefill(buffer, retrace_count - c, SCREEN_H()/2, 32, makecol(0, 0, 0))
+  textprintf_ex(buffer, font, 0, 0, makecol(0, 0, 0), -1, "Double buffered (%s)" % gfx_driver.name)
+  blit(buffer, screen, 0, 0, 0, 0, SCREEN_W(), SCREEN_H())
+
+  break if keypressed
+end
+
+destroy_bitmap(buffer)
+
+# now create two video memory bitmaps for the page flipping
+page1 = create_video_bitmap(SCREEN_W(), SCREEN_H())
+page2 = create_video_bitmap(SCREEN_W(), SCREEN_H())
+
+if page1.nil? || page2.nil?
+  set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+  allegro_message("Unable to create two video memory pages\n")
+  exit 1
+end
+
+active_page = page2
+
+# do the animation using page flips...
+clear_keybuf
+(-32..SCREEN_W() + 32).each do |c|
+  clear_to_color(active_page, makecol(255, 255, 255))
+  circlefill(active_page, c, SCREEN_H()/2, 32, makecol(0, 0, 0))
+  textprintf_ex(active_page, font, 0, 0, makecol(0, 0, 0), -1, "Page flipping (%s)" % gfx_driver.name)
+  show_video_bitmap(active_page)
+
+  if (active_page == page1)
+    active_page = page2
+  else
+    active_page = page1
+  end
+
+  break if keypressed
+end
+
+destroy_bitmap(page1)
+destroy_bitmap(page2)

data/examples/exfont.rb

@@ -0,0 +1,70 @@
+#
+# Example program (C version) for the Allegro library, by Evert Glebbeek.
+#   (Ruby port by Jason Frey)
+#
+# This is a very simple program showing how to load and manipulate fonts.
+#
+
+require 'rubygems'
+require 'allegro4r'
+include Allegro4r::API
+
+# you should always do this at the start of Allegro programs
+exit 1 if allegro_init != 0
+
+# set up the keyboard handler
+install_keyboard
+
+# set a graphics mode sized 320x200
+if set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0
+  if set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0
+    set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+    allegro_message("Unable to set any graphic mode\n%s\n" % allegro_error)
+    exit 1
+  end
+end
+
+# set the color palette
+set_palette(desktop_palette)
+
+# clear the screen to white
+clear_to_color(screen, makecol(255, 255, 255))
+
+# We will use the lower case letters from Allegro's normal font and the
+# uppercase letters from the font in unifont.dat
+f1 = load_font("unifont.dat", nil, nil)
+if f1.nil?
+  set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+  allegro_message("Cannot find unifont.dat in current directory.\n")
+  exit 1
+end
+
+# Extract character ranges
+f2 = extract_font_range(font, ' '[0], ?A - 1)
+f3 = extract_font_range(f1, ?A, ?Z);
+f4 = extract_font_range(font, ?Z + 1, ?z)
+
+# Merge fonts
+Allegro4r::API.font = merge_fonts(f4, f5 = merge_fonts(f2, f3))
+
+# Destroy temporary fonts
+destroy_font(f1)
+destroy_font(f2)
+destroy_font(f3)
+destroy_font(f4)
+destroy_font(f5)
+
+# you don't need to do this, but on some platforms (eg. Windows) things
+# will be drawn more quickly if you always acquire the screen before
+# trying to draw onto it.
+acquire_screen
+
+# write some text to the screen with black letters and transparent
+# background
+textout_centre_ex(screen, font, "Hello, world!", SCREEN_W()/2, SCREEN_H()/2, makecol(0, 0, 0), -1)
+
+# you must always release bitmaps before calling any input functions
+release_screen
+
+# wait for a key press
+readkey

data/examples/exhello.rb

@@ -0,0 +1,46 @@
+#
+# Example program (C version) for the Allegro library, by Shawn Hargreaves.
+#   (Ruby port by Jason Frey)
+#
+# This is a very simple program showing how to get into graphics
+# mode and draw text onto the screen.
+#
+
+require 'rubygems'
+require 'allegro4r'
+include Allegro4r::API
+
+# you should always do this at the start of Allegro programs
+exit 1 if allegro_init != 0
+
+# set up the keyboard handler
+install_keyboard
+
+# set a graphics mode sized 320x200
+if set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0
+  if set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0
+    set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+    allegro_message("Unable to set any graphic mode\n%s\n" % allegro_error)
+    exit 1
+  end
+end
+
+# set the color palette
+set_palette(desktop_palette)
+
+# clear the screen to white
+clear_to_color(screen, makecol(255, 255, 255))
+
+# you don't need to do this, but on some platforms (eg. Windows) things
+# will be drawn more quickly if you always acquire the screen before
+# trying to draw onto it.
+acquire_screen
+
+# write some text to the screen with black letters and transparent background
+textout_centre_ex(screen, font, "Hello, world!", SCREEN_W()/2, SCREEN_H()/2, makecol(0, 0, 0), -1)
+
+# you must always release bitmaps before calling any input functions
+release_screen
+
+# wait for a key press
+readkey

data/examples/exjoy.rb

@@ -0,0 +1,206 @@
+#
+# Example program (C Version) for the Allegro library, by Grzegorz Adam Hankiewicz.
+#   (Ruby port by Jason Frey)
+#
+# This program uses the Allegro library to detect and read the value
+# of a joystick. The output of the program is a small target sight
+# on the screen which you can move. At the same time the program will
+# tell you what you are doing with the joystick (moving or firing).
+
+require 'rubygems'
+require 'allegro4r'
+include Allegro4r::API
+
+x = 160; y = 100       # these will be used to show the target sight
+analogmode = false
+
+exit 1 if allegro_init != 0 # you NEED this man! ;-)
+
+install_keyboard # ahh... read the docs. I will explain only
+# joystick specific routines
+
+if set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0
+  if set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0
+    set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+    allegro_message("Unable to set any graphic mode\n%s\n" % allegro_error)
+    exit 1
+  end
+end
+
+set_palette(default_palette)
+clear_bitmap(screen)
+textout_centre_ex(screen, font, "Please center the joystick", SCREEN_W()/2, SCREEN_H()/2 - 36, palette_color[255], 0)
+textout_centre_ex(screen, font, "and press a key.", SCREEN_W()/2, SCREEN_H()/2 - 20, palette_color[255], 0)
+
+exit 0 if (readkey & 0xFF) == 27
+
+# the first thing is to initialise the joystick driver
+if install_joystick(JOY_TYPE_AUTODETECT) != 0
+  set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+  allegro_message("Error initialising joystick\n%s\n", allegro_error)
+  exit 1
+end
+
+# make sure that we really do have a joystick
+if num_joysticks == 0
+  set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+  allegro_message("Error: joystick not found\n")
+  exit 1
+end
+
+# before using the joystick, we have to calibrate it. This loop only
+# calibrates joystick number 0, but you could do the same thing for
+# other sticks if they are present (the num_joysticks variable will
+# tell you how many there are).
+while joy[0].flags & JOYFLAG_CALIBRATE != 0
+  msg = calibrate_joystick_name(0)
+
+  clear_bitmap(screen)
+  textout_centre_ex(screen, font, msg, SCREEN_W()/2, 64, palette_color[255], 0)
+  textout_centre_ex(screen, font, "and press a key.", SCREEN_W()/2, 80, palette_color[255], 0)
+  
+  exit 0 if (readkey & 0xFF) == 27
+  
+  if calibrate_joystick(0) != 0
+    set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+    allegro_message("Error calibrating joystick!\n")
+    exit 1
+  end
+end
+
+# if this joystick supports analogue input, ask the user whether to
+# use digital or analogue mode. If it is only a digital pad, we don't
+# bother with this question.
+#
+if joy[0].stick[0].flags & JOYFLAG_ANALOGUE != 0
+  clear_bitmap(screen)
+  textout_centre_ex(screen, font, "Now press 'D' to use a digital", SCREEN_W()/2, 64, palette_color[255], 0)
+  textout_centre_ex(screen, font, "joystick or 'A' for analogue mode.", SCREEN_W()/2, 80, palette_color[255], 0)
+
+  loop do
+    c = readkey & 0xFF
+  
+    if c == ?d || c == ?D
+      analogmode = false
+      break
+    elsif c == ?a || c == ?A
+      analogmode = true
+      break
+    elsif c == 27
+      exit 0
+    end
+  end
+else
+  analogmode = false
+end
+
+drawing_mode(DRAW_MODE_XOR, nil, 0, 0)
+clear_keybuf
+
+bmp = create_bitmap(320, 200)
+clear_bitmap(bmp)
+
+loop do
+  poll_joystick     # we HAVE to do this to read the joystick
+
+  clear_bitmap(bmp)
+
+  textout_centre_ex(bmp, font, joystick_driver.name, 160, 150, palette_color[255], 0)
+
+  if (analogmode)
+    textout_centre_ex(bmp, font, "Analog mode selected", 160, 160, palette_color[255], 0)
+  else
+    textout_centre_ex(bmp, font, "Digital mode selected", 160, 160, palette_color[255], 0)
+  end
+
+  textout_centre_ex(bmp, font, "Move the joystick all around", 160, 170, palette_color[255], 0)
+  textout_centre_ex(bmp, font, "Press any key to exit", 160, 180, palette_color[255], 0)
+  textout_centre_ex(bmp, font, "Made by Grzegorz Adam Hankiewicz", 160, 190, palette_color[255], 0)
+
+  # if we detect any buttons, we print a message on the screen
+  (0...joy[0].num_buttons).each do |c|
+    if (joy[0].button[c].b)
+      textprintf_centre_ex(bmp, font, 160, c*10, palette_color[15], 0, "%s pressed" % joy[0].button[c].name)
+    end
+  end
+  
+  if !analogmode
+    # now we have to check individually every possible movement
+    # and actualize the coordinates of the target sight.
+    if joy[0].stick[0].axis[0].d1
+      x -= 1 if x > 0
+      textout_centre_ex(bmp, font, "Left", 120, 100, palette_color[255], 0)
+    end
+    if joy[0].stick[0].axis[0].d2
+      x += 1 if x < 319
+      textout_centre_ex(bmp, font, "Right", 200, 100, palette_color[255], 0)
+    end
+    if joy[0].stick[0].axis[1].d1
+      y -= 1 if y > 0
+      textout_centre_ex(bmp, font, "Up", 160, 70, palette_color[255], 0)
+    end
+    if joy[0].stick[0].axis[1].d2
+      y += 1 if y < 199
+      textout_centre_ex(bmp, font, "Down", 160, 130, palette_color[255], 0)
+    end
+  else
+    # yeah! Remember the 'ifs' of the digital part? This looks
+    # much better, only 2 lines.
+    x += joy[0].stick[0].axis[0].pos/40
+    y += joy[0].stick[0].axis[1].pos/40
+
+    # for informational purposes, show the input values on screen */
+    textprintf_ex(bmp, font, 0,  0, palette_color[255], 0, "Axis 0: %d" % joy[0].stick[0].axis[0].pos)
+    textprintf_ex(bmp, font, 0, 10, palette_color[255], 0, "Axis 1: %d" % joy[0].stick[0].axis[1].pos)
+
+    # by checking if the values were positive or negative, we
+    # can know in which the direction the user pulled the joy.
+    if joy[0].stick[0].axis[0].pos/40 < 0
+      textout_centre_ex(bmp, font, "Left", 120, 100, palette_color[255], 0)
+    end
+
+    if joy[0].stick[0].axis[0].pos/40 > 0
+      textout_centre_ex(bmp, font, "Right", 200, 100, palette_color[255], 0)
+    end
+
+    if joy[0].stick[0].axis[1].pos/40 < 0
+      textout_centre_ex(bmp, font, "Up", 160, 70, palette_color[255], 0)
+    end
+
+    if joy[0].stick[0].axis[1].pos/40 > 0
+      textout_centre_ex(bmp, font, "Down", 160, 130, palette_color[255], 0)
+    end
+
+    # WARNING! An analog joystick can move more than 1 pixel at
+    # a time and the checks we did with the digital part don't
+    # work any longer because the steps of the target sight could
+    # 'jump' over the limits.
+    # To avoid this, we just check if the target sight has gone
+    # out of the screen. If yes, we put it back at the border.
+    x = 319 if x > 319
+
+    x = 0 if x < 0
+
+    y = 0 if y < 0
+
+    y = 199 if y > 199
+  end
+
+  # this draws the target sight.
+  circle(bmp, x, y, 5, palette_color[255])
+  putpixel(bmp, x, y, palette_color[255])
+  putpixel(bmp, x+1, y, palette_color[255])
+  putpixel(bmp, x, y+1, palette_color[255])
+  putpixel(bmp, x-1, y, palette_color[255])
+  putpixel(bmp, x, y-1, palette_color[255])
+  putpixel(bmp, x+5, y, palette_color[255])
+  putpixel(bmp, x, y+5, palette_color[255])
+  putpixel(bmp, x-5, y, palette_color[255])
+  putpixel(bmp, x, y-5, palette_color[255])
+
+  blit(bmp, screen, 0, 0, SCREEN_W()/2 - 160, SCREEN_H()/2 - 100, 320, 200)
+
+  break unless !keypressed
+end
+
+destroy_bitmap(bmp)

data/examples/exkeys.rb

@@ -0,0 +1,216 @@
+#
+# Example program (C Version) for the Allegro library, by Shawn Hargreaves.
+#   (Ruby port by Jason Frey)
+#
+# This program demonstrates how to access the keyboard. The
+# first part shows the basic use of readkey(). The second part
+# shows how to extract the ASCII value. Next come the scan codes.
+# The fourth test detects modifier keys like alt or shift. The
+# fifth test requires some focus to be passed. The final step
+# shows how to use the global key array to read simultaneous
+# key presses.
+# The last method to detect key presses are keyboard callbacks.
+# This is demonstrated by by installing a keyboard callback,
+# which marks all pressed keys by drawing to a grid.
+#
+
+require 'rubygems'
+require 'allegro4r'
+include Allegro4r::API
+
+key_names = [
+  "(none)",         "KEY_A",          "KEY_B",          "KEY_C",
+  "KEY_D",          "KEY_E",          "KEY_F",          "KEY_G",
+  "KEY_H",          "KEY_I",          "KEY_J",          "KEY_K",
+  "KEY_L",          "KEY_M",          "KEY_N",          "KEY_O",
+  "KEY_P",          "KEY_Q",          "KEY_R",          "KEY_S",
+  "KEY_T",          "KEY_U",          "KEY_V",          "KEY_W",
+  "KEY_X",          "KEY_Y",          "KEY_Z",          "KEY_0",
+  "KEY_1",          "KEY_2",          "KEY_3",          "KEY_4",
+  "KEY_5",          "KEY_6",          "KEY_7",          "KEY_8",
+  "KEY_9",          "KEY_0_PAD",      "KEY_1_PAD",      "KEY_2_PAD",
+  "KEY_3_PAD",      "KEY_4_PAD",      "KEY_5_PAD",      "KEY_6_PAD",
+  "KEY_7_PAD",      "KEY_8_PAD",      "KEY_9_PAD",      "KEY_F1",
+  "KEY_F2",         "KEY_F3",         "KEY_F4",         "KEY_F5",
+  "KEY_F6",         "KEY_F7",         "KEY_F8",         "KEY_F9",
+  "KEY_F10",        "KEY_F11",        "KEY_F12",        "KEY_ESC",
+  "KEY_TILDE",      "KEY_MINUS",      "KEY_EQUALS",     "KEY_BACKSPACE",
+  "KEY_TAB",        "KEY_OPENBRACE",  "KEY_CLOSEBRACE", "KEY_ENTER",
+  "KEY_COLON",      "KEY_QUOTE",      "KEY_BACKSLASH",  "KEY_BACKSLASH2",
+  "KEY_COMMA",      "KEY_STOP",       "KEY_SLASH",      "KEY_SPACE",
+  "KEY_INSERT",     "KEY_DEL",        "KEY_HOME",       "KEY_END",
+  "KEY_PGUP",       "KEY_PGDN",       "KEY_LEFT",       "KEY_RIGHT",
+  "KEY_UP",         "KEY_DOWN",       "KEY_SLASH_PAD",  "KEY_ASTERISK",
+  "KEY_MINUS_PAD",  "KEY_PLUS_PAD",   "KEY_DEL_PAD",    "KEY_ENTER_PAD",
+  "KEY_PRTSCR",     "KEY_PAUSE",      "KEY_ABNT_C1",    "KEY_YEN",
+  "KEY_KANA",       "KEY_CONVERT",    "KEY_NOCONVERT",  "KEY_AT",
+  "KEY_CIRCUMFLEX", "KEY_COLON2",     "KEY_KANJI",      "KEY_EQUALS_PAD",
+  "KEY_BACKQUOTE",  "KEY_SEMICOLON",  "KEY_COMMAND",    "KEY_UNKNOWN1",
+  "KEY_UNKNOWN2",   "KEY_UNKNOWN3",   "KEY_UNKNOWN4",   "KEY_UNKNOWN5",
+  "KEY_UNKNOWN6",   "KEY_UNKNOWN7",   "KEY_UNKNOWN8",   "KEY_LSHIFT",
+  "KEY_RSHIFT",     "KEY_LCONTROL",   "KEY_RCONTROL",   "KEY_ALT",
+  "KEY_ALTGR",      "KEY_LWIN",       "KEY_RWIN",       "KEY_MENU",
+  "KEY_SCRLOCK",    "KEY_NUMLOCK",    "KEY_CAPSLOCK",   "KEY_MAX"
+]
+
+# Keyboard callback. We are very evil and draw to the screen from within
+# the callback. Don't do this in your own programs ;)
+def keypress_handler(scancode)
+  i = scancode & 0x7f
+  x = SCREEN_W() - 100 * 3 + (i % 3) * 100
+  y = SCREEN_H() / 2 + (i / 3 - 21) * 10
+  color = scancode & 0x80 != 0 ? makecol(255, 255, 0) : makecol(128, 0, 0)
+  rectfill(screen, x, y, x + 95, y + 8, color)
+  str = ustrzncpy(scancode_to_name(i), 12)
+  textprintf_ex(screen, font, x + 1, y + 1, makecol(0, 0, 0), -1, str)
+end
+
+# helper function for making more room on the screen
+def scroll
+  blit(screen, screen, 0, 32, 0, 24, SCREEN_W() / 2, SCREEN_H() - 32)
+  rectfill(screen, 0, SCREEN_H() - 16, SCREEN_W() / 2, SCREEN_H() - 1, makecol(255, 255, 255))
+end
+
+exit 1 if allegro_init != 0
+install_keyboard
+install_timer
+
+if set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0
+  if set_gfx_mode(GFX_SAFE, 640, 480, 0, 0) != 0
+    set_gfx_mode(GFX_TEXT, 0, 0, 0, 0)
+    allegro_message("Unable to set any graphic mode\n%s\n" % allegro_error)
+    exit 1
+  end
+end
+
+set_palette(desktop_palette)
+
+clear_to_color(screen, makecol(255, 255, 255))
+
+# Draw the initial keys grid by simulating release of every key.
+(0...KEY_MAX).each do |k|
+  keypress_handler(k + 0x80)
+end
+
+# Install our keyboard callback.
+# TODO: Have not been able to figure out how to get the keyboard interrupt stuff
+# to work with Ruby, so I'm temporarily skipping this part.
+# LOCK_FUNCTION(:keypress_handler)
+# Allegro4r::API.keyboard_lowlevel_callback = self.method(:keypress_handler)
+
+acquire_screen
+textprintf_centre_ex(screen, font, SCREEN_W()/2, 8, makecol(0, 0, 0), makecol(255, 255, 255), "Driver: %s" % keyboard_driver.name)
+
+# keyboard input can be accessed with the readkey function
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press some keys (ESC to finish)")
+scroll
+
+loop do
+  release_screen
+  k = readkey
+  acquire_screen
+  scroll
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "readkey returned %-6d (0x%04X)" % [k, k])
+  break unless (k & 0xFF) != 27
+end
+
+# the ASCII code is in the low byte of the return value
+scroll; scroll; scroll
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press some more keys (ESC to finish)")
+scroll
+
+loop do
+  release_screen
+  k = readkey
+  acquire_screen
+  scroll
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "ASCII code is %d" % (k & 0xFF))
+  break unless (k & 0xFF) != 27
+end
+
+# the hardware scan code is in the high byte of the return value
+scroll; scroll; scroll
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press some more keys (ESC to finish)")
+scroll
+
+loop do
+  release_screen
+  k = readkey
+  acquire_screen
+  scroll
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Scan code is %d (%s)" % [k>>8, key_names[k>>8]])
+  break unless (k & 0xFF) != 27
+end
+  
+# key qualifiers are stored in the key_shifts variable. Note that this
+# version of the code uses ureadkey instead of readkey: that is
+# necessary if you want to access Unicode characters from outside
+# the normal ASCII range, for example to support Russian or Chinese.
+scroll; scroll; scroll
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press some more keys (ESC to finish)")
+scroll
+
+loop do
+  release_screen
+  k = ureadkey(nil)
+  acquire_screen
+  buf = ""
+  buf << "shift "   if (key_shifts & KB_SHIFT_FLAG != 0)
+  buf << "ctrl "    if (key_shifts & KB_CTRL_FLAG != 0)
+  buf << "alt "     if (key_shifts & KB_ALT_FLAG != 0)
+  buf << "lwin "    if (key_shifts & KB_LWIN_FLAG != 0)
+  buf << "rwin "    if (key_shifts & KB_RWIN_FLAG != 0)
+  buf << "menu "    if (key_shifts & KB_MENU_FLAG != 0)
+  buf << "command " if (key_shifts & KB_COMMAND_FLAG != 0)
+  buf << usprintf("'%c' [0x%02x]" % [k != 0 ? k : ' '[0], k])
+  buf << " caps"    if (key_shifts & KB_CAPSLOCK_FLAG != 0)
+  buf << " num"     if (key_shifts & KB_NUMLOCK_FLAG != 0)
+  buf << " scrl"    if (key_shifts & KB_SCROLOCK_FLAG != 0)
+  scroll
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), buf)
+  break unless k != 27
+end
+
+# various scan codes are defined in allegro.h as KEY_* constants
+scroll; scroll; scroll
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press F6")
+scroll
+
+release_screen
+k = readkey
+acquire_screen
+
+while (k>>8) != KEY_F6 && (k>>8) != KEY_ESC
+  scroll
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Wrong key, stupid! I said press F6")
+  release_screen
+  k = readkey
+  acquire_screen
+end
+
+# for detecting multiple simultaneous key presses, use the key[] array
+scroll; scroll; scroll
+textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), "Press a combination of numbers")
+scroll; scroll
+
+release_screen
+
+buf = ' ' * 10
+loop do
+  buf[0] = key[KEY_0] ? '0' : ' '
+  buf[1] = key[KEY_1] ? '1' : ' '
+  buf[2] = key[KEY_2] ? '2' : ' '
+  buf[3] = key[KEY_3] ? '3' : ' '
+  buf[4] = key[KEY_4] ? '4' : ' '
+  buf[5] = key[KEY_5] ? '5' : ' '
+  buf[6] = key[KEY_6] ? '6' : ' '
+  buf[7] = key[KEY_7] ? '7' : ' '
+  buf[8] = key[KEY_8] ? '8' : ' '
+  buf[9] = key[KEY_9] ? '9' : ' '
+  textprintf_ex(screen, font, 8, SCREEN_H()-16, makecol(0, 0, 0), makecol(255, 255, 255), buf)
+  rest(1)
+  break unless !keypressed || (readkey >> 8) != KEY_ESC
+end
+
+clear_keybuf
+# Allegro4r::API.keyboard_lowlevel_callback = nil;