How to place a text string in a given rectangle on the page? [SetTextMatrix()/SetTransform()]

Q:

A quick question about positioning the text. I believe that I should
be using SetTextMatrix(a, b.....) to set the positioning of the text,
but definitely don't understand the matrix. From the OCR I basically
get a positioning of the rectangle of the word.

How would I take that and create it into a Matrix?
---

A:
If you know the positioning information as a rectangle on the page you
can create text matrix as follows:

element.SetTextMatrix(rect.Width(), 0, 0, rect.Height(), rect.x1,
rect.y1);

where (rect.x1, rect.y1) is the lower-left coordinate of the
positioning rectangle and rect.Width()/Height() are the dimensaions of
the element bounding box.

Please keep in mind that in this case you should keep font size to 1
(otherwise the dimensions of the text box will be multiplied by font
size):

Element element = eb.CreateTextBegin(font, 1);
element.SetTextMatrix(rect.Width(), 0, 0, rect.Height(), rect.x1,
rect.y1);
...

Actually the dimensions (and positioning) of text (and other graphics
can be also influnced) by CTM (current transformation matrix)
element.GetGState().SetTransform(), but as long as you keep this
transform as idenity you don't need to worry about this. To place an
image in the given 'rect' you could do the following:

// assuming C#
element = eb.CreateImage(img, new Matrix2D(rect.Width(), 0, 0,
rect.Height(), rect.x1, rect.y1));
writer.WritePlacedElement(element);

this is equivalent to:

writer.WriteElement(eb.CreateGroupBegin()); // Save the graphics state
element = eb.CreateImage(img, new Matrix2D());
element.GetGState().SetTransform(rect.Width(), 0, 0, rect.Height(),
rect.x1, rect.y1);
writer.WriteElement(eb.CreateGroupEnd()); // Restore the graphics
state

for more information about Matrix2D, please see:
  http://www.pdftron.com/net/html/classpdftron_1_1Common_1_1Matrix2D.html