Graphics 2.0: Migrating from Graphics 1.0 to 2.0

Updated: 2013.11.18

Overview

This guide explains the changes required to modify existing Graphics 1.0 code to handle some behavioral changes introduced in Graphics 2.0. By migrating your projects, you'll be able to take advantage of all the new graphics features which are not actively supported in Graphics 1.0 Compatibility Mode.

Guides for the new Graphics 2.0 features are available in Corona University. For a list of tutorials, see the Graphics 2.0 Tutorial Roundup.

Display Objects

The following are behavioral changes to Graphics 2.0 APIs:

Constructors

In Graphics 1.0, display object constructors had a top/left parameter. These have been reinterpreted as x and y values that specify the object's center point. The original behavior of interpreting the x and y parameter as top/left is available if using V1 Compatibility Mode. You can see the difference by comparing the HelloWorld_v1 and HelloWorld_v2 samples.

Reference points → Anchor Points

The following methods and properties have been removed:

  • setReferencePoint
  • xReference
  • yReference
  • xOrigin
  • yOrigin

These have been replaced by anchor points, set via object.anchorX and object.anchorY. Anchors have some behavioral differences — see Understanding Transforms and Anchors for details.

Note that groups do not have anchor points. All operations are based around the group's fixed origin point.

Color Definition

For properties like object:setFillColor() and object:setStrokeColor(), RGBA color settings range between 0.0 and 1.0, not between 0 and 255. In addition, APIs that were available in Graphics 1.0 will adopt the new range by default, unless you enable V1 Compatibility Mode.

Also note that object:setTextColor() has been deprecated. You should use object:setFillColor() on text objects instead.

Widgets

This section aims to ease the migration of projects containing widgets.

Widget Alignment

In Graphics 1.0, all widgets were top-left aligned, except for newPickerWheel().

In Graphics 2.0, all widgets are center aligned for consistency. The default anchoring for all widgets is 0.5 for both the x and y coordinates.

TableView

The following changes relate to widget.newTableView():

Widget Positioning

In Graphics 2.0, the x and y properties of the table view refer to the center of the widget. This is a change from Graphics 1.0 in which the x and y properties were aligned to the top left.

Row Positioning

In Graphics 2.0, the x and y position of the rows — when inserting objects into a row via the onRowRender method — will refer to the center of the row.

Example

The following example shows how your Graphics 1.0 code might look, followed by what it should look like in Graphics 2.0:

-- Graphics 1.0
local function onRowRender( event )
    local phase = event.phase
    local row = event.row

    -- We cache the row contentWidth and contentHeight because the row bounds can change as we add children
    local rowHeight = row.contentHeight
    local rowWidth = row.contentWidth

    local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )

    -- Left-align the label
    rowTitle.x = row.x - ( rowWidth * 0.5 ) + ( rowTitle.contentWidth * 0.5 )

    rowTitle.y = rowHeight * 0.5
    rowTitle:setTextColor( 0 )
end

-- Graphics 2.0 (even in V1 Compatibility Mode)
local function onRowRender( event )
    local phase = event.phase
    local row = event.row

    -- We cache the row contentWidth and contentHeight because the row bounds can change as we add children
    local rowHeight = row.contentHeight
    local rowWidth = row.contentWidth

    local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )

    -- Left-align the label
    rowTitle.x = 0
    rowTitle.anchorX = 0

    rowTitle.y = rowHeight * 0.5
    rowTitle:setFillColor( 0 )
end

Removed Libraries and APIs

The following libraries and APIs have been removed in Graphics 2.0 and are not available, even in V1 Compatibility Mode:

sprite library
  • The legacy sprite library has been removed. Use display.newSprite() instead.
  • If you rely on the old sprite library, a legacy sprite module is available here.
  • Update: Particle Candy has been updated to support Corona Graphics 2.0. If your project uses and older version of Particle Candy, you must download and require() this legacy sprite module.

Deprecated APIs

graphics.newGradient()

2.0 Graphics Features

To learn about the new Graphics 2.0 features, please read the guides in Corona University or see the Graphics 2.0 Tutorial Roundup.