In CDL documents figures are placed by centering the Anchor reference point to the defined Pin position.

Figure Pin

Whenever a figure is added to a document, its Pin is defined as the (0,0) coordinate. You can also set it at the figure definition:

var figure = Cx.Text({ line: "Phrase"
                     , ... 
                     , pin: Px(100,50) });

Or change it later using the pin property as usual:

figure.pin( Px(100,20) ); // Or directly figure.pin(100,20);

Also we may change the position of a figure with respect to its current position:

figure.translate( offset ); // Or figure.translate( x,y );

This would change the figure’s position in x horizontally and y vertically.

Other operations can also modify the figure’s position, for example rotation around a given pivot point:

figure.rotateAround(pivot,degrees);

Figure Anchor

To be able to place a given figure in the Pin position we need to define a reference point relative to the figure curves. This point is called Anchor in our system and it is an important piece in building well behaved templates that the user can modify.

The following diagram illustrates the relationship between the Anchor and the Pin. We start with a given shape that is defined by a single Region with a closed boundary. The original points in this curve are the ones in the upper-right corner of the document. The green point is the Anchor of the Shape, in this particular case is an Absolute Anchor. This is the point that will be used to center the figure in the Pin position, sketched in the diagram with a red dot.

shape.anchor( Cx.AbsoluteAnchor(pos) );

We use a Relative Anchor to define a good reference point for Texts for example. The reference point will be obtained relative to the bounds of the processed figure (before the final transformation is applied).

text.anchor( Cx.RelativeAnchor(rx,ry) );

The following diagram showcased what happens when the user modify the line of a given Text. The Anchor is defined as Cx.RelativeAnchor(0.5,0.5) in this case. So the center of the bounds is placed at the pin position marked here again as a red dot. The figure accommodates nicely around the Pin.

The Anchor of the figure is an object that defines an absolute and a pos properties.

var anchor = figure.anchor();
if( anchor.absolute() ) {
  var asolutePos = anchor.pos();
  // ...
} 
else {
  var relativePos = anchor.pos();
  // ...
}

Direct positioning

Sometimes, it is useful to avoid the Anchor-Pin model and directly work with the figure bounds. We can use center or align operations to define the pin with respect to other points or objects in the document.

figure.center$(pos); // Or figure.center$(x,y);

The center$ function takes any objects that defines a center (Canvas, bounds, frame or even a list of figures). For example, we can place the figure in the middle of the view with:

figure.center$(canvas); // Center the figure in the middle of Canvas

Read the figures transformations reference to learn about more available alignment operations.