^{Excerpted from my book FrameScript for Newbies  Copyright [7/17/2007] by Paul Schnall}

It is always good to know where you are, this is also true in scripting. Most FrameMaker objects have a text location or text range property. This property tells you the coordinates of the object. Then, these coordinates can be used to place other object relative to this location. For example, if you have the text range of a paragraph, then you can specify a new text location. The new text location can be anywhere within this text range. The text location can be used to add text at that point.

Text Range

Many FrameMaker objects have the property TextRange. This is the place within the document that identifies the location of an object. For example the title may have a Text Range as specified in the figure below. Along with the text range property there are also two other properties;

• the starting point of the object

• the endpoint of the object.

These can be specified using the dot notation

• vPgf.TextRange.Begin
• vPgf.TextRange.End.

Figure 1. TextRange

The TextRange can be obtained using the dot notation. For example:

1) Set vPgf = vCurrentDoc.MainFlowInDoc.FirstPgfInFlow;

2) Set vPgfTextRange = vPgf.TextRange;

Line 2 sets the variable name vPgfTextRange equal to the text range of the first paragraph in the main flow of the document.

The TextRange property specifies the range of a FrameMaker object or the range of a section of text, using the text location at the beginning and the text location at the end of the FrameMaker object or text. The most useful of these objects is the paragraph. The paragraph object has a property TextRange. You can then assign a variable to either the beginning or End of the TextRange by using:

Or

TextLoc

A Text Location can be specified using:

This code sets a variable to the location of the beginning of the paragraph vPgf.

A TextLoc can also specify any position in the paragraph by specifying an offset from the beginning or by specifying the end or an offset back from the end of the TextRange. This offset specifies the number of characters and/or spaces to move forwards or backwards (using a negative number).

Figure 2. New TextLoc using the end of the object with a negative offset.

Figure 3. Adding Text

New TextLoc

This command allows you to specify a location in the document and assign it a variable name. This is useful when you want to insert objects into the document. New TextLoc NewVar(vTextLoc) Object(vPgf) Offset(ObjEndOffset-1);

The command above:

• creates a new text location
• assigns the new location the variable name vTextLoc

It takes the location from the TextRange property of the object vPgf. Offset then counts places from either the beginning or the end of the TextRange. In the example above it counts back one space from the end of the object TextRange. The TextLoc is limited to a single location and cannot be a range.

Variables as their name imply can change. During the course of running the script the variable vPgf may continuously be reassigned. For example in a Loop through the paragraphs the variable vPgf will, with each iteration of the loop, be reassigned to the next paragraph in the document. It is important to understand that the paragraph that is associated with the variable vPgf can change as the script runs. Using If statements can identify which paragraph is assigned the variable vPgf.

In general, when looping through a document the first thing you want to do inside the loop is to put an If statement that will be able to identify the paragraphs you are looking for.

Loop For Each paragraph.

If the paragraph contains the text "Boy, is it cold out!"
The If command returns a value of true or false. If you know the that the if statement is true you can do something with the paragraph at this point. You also know that the variable vPgf is assigned to this particular paragraph. And that vPgf.TextRange.End is the location of the end of this paragraph.

// Add text at the text location.

New Text TextLoc(vTextLoc) ' I wish I had a coat. ';

End the if statement

Continue on looping through the paragraphs of the document.