For those who have been following the development of Corona’s Graphics 2.0 engine, you’ll quickly be introduced to one of the useful new features: anchor points. Anchor points are used to align display objects around a particular relative point within the object’s “bounding box” which can be considered as an imaginary rectangular box traced around the image.

The anchor point of an object controls position, rotation, and transformation.

Let’s consider an analog clock as an example, using this image of the clock’s hand. The overall image size is 412×64:
If you want to rotate this object around the center point, represented by the red ×, it’s clearly not centrally located in the image bounding box. Thus, you must change the anchor point to that location using the anchorX and anchorY properties. For each axis, these values range from 0 to 1, with 0.5 (default) being the center point.

For our clock hand graphic, we need to calculate this value based on the image size. The vertical value of the rotation point is centered, so we can keep the anchorY value at 0.5. On the x axis, we can calculate the anchorX value as follows:

With these two values, our 2.0-compatible code may look like this:

Now, when you run the sample project, you’ll see that the hand spins around its center point as intended.

If you want an image aligned around its top-left point, set both of the anchor points to 0. If you want it aligned around the bottom-right, set both to 1. Also note that anchor points can be specified before or after positioning the object. If specified after, the object will move (shift) in respect to the new anchor point, although this can be overridden by anchoring the children to the group as described in the next section.

Anchor Points and Groups

Generally speaking, groups don’t care about anchor points because they are “unbounded.” In other words, as a group’s children move within it, the group’s bounding box changes to accommodate its new size. However, if you need to align, rotate, or move a group and its children, there is a special property that you must set on the group. This property is named .anchorChildren and it will cause the objects in the group to behave as if they were a single rectangle respecting the anchor point set on the group.

This will cause the group and its children to re-position around its top left point, then rotate -20 degrees as a singular unit.

For display groups in Graphics 2.0, .anchorChildren is false by default.

Groups, being infinite in width and height, don’t have an actual center. Applying the .anchorChildren property and setting it to true causes the group to take on a limited width and height based on the bounding box all of its children. Without this flag, or if it’s set to false, the children will rotate around the group’s origin which, in this case, is the center because the code repositioned the group to be in the center of the screen. The children will now orbit around this center point, similar to the way a planet orbits the sun.

By setting the value to true, we now have a bounding box around the children. That box is then centered and the children now move as if part of a singular unit. This is more like how the Earth rotates on its axis.

It’s best to run this block of code and change the .anchorChildren value from true to false and see how it differs.

Anchor Points and Containers

Containers are another new construct in Graphics 2.0. You can think of them as display groups that have a defined bounding box. All content outside of the container’s bounds is automatically masked (clipped). Containers work like groups in that you use the :insert method to insert display objects into it. Similarly, moving the container moves all of its contents.

Despite the similarities, containers behave differently in some respects, primarily in how children behave. Unlike groups, the default for .anchorChildren is true. Thus, when you move a container, the children inside will move in lock-step with the clipping bounds. In contrast, if you want to move the clipping box without moving the objects inside, set .anchorChildren to false.

From Graphics 1.0 to 2.0

A few other things have changed in Graphics 2.0 in relation to object positioning. Let’s examine these further and learn how Graphics 2.0 behaves differently.

Positioning Inconsistencies

In 1.0, there are some inconsistencies in object positioning upon creation. While most display objects let you pass in position coordinates when creating the object, some do not. More importantly, how these items are positioned is also inconsistent. In the case of some display objects like a display.newRect(), the top-left corner of the rectangle is defined at the position specified in the function call, and the width and height values extend to the right and downward:

With this call, you get a 100×100 pixel box with its top-left corner located at 0,0 on the screen. However, that box’s actual x and y coordinates are 50,50, since the default position is considered at its center.

In Graphics 2.0, object positioning is now consistently based around the center reference point. Thus, to get the same square in the same position as illustrated above, the command is:

Reference Points

In version 1.0, most developers aligned objects using reference point constants based on the most common relative locations around which objects might be aligned:

In Graphics 2.0, reference points have been deprecated. Anchor points must be used in their place unless you decide to use V1 Compatibility Mode.

Version 1.0 Compatibility Mode

We understand that there is a large code base that uses reference points and we want to minimize the impact on you. You can continue to use reference points simply by adding one line to your config.lua file:

This flag also changes most display object constructors to use top-left when creating objects, just like version 1.0. This being said, we encourage you to convert to anchor points instead of reference points.

Default Anchor Point

Because some apps may need to change the default behavior of display objects to return to a top-left type creation, Graphics 2.0 also adds a couple of new functions that let you set the “default anchor point” before items are created. For example:

After this declaration, all new display objects will use the top left as their anchor point (objects created beforehand will remain unaffected). Your code likely exists at a nexus where some of your objects will be perfectly happy with a center anchor point, while other objects will be out of place. Depending on how many need adjusting, you can use these defaults to help reduce the number of edits in your code. For example, if most of your app works with centered objects but you have a scene where you draw several top-left oriented text objects, you can do this:

This will cause those three display.newText() calls to resort to their previous top-left positioning and then, afterward, the default anchor point is reverted back to center.

In Summary

Anchor points are just one of several new features in Graphics 2.0. Hopefully once you use them and see how the relational, flexible alignment can work to your benefit, they will become a staple of your development.

If you’re a Corona Pro or Enterprise subscriber, please download a recent Graphics 2.0 Daily Build and test out the sample project using anchor points.

Source article: 

Tutorial: Anchor Points in Graphics 2.0