Progress Ring Module for Corona SDK

UPDATE #3 (3/4/2015): Fixed a bug that caused a “completed” event to be triggered upon creating the progress ring. Now “completed” events will only be triggered by ring:goTo() calls made after the ring’s creation. Thanks to Nick for finding this mistake and pointing it out in the comments!

UPDATE #2 (1/23/2015): Fixed a bug that only manifests in Corona SDK build #2015.2544 and later. In build #2015.2544, Corona Labs fixed the finalize() bug that prevented objects’ finalize events from being triggered when their parent display group was removed. I had utilized a brilliant workaround developed by Sergey Lerg, but there was an error in my implementation of his fix that caused a crash when run on build 2015.2544 and later. I fixed that crash by adding a 1ms timer when checking to see if finalize events are being triggered as they should. The fix is not necessary for up-to-date Corona builds, but I’m leaving it in for folks who might be running legacy Corona builds.

UPDATE #1 (1/7/2015): The progressRing module has been updated to ensure that the procedurally-generated mask image reliably meets the requirements for mask images. Previously, it didn’t always work when running on devices whose screen size did not match up with the content width/height defined in an app’s config.lua file.

Something that is occasionally asked about on the Corona Labs forums is how to achieve a circular progress indicator (what I call a “progress ring”). The uses for this type of widget are limitless, but here are a few examples:

• player/enemy health bars in a RTS-style game (see Ravenmark)
• countdown timer to show when a player’s turn is up in a turn-based multiplayer or puzzle game
• a more visually interesting percentage indicator than the usual horizontal or vertical bar (in a business app)

A number of solutions have been proposed in the forums, often involving the use of sprite objects with X number of frames to cycle through depending on the position of the progress bar. These solutions can work, of course, but I set out to create my own progress ring solution with the following goals in mind:

• The movement of the progress ring should be seamless and smooth, regardless of which direction it was moving and/or how quickly (something that can’t happen with sprite-based solutions unless you use a prohibitively high number of frames)
• The progress ring must be created solely with code, so that it can be modularized into a single lua file and added to a project with one line of code (again, something that isn’t possible with sprite-based solutions).
• The progress ring must be visually customizable through code: colors, size, depth of the “donut hole” (or no donut hole at all), stroke width, etc.
• A progress ring object must have simple and easy-to-use methods for controlling it after it’s been created.

And I’m happy to report that I’ve come up with a solution that meets all those requirements and makes it very easy to add a progressRing to any Corona project with just one line of code!

How to Make a Progress Ring

Here’s a simple step-by-step guide to adding a basic progress ring to your Corona app with just one line of code:

1. Download progressRing.lua and place it in your project’s root directory (where you keep main.lua).
2. Require the module into your app by adding this line of code:

local progressRing = require("progressRing")

• Create a progressRing object in your app by adding this line of code:

  local ringObject = progressRing.new()

That’s it! Following those steps will create a very basic progressRing with some default parameters. The returned progress ring is just a Corona display group, so you can easily manipulate its x and y coordinates, rotate it, scale it, add it to other display groups such as a Composer scene group, and get rid of it by calling display.remove() on it. Any method you can call on a Corona display object can be called on your progress ring.

Customizing your Progress Ring

The above steps are the fastest way to add a progress ring to your app, but the returned progress ring will be very minimal. However, it’s very easy to customize the look of your progress ring by passing a single table as an argument when you call progressRing.new(). The table can include any of the following key/value pairs, but none are required:

