Ripples

Ripples

Ripples are the haptic feedback provided by almost all the elements that expect user interactions, in Material-Design.

The ripple effect is also called Surface Reaction in the Material-Design spec.

Require ripples.lua

The first step for you to use this amazing effect is to require the ripples.lua file inside your project.

local ripple = require "material-love.libs.ripples"

Ripples containers

There are a total of four BASIC types of ripples containers.

Box

The ripple.box is the most basic type of ripple container, it's just a rectangle where ripples can propagate

In order to create a new ripple box just call ripple.box as following:

local box = ripple.box(x, y, w, h, time)

• x, y: The x and y coordinates of the box
• w, h: The width and height of the box
• time: The time it takes for a ripple to fill the container (defaults to 1)

Circle

Since using a box is not suitable for buttons such as the FAB button ripple.circle exists. It is the same as ripple.box but the container is a circle instead.

In order to create a new ripple circle just call ripple.circle as following:

local circle = ripple.circle(x, y, r, time)

• x, y: The x and y coordinates of the center of the circle
• r: The radius of the circle
• time: The time it takes for a ripple to fill the container (defaults to 1)

Custom

Since this two don't fit all the needs there is a third one which can be used to generate all types of containers (Actually the first two are based on this third one).

Create a custom container as follows:

local custom = ripple.custom(fn, fr, time)

• fn: A stencil function to use when drawing the ripples, this contains them and doesnt let them overflow
• fr: The final radius at which ripples will grow (for boxes is the diagonal, for circles the radius multiplied by two).
• time: The time it takes for a ripple to the final radius (defaults to 1)

The fourth type

This is COMPLETELY different so will be described in the Stencil section.

Starting Ripples

To start a ripple on a container there are two ways, the first one is using the ripple.start function

ripple.start(container, x,y, r,g,b,a)

The second is using the start method of a container (box, circle, custom,...)

container:start(x,y, r,g,b,a)

Both this functions expect the following arguments

• x,y: The x and y coordinates where the ripple originates
• r,g,b,a: The RGBA values for the color of the ripple

Fading ripples

After a ripple has begun it keeps expanding until completely filling the container, in order to make it disappear you need to call ripple.fade with the container as argument or the fade method of the container.

ripple.fade(container)
container:fade()

Whenever you start a ripple in a container where a ripple already existed, the old ripple is faded out.

Draw and Update

You need to update the container, and draw the ripples to screen

Update

You can use the update method of the container or the ripple.update function with the container as first argument.

love.update = function (dt)
    ripple.update(container,dt)
    container:update(dt) --One or the other, not both, otherwise it would update twice
end

Draw

To draw the ripples there are again two ways of doing it, ripple.draw with the container as first argument and the draw method of the container

love.draw = function ()
    ripple.draw(container)
    container:draw() --One or the other, not both, otherwise it would look darker
end

Stencils

Ripple stencils are the fourth type of ripples, they are different because they are not Surface reaction but instead they are used for the Reveal effect. It is pretty simple, just create a new one with ripple.stencil:

stencil = ripple.stencil(x, y, w, h, time)

You need to specify the area of the thing you want to make appear, that is why you need to provide the x and y coordinates plus the width and the height, the time argument is again the time it takes to expand to the fullest.

Draw

Now you have your area defined, you may want to draw your stuff, to do this you need to call the draw method of the stencil (it is recommended to use the methods and not the ripple.update function).

This method expects a function, that is gonna be drawn inside the stencil, that is it will be displayed only when the reveal effect expands.

love.draw = function ()
    stencil:draw(function ()
        -- Drawing some stuff inside the stencil
        love.graphics.rectangle("fill",x,y,w,h)
        love.graphics.circle("line",x + w/2, y + h/2, math.min(w/2,h/2))
    end)
end

Remember to limit you drawing operations to the area you defined in ripple.stencil or otherwise it will be cut by the circle.

Reveal

To reveal this, you need to call the start method of the stencil, with and x and y coordinate of where the reveal should origin.

stencil:start(x,y)

You can also pass true as a third argument to make it collapse to that point, but if no ripple had revealed the content, it will all appear without the reveal effect, which would look wrong in most cases.

Collapse

As said before the collapse is the way to hide content, if you want to collapse something to the center, use the fade method of the stencil, it is not actually fading but a collapsing ripple that will go to the center of the defined area.

Update

Remember to update the stencil with the update method, and pass dt as an argument.

love.update = function (dt)
    stencil:update(dt)
end

Files

You only need libs/ripples.lua