# Tutorial:Using Input

Capturing input events with LÖVE is really easy; in this tutorial we'll cover how to capture keyboard and mouse events using both object methods and callbacks. We'll start our tutorial by putting together an almost empty LÖVE program:

    local text

    function love.load()
       love.graphics.setNewFont(12)
       text = "Nothing yet"
    end

    function love.update(dt)

    end

    function love.draw()
       love.graphics.print( text, 330, 300 )
    end

## Capturing keyboard events

The easiest way to know if the user is pressing a key is calling the `love.keyboard.isDown` method, which has the following syntax:

    love.keyboard.isDown( key )

The key parameter is a string representing the key we want to see if it's currently pressed. A simple example:

    if love.keyboard.isDown( " " ) then
       text = "The SPACE key is held down!"
    end

You can find the complete list of keys here. The best place to perform this check is inside the `love.update` callback: that way we're able to get input from the user and update our variables before drawing our stuff into the screen. So, our modified `love.update` callback should look like this:

    function love.update(dt)
       if love.keyboard.isDown( " " ) then
          text = "The SPACE key is held down!"
       end
    end

While this is fine and dandy if we only need to know which key or keys are currently pressed, we might also need to specify different behaviors when a certain key is pressed and/or released. An elegant way of doing this is using the keyboard callbacks `love.keypressed` and `love.keyreleased`. They work in a similar way of the already known `love.update` or `love.draw` callbacks, executing our code every time that event is triggered. For example:

    function love.keypressed( key )
       if key == "return" then
          text = "RETURN has been pressed!"
       end
    end

    function love.keyreleased( key )
       if key == "return" then
          text = "RETURN has been released!"
       end
    end

As you can see, these two callbacks will provide you a key variable which you can use to check if a given key has been pressed, released or both. Up to this point, our source file should look like this:

    function love.load()
        love.graphics.setFont(12)
        text = "Nothing yet"
    end

    function love.update(dt)
       if love.keyboard.isDown( " " ) then
          text = "The SPACE key is held down!"
       end
    end

    function love.draw()
          love.graphics.print( text, 330, 300 )
    end

    function love.keypressed( key )
       if key == "return" then
          text = "RETURN is being pressed!"
       end
    end

    function love.keyreleased( key )
       if key == "return" then
          text = "RETURN has been released!"
       end
    end

## Capturing mouse events

So, we already know how to interact with our users through a keyboard. But what about that little rodent that sits on their desks? Well, mouse input works in a fairly similar way: we have a `love.mouse.isDown` method and the `love.mousepressed` and `love.mousereleased` callbacks. Let's add a few lines to our `love.update` callback:

    if love.mouse.isDown("r") then
       text = "Right mouse button has been pressed"
    end

As you can see, it's very similar to the `love.keyboard.isDown` and, again, you can see the full list of mouse-related parameters here. You can even check if the mouse wheel has been rolled up or down using this method. We also have two handy methods to know the current position of the mouse pointer inside our game window: `love.mouse.getX` and `love.mouse.getY`. Each one will return the current coordinate of the mouse pointer. Let's see an example by adding these line to the beginning of our `love.update` callback:

    mouse_x = love.mouse.getX()
    mouse_y = love.mouse.getY()

And this line to our `love.draw` callback:

    love.graphics.print( "Mouse X: ".. mouse_x .. " Mouse Y: " .. mouse_y, 10, 20 )

The `love.mousepressed` and `love.mousereleased` callbacks work in a very similar way as their keyboard counterparts:

    function love.mousepressed(x, y, button)
       if button == 'l' then
          text = "Left mouse button has been pressed"
       end
    end

    function love.mousereleased(x, y, button)
       if button == 'l' then
          text = "Left mouse button has been released"
       end
    end

A cool feature of this callback is that you can know not only if a button has been pressed but also the position of the mouse pointer when the user pressed the button. This can be really useful if you need to put together some basic user interface elements like buttons or other objects that can interact with the mouse. A simple example:

    function love.mousepressed(x, y, button)
       if button == 'l' then
          text = "Left mouse button has been pressed at X:"..x.." Y: "..y
       end
    end

Finally, we have another two useful mouse-related methods: `love.mouse.setVisible` and `love.mouse.isVisible`. The first one will let you hide or show the mouse pointer and the second one will obviously let you know if the mouse pointer is visible or not. Let's add even more code to our `love.keypressed` callback:

    if key == 'h' then
       if love.mouse.isVisible() then
          love.mouse.setVisible(false)
       else
          love.mouse.setVisible(true)
       end
       -- OR:
       -- love.mouse.setVisible(not love.mouse.isVisible())
    end

In these few lines we check if the mouse pointer is visible or not and then we change its visibility: if it's visible we hide it and if it's already hidden we then show it. Fairly easy, isn't it?

##

Category:

- Tutorials