Gideros Mobile Tutorial 5: Events

admin Gideros, Mobile Development

So far we only displayed some graphics on the screen, we even animated (not real animation though, just rotation of one bitmap) it but there was no user interaction at all. We had one event in Tutorial 4 but it was not really explained in details what it does.

Events and addEventListener

With events we handle responses and they allow us to create interactive applications. The target of an event is a listener function and an optional data value so when an event is dispatched, the registered function is called.  If the optional data value is given, it is used as a first parameter while calling the listener function.  In Gideros we have built-in events generated by the system (e.g. ENTER_FRAME event, touch events, timer events, etc.) and custom events which can be generated by the user.

Here are few examples of kinds of events:

  • ENTER_FRAME  – this event is dispatched every frame. If your game is 60 fps then 60 times/s
  • MOUSE_DOWN – dispatched every time someone presses “mouse” button
  • MOUSE_UP – dispatched every time “mouse” button is released
  • TOUCHES_BEGIN – dispatched every time screen is touched
  • TIMER  – events tied to timers

Just to make it less confusing: We don’t actually use mouse on smartphones of course so you can use MOUSE_ events to handle only a single touch on specific object. In case you want to handle multi touch then you should use TOUCHES_ events because they will provide you with more information about current touch id and all available touches on the screen.

Here is a quick example of an event and function it calls. Let’s suppose we already loaded bitmap ball.

-- function that will be called every time event is dispatched
function rotateBall(event)
 --some code to rotate the ball
end
-- we attach event to ball's addEventListener
ball:addEventListener(Event.ENTER_FRAME, rotateBall)

So basically what this means is we attached addEventListener to our ball object and what it will do is it will call function rotateBall on every frame change. If we would have Event.MOUSE_DOWN instead then rotateBall function would be called every time we press/touch the ball.

At the end of this tutorial we will have a rotating ball that will randomly change direction, rotation speed and play a sound every time you press it.  In next tutorial (tutorial 6) we will add some events that will make the ball dragable and the effects of picking up and dropping the it.

Ok, enough of theory, let’s build an app (with graphics and sound effects). Create project “Events” and add main.lua.

Note: So far we put all the files in one folder but as the app grows larger it is better to be organized. So we will put graphics in gfx  folder and sounds in snd  folder. I prepared a file for you so download it and extract it to your project folder. Important: Gideros project folder  structure is independent of your OS folder structure so you will have to create folder in Gideros by yourself and add existing files there. In theory this means that you might have all the files in one folder on disk but in Gideros they are nicely structured – or the opposite of course!

Add this code to main.lua :

-- you can apply some settings to your entire application
application:setKeepAwake(true) 
application:setScaleMode("letterbox") --proper "full screen" scaling for most devices

-- global direction variable,rotate clockwise 3
direction = 3

-- load the textures and create bitmap objects
--2nd texture parameter can be set to true to get anti-aliasing
local field = Bitmap.new(Texture.new("gfx/field.png",true))
local ball = Bitmap.new(Texture.new("gfx/ball5.png",true))

-- load sound that will be played when we press on ball
local soundJump = Sound.new("snd/jump.mp3")

-- set the anchor point in the center of ball it rotates around center
ball:setPosition(120,150)
ball:setAnchorPoint(0.5,0.5)

-- function changeBallDirection - executed every frame
function rotateBall(event)
	ball:setRotation(ball:getRotation()+direction)
end

-- function changeBallDirection - executed every mouse press
-- it is not actualy mouse, it means no multi touch
function changeBallDirection(event)
		soundJump:play()
		direction = math.random(-20,20) --random rotation speed(left or right)
end

-- rotateBall function will be called on every frame change
ball:addEventListener(Event.ENTER_FRAME, rotateBall)
-- when we click on the ball it will (or not) change direction
ball:addEventListener(Event.MOUSE_DOWN, changeBallDirection)
-- when we move the mouse then ball also moves

stage:addChild(field)
stage:addChild(ball)

Run it and you will have a nice rotating ball on the field. Now press the ball and it will randomly change the rotation direction and speed, not to mention it will play a sound every time you press it. If you do it long enough you might even make the ball stop rotating (speed=0) 😉

But what a minute – the ball changes rotation/speed even if we click anywhere on the screen! That is not very useful. No worries though, it is easy to fix this,we just need to wrap the reaction between 2 lines. Replace the changeBallDirection function with this:

function changeBallDirection(event)
	if ball:hitTestPoint(event.x, event.y) then
		soundJump:play()
		direction = math.random(-20,20) --random rotation speed(left or right)
	end
end

So we just wrapped the code with hitTestPoint function (lines 2 and 5). This hitTestPoint function simply checks if the given coordinates are in bounds of the sprite/object. Run it and now it only works if you “click” on the ball.

I don’t want to make this tutorial too long and hard to comprehend so we will add some additional events in the next tutorial.