Almost a year ago I posted a free module that allows Corona SDK developers to add a finger painting “canvas” to their Corona projects with just one line of code. It seems to have been useful for a number of developers, but in the months since releasing it, opportunities for improvement have presented themselves, and in particular I received one specific feature request that seemed worth addressing. So I dusted off that old module and made some tweaks that resulted in what I’m calling fingerPaint version 1.5.
What’s New In Version 1.5
- I’ve updated the syntax for calling fingerPaint.newCanvas() so that you now pass a single table with specific key/value pairs into the function. This is partly because I find this to be a better way to organize function arguments, but also because it’s in-line with the syntax in my more popular progressRing module (as well as most official Corona SDK APIs). I’ve included backwards compatibility, however, so version 1.5 of the module will play nice with projects that use the older syntax.
- I added a new “how to use this module” section at the top of fingerPaint.lua. That’s something I did for the progressRing module that folks seemed to like, so I’ll be doing that with all my publicly-shared modules moving forward.
- I modified the module so that a paint stroke is only extended if the user’s finger has traveled far enough for it to make a visible difference. Previously, you could occasionally get an erratic line if the user “squiggled” their finger too closely around a single point.
- I added the option to break up a stroke into individual line segments instead of using a single line object and appending new line points. By default this option is disabled, because it can lead to potentially crash-inducing memory usage if left unchecked, as it requires substantially more display objects to keep in system memory. But in certain controlled circumstances this option can be useful — for example, if you want the user to be able to erase only part of an existing paint stroke. I’ve also heard reports that on certain Android devices the default method of appending to a single line object can result in erratic behavior. In those cases, using segmented strokes seems to fix things. To enable this feature, simply add the key/value pair “segmented = true” to the table you pass into fingerPaint.newCanvas().
How To Use The Module
For more information about how the module works and it’s history, you can check out the original post from 2014 – I’m not going to recreate that information here. But below is a step-by-step guide for using the module to add a finger paint canvas to your app, with the updated syntax. This same information is also included in a commented-out section at the top of the module’s lua file.
- Place fingerPaint.lua in your project’s root directory.
- Require the module in your project as such:
local fingerPaint = require("fingerPaint") - Create a finger painting “canvas” object as such:
local canvas = fingerPaint.newCanvas()
You can customize your canvas by including a single table as an argument when calling fingerPaint.newCanvas(). The table can include any of the following key/value pairs (but none are required):
- width: the width of your canvas. Defaults to the full screen width.
- height: the height of your canvas. Defaults to the full screen height.
- strokeWidth: the width of your fingerpainting “strokes,” or the lines that the user draws. Defaults to 10 pixels.
- canvasColor: a table containing 4 numbers between 0 and 1, representing the RBGA values of your canvas’ background color. Defaults to {1, 1, 1, 1} (white). TIP: Set the 4th value to 0 for a canvas with a transparent background.
- paintColor: a table containing 4 numbers between 0 and 1, representing the RBGA values of the “paint” color. Defaults to {0, 0, 0, 1} (black).
- segmented: a boolean (true/false) that, when set to true, results in paint strokes that are comprised of separate line object segments. USE WITH CAUTION: setting this value to true can substantially increase the memory usage of your app. Defaults to false.
- x: the x coordinate where you want your canvas to be placed. Defaults to the horizontal center of the screen.
- y: the y coordinate where you want your canvas to be placed. Defaults to the vertical center of the screen.
- isActive: a boolean (true/false) that disables painting when set to false, and enables painting when set to true. Defaults to true.
- You can adjust the behavior of your finger painting canvas using the following methods:
- canvas:setPaintColor() will change the paint color for all future paint strokes (older paint strokes will be unaffected). You must pass a single table into the function containing 4 numbers between 0 and 1, representing the RBGA values of the new paint color.
- canvas:setCanvasColor() will change the canvas’ background color. You must pass a single table into the function containing 4 numbers between 0 and 1, representing the RBGA values of the new background color. TIP: Set the 4th value to 0 for a canvas with a transparent background.
- canvas:setStrokeWidth() will change the width of future paint strokes (older paint strokes will be unaffected). You must pass a single number into the function, representing the new stroke width.
- canvas:undo() will remove existing paint strokes, in reverse order, one at a time.
- canvas:redo() will restore “undone” paint strokes, in the order in which they were created, one at a time.
- canvas:erase() will remove all paint strokes from the canvas. It cannot be undone.
- canvas.isActive is a boolean (true/false) property of the canvas object that can be changed as needed to enable or disable painting.
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!
1 Trackback