• radius: a number representing the radius of your ring in pixels. Defaults to 100.
• ringColor: a table containing 4 numbers between 0 and 1, representing the RGBA values of your ring’s bar color. Defaults to {1, 1, 1, 1} (white).
• bgColor: a table containing 4 numbers between 0 and 1, representing the RBGA values of your ring’s background color. Defaults to {0, 0, 0, 1} (black).
• ringDepth: a number between 0 and 1 representing the depth of your ring. A ringDepth of 1 will result in a fully-round ring (“all donut, no hole”), while a ringDepth of 0 would result in an invisible ring (“all hole, no donut”). Defaults to .33.
• strokeColor: a table containing 4 numbers between 0 and 1, representing the RBGA values of your ring’s stroke (border) color. Defaults to whatever your bgColor is.
• strokeWidth: a number representing the width of your ring’s stroke (border) in pixels. Defaults to 0 (no stroke).
• counterclockwise: a boolean (true/false) value indicating whether or not the ring should advance in a counter-clockwise manner. Defaults to false.
• hideBG: a boolean (true/false) value indicating whether or not the background should be visible. Defaults to false.
• time: a number representing the amount of time (in milliseconds) your ring will take to make a full rotation, from 0 to 360 degrees. Defaults to 10000 (10 seconds).
• position: a number between 0 and 1 representing the starting position of your progress bar. 0 would result in no visible progress bar (i.e. 0 degrees). 1 would result in a full progress bar (i.e. 360 degrees). .5 would result in a halfway-full progress bar (i.e. 180 degrees). Defaults to 0.
• bottomImage: a string representing the path to an image file (i.e. “images/bottom.png”) that will appear “underneath” or “behind” your progress ring. Automatically supports dynamic image scaling (@2x, @3x, etc.). Defaults to nil.
• topImage: a string representing the path to an image file (i.e. “images/top.png”) that will appear “on top of” or “in front of” your progress ring. Automatically supports dynamic image scaling (@2x, @3x, etc.). Defaults to nil.

As an example, here is some code that would create a progress ring with a radius of 200 pixels, a red background, a green ring, a ring depth of 33%, and that takes 4 seconds to make a full rotation:

local ringObject = progressRing.new({
     radius = 200,
     bgColor = {1, 0, 0, 1},
     ringColor = {0, 1, 0, 1},
     ringDepth = .33,
     time = 4000,
})

Download the sample project to make adjustments to the available parameters on the fly and see them reflected on-screen in real time.

Let’s Get Moving!

Now that you’ve created your progress ring, you can call several methods in order to make it advance or retreat as needed. Here are the available methods:

• ringObject:goTo(position, [time]) is used to advance/retreat the position of the progress ring. Note:
  1. position (required) is a number between 0 and 1 representing the position the bar should advance or retreat to.
  2. time (optional) is a number representing the amount of time (in milliseconds) it will take for your ring to reach the position you defined. By default, this is determined by the time you set for a full rotation (i.e. if you set a time of 10 seconds for a full 360-degree rotation, and your ring is advancing 180 degrees, it will take 5 seconds). Setting a time of 0 will result in an immediate repositioning of your progress ring.
• ringObject:pause() will pause your progress ring while advancing or retreating.
• ringObject:resume() will resume a paused progress ring.
• ringObject:reset() will return your progress ring to the starting position you defined when creating the object.

A Note About Nested Mask Limits and Snapshots

In general, this module should perform well on any device capable of running a Corona app. However, there are a few things that you may need to take into account when adding a progress ring to your app:

• Each progress ring object utilizes two masks that are created on-the-fly, through code. One is to create the “donut hole” effect, and the other is to mask the movement of the ring “slices” as they appear from a zero position. Corona has a nested masking limit of 3, so take care when inserting your progress ring into other masked objects, such as display containers, to make sure you don’t exceed that limit.
• I wanted to allow my progress rings to have semi-transparent ring colors, but the only way to do that without ugly visible seams when the ring’s “slices” overlap was to utilize Corona’s display.newSnapshot() API. Snapshots do come with a bit of a performance penalty, so you should take that into consideration if you assign an alpha value of less than 1 to your ringColor. Also, keep in mind that the snapshot API is only available for Pro/Enterprise Corona users. (Note: the module only utilizes the snapshot API if you specify an alpha value of less than 1 in your ringColor table, otherwise it uses regular display groups. So if you have a fully-opaque ringColor, these concerns don’t apply.)

Have You Used It?

This module is free to download, free to use, and you are free to modify it to your heart’s content. I hope that you find it useful! But if you do use it in one of your apps, please share a link to your app in the comments, or contact me so I can see how you integrated it into your app. I’d love nothing more than to see to see my code getting used out in the wild. Enjoy!