Chap. 05 - Keyboard and Mouse

Event System Basics

Wild Pockets has an "event system" whose primary purpose is to notify the program of keyboard keys, mouse clicks, and mouse movement. The event system works as follows: every event has a name, such as "keyPress-leftMouse". To respond to events, you must create an EventMap that connects event names to event handling functions. Here is a simple example:

local eventmap = EventMap.new()
eventmap:setEvent("keyPress-left", handleLeftArrow)
eventmap:setEvent("keyPress-right", handleRightArrow)
EventHandler.push(eventmap)

function handleLeftArrow()
    print("You pressed the left arrow key.")
end

function handleRightArrow()
    print("You pressed the right arrow key.")
end

The EventMap is basically a table of event names and functions. The command EventHandler.push adds the EventMap to the "event stack." When an event occurs (such as the user pressing a mouse button), the system looks at all the EventMaps in the event stack, starting with the most-recently added EventMap. If the EventMap has an entry for the relevant event name, then the function is called, and event handling is done. If not, the next EventMap in the stack is checked until finally an EventMap responds to the event.

Major Event Types

Here is a list of all the major event categories:

     

  • keyPress events. The event name is the word "keyPress" concatenated to a dash and then the key-name. For example, the event name might be keyPress-left, keyPress-tab, or keyPress-a. These are sent whenever the user pushes a button on the keyboard or the mouse. These events are untranslated. For instance, on my US keyboard, the "1" key also has an exclamation point "!". If I press shift-1, the events I receive are "keyPress-shift" then "keyPress-1", not "keyPress-!". Mouse buttons also send keyPress events (keyPress-leftMouse, keyPress-rightMouse).

     

  • keyRepeat events. These are sent whenever the keyboard's autorepeat function triggers. You will only receive a keyRepeat event if you have previously received the corresponding keyPress event.

     

  • keyRelease events. These are sent whenever you let go of the button on the keyboard. You will only receive a keyRelease if you have previously received the corresponding keyPress event.

     

  • keyDown events. When a keyboard key is down, a keyDown event is sent every frame. This differs from keyRepeat in that keyRepeat events are only sent when the operating system autorepeat triggers, whereas keyDown events are sent every frame.

     

  • characterPressed events. These events are sent whenever the user has typed a character on the keyboard. If I press shift-1 on my US keyboard, the characterPressed event for exclamation point will be sent. Unlike keyPress events, the event name is just "characterPressed". The actual character is passed separately (see below).

Event Arguments

Event handling functions may receive additional arguments, depending on the event type. This table shows the arguments for each event type:

  • keyPress shiftFlag ctrlFlag
  • keyRepeat shiftFlag ctrlFlag
  • keyRelease shiftFlag ctrlFlag
  • keyDown
  • characterPressed characterAsciiCode

The shiftFlag and ctrlFlag are attached to key-related events to indicate what state the keyboard shift and ctrl keys were in when the event was sent. Note that the keyDown event doesn't contain these values yet. You can get the same information by calling EventHandler.getKeyDown("shift") and the like. Here's some example code that utilizes these extra arguments:

function onSceneStart()
    local evt = EventMap.new()
    EventMap:setEvent("keyPress-enter", handleEnterKey)
    EventHandler.push(evt)
end    

function handleEnterKey(shiftFlag, ctrlFlag)
    print("Somebody pressed the Enter key.")
    print("Shift key down: ", shiftFlag)
    print("Control key down: ", ctrlFlag)
end

List of all Keyboard Key Names

  • leftMouse
  • rightMouse
  • middleMouse
  • backspace
  • tab
  • enter
  • shift
  • ctrl
  • pause
  • capsLock
  • esc
  • space
  • pageUp
  • pageDown
  • end
  • home
  • left
  • up
  • right
  • down
  • insert
  • delete
  • 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
  • num+
  • num-
  • f1
  • f2
  • f3
  • f4
  • f5
  • f6
  • f7
  • f8
  • f9
  • f10
  • f11
  • f12
  • numLock
  • scrollLock
  • ;
  • =
  • ,
  • -
  • .
  • /
  • `
  • [
  • \
  • ]
  • '

Other Keyboard and Mouse-Related Operations

You can just ask whether or not a given key is pressed by calling EventHandler.keyIsDown(key). The argument to this function is a key-name as you might find in a keyPress event. It is possible to get the mouse position without using events by calling Mouse:getX, Mouse:getY, or Mouse:getXY (which returns two values). It is also possible to find out what object in the scene the mouse is pointing at by calling Mouse:getTopObject.