Coming in the next daily build (2011.645—should be up around 2am on the 25th of October), is a MAJOR update to the widget library.
The documentation pages have already been updated to reflect the changes, and I recommend viewing the list of "Known Issues" and "Recent Changes" to become familiar with this update.
http://developer.anscamobile.com/content/widget
Here are the main changes:
tableViews and scrollViews
These have been completely redesigned for stability and flexibility. Those who had problems with the tableViews before should immediately notice that there is no more losing rows, no more strange issues with category items, and now, you are completely free to decide WHAT goes in each row.
Each row, to include category items, are just another display group. You'll decide what goes into each row by specifying an 'onRender' listener for each row and inserting objects into the listener's event.view property. This means there's a little more "setup" involved when it comes to creating tableViews, but you are now given a tremendous amount of flexibility that was not possible before.
During testing, we've noticed that on older devices (which include 2nd generation iPod touches and older), tableViews with 500+ rows (or just a huge amount) do tend to stutter and cause some problems. It's not very user-friendly to have that many rows in a tableView anyway, so we recommend splitting up your lists by having a 'Load 25 More' row as the last item.
While the scrollView hasn't changed all that much, the parameters have been made to be more consistent with the tableView (as well as the other widgets), and an unfortunate side effect to all the refinements of this update is the absence of scrollBars (same goes for tableViews). Please be patient as we're working on restoring these in a future update. Until then, please enjoy the enhanced stability and flexibility these widgets now provide.
pickerWheel
Since the pickerWheel actually relies heavily on the tableView widget, we had to revamp this widget as well. You'll notice there's more customization options and no more limit to how many rows you can have. We've also added an "alignment" and "startIndex" property to each column.
Currently, there are two known issues that we're working on addressing in a future update. The first one is the fact that rows do not soft-land on specific items (as they do with the native iOS pickerWheel). The selected item will be whatever is in the selection area, whether it is centered or not.
The second known issue is that if you change the 'y' value of the pickerWheel (such as with a transition.to, to slide the pickerWheel up), then the 'getValue()' method will stop working. We recommend you instead "fade" the pickerWheel in if you want some kind of animation, as you cannot move the pickerWheel once it has been created without experiencing issues.
tabBar (brand new widget)
This is the much-requested tabBar widget that is brand new to this upcoming version of the widget library. It supports plenty of customization and an unlimited amount of tab buttons.
For iOS users, the default tabBar should look and feel just-right. For other platforms, or apps that need to deviate from the standard look, there are plenty of parameters you can set to get it looking just the way you want.
Here is the API documentation for the new tabBar:
http://developer.anscamobile.com/reference/index/widgetnewtabbar
Widget Themes
Prior to this version, themes were hard-coded into the widget library and relied on updates to provide you with new themes. That is no longer the case.
Now, themes are Lua modules which contain tables (similar to config.lua) that correspond to specific widgets. Since widgets have been made to be more flexible, themes are simply preset parameters for the widget (that you can override on a per-widget basis). Themes will have a folder that also needs to be included in your project folder (along with the Lua module), which will contain the graphical assets that are required for that particular theme.
At the moment, there is only an iOS theme. We are working on an Android theme. You can take the iOS theme and modify it to create your own custom themes to share with others, or to simply have unique-looking widgets for your game or app.
Text
Previously, the widget library modified the display.newText() function, which caused problems with the new multi-line text capabilities.
Now, the widget library no longer touches the display.newText(), and as of build 2011.645, there is now display.newRetinaText() and display.newEmbossedText() to take care of your retina-display and embossed text needs.
Removed Widgets
The segmented control has been removed from the widget library, but has been made open-source for anyone who still wants it:
http://developer.anscamobile.com/code/segmented-control-widget
The tabBar is more cross-platform friendly and serves almost the same purpose as the segmented control, still, the source is available for those who absolutely need/want it.
The toolbar has also been removed, because you can now create an empty tabBar (or just use an image) and place embossed text over it using the display.newEmbossedText() function.
BETA Reminder
Unfortunately, if you were currently using the widget library in your projects and you update to this new version that will come out with build 2011.246, your code will break. This library is still in beta and is subject to changes, but we feel like these changes were necessary to keep moving this library forward, and closer to a more stable condition. Most-likely there will not be anymore changes to this widget library as major as this one, since I believe this update addresses most of the major issues that were present in previous versions.
Please take a moment to look over the documentation, and prepare to migrate your previous widget code to be compatible with this new version—you'll be glad you did :-)
http://developer.anscamobile.com/content/widget
The WidgetDemo in Daily Build 2011.646 has also been completely revamped to take advantage of all these changes, and to further demonstrate basic widget usage.
Matthew Wallace
