Corona’s Widget API was designed to take the time and headache out of designing cross-platform user interface elements from scratch. With just a few lines of code, you can add buttons (that are customizable!), tab bars, sliders, a picker wheel, lists (via tableView widget), and of course, scrolling content with the scrollView widget.
Due to the restraints imposed by small mobile screens (well, smaller than what we’re used to having on desktops and laptops anyway), one of the most common things you’ll see across all platforms is content within a scrollable container. These containers allow the user to access off-screen objects by simply dragging the content in the direction they want it to move. In Corona, you can create these containers using the scrollView widget.
In its most basic form, a scrollView widget can be created by simply specifying a few parameters, creating an external display object, and inserting that object into the scrollView. Here’s an example (if you can’t see the code below, go here to view it):
Let’s take a moment to walk through the code:
- First, you must require-in the widget library.
- Create the scrollView that takes up the full width and height of an iPhone (width/height).
- The scrollWidth/scrollHeight parameters determine how much the scrollView can initially scroll. This will be automatically extended as objects are inserted.
- Create an display object and position it (obj).
- Insert the object into the scrollView as you would any other display group.
And that’s the scrollView widget in its most basic form. If you were to run the above project in the Corona simulator (assuming you have “myobject.png” in your project folder), you’ll see that you’re able to drag the content around (to the distance of scrollWidth and scrollHeight).
If you ever need to explicitly disable horizontal or vertical scrolling, you can set either of the following two properties to false:
NOTE: The use of “scrollView” above should be replaced with the variable name you specified when creating the scrollView widget. Going by our examples so far, it would be “scroller”.
Clipping the Width and Height
Now, what if you don’t want your scrollView to take up the full width and height of the screen? The only way to do so at the moment is by using a bitmap mask. We did try to simplify the process as much as possible though. To use a bitmap mask for the purpose of clipping your scrollView at a specific width and height, simply set the width and height parameters to your desired dimensions, create a corresponding bitmap mask, and then set the maskFile parameter to the filename of your bitmap mask.
To make the process as simple as possible, we’ve published a separate tutorial showing you how to make bitmap mask graphics for the purpose of using them with scrollViews and tableViews. Don’t worry, you’re only working with a white rectangle and a black border, so no artistic skills needed!
Buttons and Touchable Objects
One question that we commonly receive in regards to the scrollView widget is, how do I add buttons and other touch-enabled objects into my scrollView without their touch listeners interfering with scrollView scrolling?
And the answer lies within the takeFocus() method built-in to every scrollView. Here’s how to use it in conjunction with a button widget (if you can’t see the code below, go here to view it):
In the example above, you’ll see that in the “moved” phase of the button’s event listener, we first check to see if the user has dragged the button in any direction at least 5 pixels (fingers that are intended to stay in place usually move around a few pixels, unlike mouse pointers). If the user does in fact move past 5 pixels, then the scrollView’s takeFocus() method is called and the event is instead passed to the scrollView to allow it to drag.
The example above shows how to prevent user experience issues when users intend to scroll the scrollView content but start their touch on a touch-able object. In short, you call the scrollView’s takeFocus() method during the object’s touch listener “moved” phase.
Optionally, you can specify a listener parameter to listen for specific scroll events that are dispatched by the scrollView widget. The parameter is a function (that you define), that will be called everytime a scroll event is dispatched. The event table for each event includes the following properties:
- event.name – This will always be “scrollEvent”.
- event.target – This is a reference to the actual scrollView widget that dispatched the event.
- event.type – This can be “beganScroll”, “endedScroll”, “movingToTopLimit”, “movingToBottomLimit”, “movingToLeftLimit”, or “movingToRightLimit”.
All of the “movingTo…” event types occur when the scrollView goes past one of the limits, just before the content “rubber-bands” back to its boundaries.
Further Reading and Resources
For a complete list of parameters, properties, and methods, please see the updated scrollView widget API documentation.
Or, to see another working example of the scrollView (and other widgets) in action, please take a look at the “WidgetDemo” sample included in the Corona download in the “Interface” folder. In recent Daily Builds, the WidgetDemo has been updated to reflect the new changes and also incorporates the Storyboard API as well.
Remember, many of the features, parameters, and properties described in this tutorial require that you are using the latest daily build, which is available to subscribers only. If you’re serious about using Corona widgets for use in games or non-game apps, subscribe today so you can take advantage of the best version of the widget library right away.