22 February 2013

Widget 2.0 is here! Bam!

It’s here! We rewrote Corona’s widget library from the ground up and it’s now available in Daily Build 1034.

IMPORTANT: Please refer to the updated documentation that accompanies each Daily Build. Several things have changed or have been renamed, so you should study it carefully. To assist you, we have included a Migration Guide, also bundled with the documentation in the applicable Daily Builds.

(Side note: There was a little snafu with the 1034’s Daily Build API docs. It’s now fixed!)

Features and Improvements

The most important thing we did was decide to start from scratch, which was critical in building a stable, rock-solid foundation. As a result, Widget 2.0 will be easier to extend and much more maintainable. (More on the woes of the 1.0 code, and a surprise, at the end.)

One of the major changes was integrating the notion of image sheets. The old widget library didn’t fully embrace image sheets, so in order to create a theme, you’d have to have a bunch of individual image files. It was a mess!

With the new widget library, we’ve fully embraced image sheets. Widget themes are now constructed with imageSheets to conserve texture memory and disk space.

In addition, we decided to ship an iOS theme and an Android theme. That means you no longer have to copy over extra widget asset files into your project. We always felt that was a little clumsy, especially when you realize that the widget framework was incomplete without those image assets. Now when you build for iOS, we pre-bake in the iOS image assets. And similarly, for Android.

We also added a ton of other features. Here are several examples to give you an idea of how much TLC we put into this:

• Ability to create a 9-slice widget button.
• Vertical sliders can now also be created, along with the previous horizontal sliders.
• Widget buttons can now have their labels aligned to one of three constants via the new “labelAlign” property.
• Vastly improved widget documentation.
• Unified API naming conventions across the board.
• Ability to be able to graphically theme a tab bar, (previously only gradients were supported).
• Built-in ability to disable a widget button from receiving touch events, which is useful for login screens etc.
• Built-in ability to insert widget buttons into a scrollView.

Bugs fixed

The code re-architecting of widgets allowed us to address a huge number of bugs:

• 18143: Corona Docs Feedback – Add visuals, especially for widgets and UI items.
• 18217: widget.newTableView category rolls do not scroll off the top of the form with the rows.
• 18496: Missing widget documentation for switches, etc.
• 18503: widget.newProgressView does not have correct referencePoint.
• 18505: widget.newProgressView default value cannot reached or measured.
• 18528: Segmented Control missing from the docs.
• 18537: widget.newStepper() reference point is incorrect.
• 18538: widget.newStepper() behaves strangely if moved after creation.
• 18975: widget.newButton’s inside a scrollView widget, the events malfunction.
• 19004, 19030: widget.newTableView() – hideBackground incorrect description.
• 20003: On-Off switch widget fails on double-taps if onRelease method removes the switch.
• 20341: Incorrect widget.newSpinner() imageSheet documentation.
• 20462: widget.newTableView() documentation referencing depreciated APIs.
• 20601: widget.newProgressView() is not documented.
• 16094: widget.tableView:scrollToY / scrollToIndex etc. don’t take in account topPadding
• 12749: widget.newSlider rotates visually, but ignores rotation functionally (we added the ability to * create vertical sliders).
• 19031: Button Widget Bugs.
• 18720: bottomPadding does not work on scrollview widget.
• 20583: “release” and “moved” events not triggered by onEvent in a button in ScrollView.
• 20468: Moved event phase not occurring in objects that are inside a scrollView.
• 18750: ScrollView in Simulator goes way out of bounds.
• 15112: widget.newTableView displayed on top of another widget.newTableView both are getting touch events*.
• 15857: TableView rows dont scroll smoothly / “shake” on borders.
• 18457: Problem on TableView function scrollToIndex on new CoronaSDK.2012.942.
• 18778: Feature request: Scoll-event in tableview widget.
• 19570: widget.tabbar button autospacing adds unnecessary padding.
• 18886: Slider widget doesn’t return event phase.

Migrating from widget 1.0

Now, if you are migrating from widget 1.0, you’ll need to be aware that we made some API changes.

In the latest daily build docs, there is a migration guide linked from the top of the widget library index that tells you how to go about updating your code to take full advantage of widget 2.0.

The short story is you should pay attention to the following APIs:

• widget.newButton()
• widget.newPickerWheel()
• widget.newScrollView()
• widget.newTabBar()
• widget.newTableView()

In the migration guide, we show you side-by-side examples of what the code looked like before and after so that your transition will be as painless as possible.

Known Issues

Of course, no release is perfect. Here are the issues we’re already looking into:

• TableView categories currently don’t push each other on/off screen.
• TableView’s/ScrollView’s are missing scroll bars.
• Grouping of radio buttons.
• Adding the Tab Bar to the default widget themes.
• WidgetDemo doesn’t look quite right on Android-based devices due to bad math related to status bar height.

One more thing…

We realize that some of you may be close to shipping or are unable to deal with the various widget 2.0 API changes. Therefore, we are open sourcing Widget 1.0 code today!

The Corona Widget 1.0 sources are now available on GitHub.

This lets you use the old widget library (even though we think you’re better off using Widget 2.0). Just download ‘widget-v1.lua’ from GitHub and put the following line at the top of each Lua file that’s using widgets:

local widget = require "widget-v1"

To tell you the truth, we look at the Widget 1.0 code and feel embarrassed by it – we even debated whether or not we should release this code to you. However, I felt it was important to get this into your hands for exactly the reason I mentioned above — to minimize disruptions to those of you trying to ship apps.

Now with that said, I also had to appease our engineering team’s sense of pride. So if you go to GitHub, you’ll see the following disclaimer in the ‘Readme’ file:

We should warn you that this code is very spaghetti-like. It’s not clean and is highly unmaintainable. It is really an anti-pattern for any budding framework writer. When you read this code, you should see right away why we struggled so much to maintain the old widget code, and why we ultimately decided to rewrite the widget library.

As I alluded to yesterday, we have been working on a ton of stuff. This is just the first of many “2.0” items that we’re shipping to you!