Understanding events and listeners

Events are sent to listeners. Functions or objects can be event listeners. When an event occurs, the listener is called by a table representing the event. All events will have a property name that identifies the kind of event.

Register events

Display objects and global Runtime objects can be event listeners. You can add and remove listeners for events using the following object methods:

  • object:addEventListener( ): It adds a listener to the object's list of listeners. When the named event occurs, the listener will be invoked and be supplied with a table representing the event.
  • object:removeEventListener( ): It removes the specified listener from the object's list of listeners so that it no longer is notified of events corresponding to the specified event.

In the following example, an image display object registers to receive a touch event. Touch events are not broadcast globally. Display objects that register for the event and lie underneath it will be candidates for receiving the touch.

local playBtn = display.newImage("playbtn.png") 
playBtn.name = "playbutton"
 
local function listener(event) 
 if event.target.name == "playbutton" then
    
print("The button was touched.")

 end 
end
 
playBtn:addEventListener("touch", listener )

Runtime events are sent by the system. They broadcast to all listeners. The following is an example of registering for an enterFrame event:

local playBtn = display.newImage("playbtn.png") 

local function listener(event) 
 print("The button appeared.")
end 
 
Runtime:addEventListener("enterFrame", listener )

Runtime events

The application we're creating uses runtime events. Runtime events have no specific target and are only sent to the global Runtime. They broadcast to all registered listeners. The following events all have string names and will be applied to the Breakout game:

enterFrame

enterFrame events occur at the frame interval of the application. They are only sent to the global Runtime object. For example, if the frame rate is 30fps, then it will occur approximately 30 times per second.

Properties are available in this event:

  • event.name is the string "enterFrame".
  • event.time is the time in milliseconds since the start of the application.

accelerometer

Accelerometer events let you detect movements and determine the device's orientation in relation to gravity. These events are only sent to devices that support accelerometer. They are only sent to the global Runtime object.

The following properties are available for this event:

  • event.name is the string "accelerometer".
  • event.xGravity is the acceleration due to gravity in the x-direction.
  • event.yGravity is the acceleration due to gravity in the y-direction.
  • event.zGravityis the acceleration due to gravity in the z-direction.
  • event.xInstantis the instantaneous acceleration in the x-direction.
  • event.yInstant is the instantaneous acceleration in the y-direction.
  • event.zInstantis the instantaneous acceleration in the z-direction.
  • event.isShake is true when the user shakes the device.

Touch events

When the user's finger touches the screen, a hit event is generated and dispatched to display objects in the display hierarchy. Only those objects that intersect with the location of the finger on the screen will receive the event.

touch (single touch)

Touch events are a special kind of hit event. When a user's finger touches the screen, they are starting a sequence of touch events, each with different phases.

  • event.name is the string "touch".
  • event.x is the x-position in screen coordinates of the touch.
  • event.y is the y-position in screen coordinates of the touch.
  • event.xStart is the x-position of the touch from the "began" phase of the touch sequence.
  • event.yStart is the y-position of the touch from the "began" phase of the touch sequence.
  • event.phase is a string identifying where in the touch sequence the event occurred:
    • "began" a finger touched the screen.
    • "moved" a finger moved on the screen.
    • "ended" a finger was lifted from the screen.
    • "cancelled" the system cancelled tracking of the touch.

tap

tap generates a hit event when the user touches the screen. The event is dispatched to display objects in the display hierarchy. This is similar to the touch event except a hit count (number of taps) is available in the event callback.

  • event.name is the string "tap".
  • event.numTaps returns the number of taps on the screen.
  • event.x is the x-position in screen coordinates of the tap.
  • event.y is the y-position in screen coordinates of the tap.
上一章目录下一章