Frames
Introduction
PTC Arbortext Layout Developer frames are rectangular two-dimensional boxes that can hold content. PTC Arbortext Layout Developer frames can contain three types of content concurrently — a text stream, a raster graphic, and an object graphic. Adding content to a frame on a page is the only way of outputting that content to a page. Some PTC Arbortext Layout Developer processes, for example footnotes, create their own frames to output content.
There are two ways to define frames in PTC Arbortext Layout Developer:
• Anonymous frames appear on a single layer — they are only visible in the code for the layer in which they appear.
• Named frames can be shared between multiple layers. They exist as a tag in PTC Arbortext Layout Developer documents. Named frames were added in Version 10.0 of PTC Arbortext Layout Developer.
The fFrame object represents both anonymous and named frames in the Formatting Object Model.
This topic concentrates on working with named frames. Be aware that anonymous frames may exist as they are not always visible.
Creating Frames
In the PTC Arbortext Layout Developer— Desktop product, frames are created by drawing a rectangle with the New Frame cursor. Activate the cursor using the > menu option. Once the frame is drawn, it can be manipulated manually to achieve the desired look and behavior. By default this method creates an anonymous frame on the current page’s main layer. This anonymous frame can then be turned into a named frame using the tfmk >”frameName” macro, where frameName is the name of the named frame.
In JavaScript, frames are created through the fundamental fContent object using a createFrame() method. The name of the frame is a required parameter of the method. This creates a named frame tag of type .fr in the PTC Arbortext Layout Developer document. The fFrame object represents the frame. The frame is listed in the fContent.frames array.
Using JavaScript, it is possible to create frames on demand using inline commands. This allows them to be used for many purposes, such as graphic holders and floating items.
|
|
Care should be taken when creating frames using inline commands, as it is possible to force PTC Arbortext Layout Developer into an infinite loop.
|
To create a frame using JavaScript, use the following:
var f = template.content.createFrame("myFrame");
Where myFrame is the name of the frame to be created.
It may be safer to test for the frame’s presence in the template first, by using:
var f;
f = template.content.getFrame("myFrame");
if (!f) {
f = template.content.createFrame("myFrame");
}
To create an anonymous frame, use the fLayer.addFrame() method. This creates a frame that is specific to that layer and returns the fFrame object for you to update and set its properties. For example:
var layer = formatting.currentPage.mainLayer;
var frame = layer.addFrame();
frame.height = "60mm";
frame.width = "30mm";
frame.x = "10mm";
frame.y = "5mm";
Frame Properties
The only required properties for a frame are its size and its position on a page. Dimensions and positions in PTC Arbortext Layout Developer are always absolute. They can be measured in any of the units that PTC Arbortext Layout Developer can handle. The position is marked from the top left corner of the page and is measured to the top left corner of the frame. The top left corner is also the origin when rotating frames.
As frames are content holders, the content they hold is a property of the frame. Content is not a required property, for example a frame can hold a color block for a page. Frames can hold three types of content:
• Text content (fFrame.text property) can be any text stream in the document. Text content can be either flow or be repeated (fFrame.repeatText property). Repeating text starts formatting at the top of the text stream each time the frame appears in the document. Flowing text starts at the top of the text stream the first time the frame appears, and continues in each subsequent appearance of that frame. Flowing text is used for the main content stream of a document. It is the default behavior for text in a frame. Repeating text is used for headers and footers.
The text in a frame by default fills a single column. Frames can have columns and margins applied to the text. In Arbortext Styler, columns and margins are applied at the block level. Frame text margins are applied separately to each edge of the frame and push content inwards from the edge. Negative margins are permitted. Frames can have up to 20 columns, which can be any combination of widths and can have any column gutters of any width. Text flows from the left to the right columns by default, but Arabic mode is also an option.
• Raster graphics (fFrame.raster property) can be any raster tag (.rg) in the document, whether it is linked or loaded. Raster graphics appear behind any text and object graphic content applied to the frame. Raster graphics applied to frames can be scaled. They can also have their origin position in the frame moved from the top left corner of the frame and have margins applied.
Refer to
Graphics for further information.
• Object graphic content (fFrame.graphic property) appears on top of all other content in the frame. Object graphics cannot be scaled.
Frames can have a number of background and rule properties applied to them:
• Rule properties
◦ A frame can hold up to 20 separate rules in the fFrame.rules array in JavaScript.
◦ A single frame rule can be applied to the top, bottom, left, and right edges of the frame, or any combination of these.
◦ The frame rule can take any of the properties available to an PTC Arbortext Layout Developer rule, including thickness, color, and pattern.
See Rules for further information.
◦ Frame rules build inwards into the frame, but do not displace the text or graphical content. With a negative thickness value, rules build outwards instead. Using rules of no color and negative thickness is a useful way of realigning rules.
◦ Frame rules can also take a radius, which is applied to corners when two adjacent edges meet. With a radius, the frame has rounded corners.
◦ Rules are added to frames using code such as the following:
var f = template.content.getFrame("myFrame");
var r = new fRule;
r.thickness = "1pt";
r.sides = fRule.SIDE_BOX;
r.lineStyle = fRuleLine.LINE_SOLID;
r.lineColor = "green";
f.rules.addRule(r);
Where the addRule() method of the fRules object is used to add the rule to the array of rules held by the frame.
◦ Frames can also specify a column gutter rule (fFrame.gutterRule property). As with other rules, column gutter rules can take any rule property including color, thickness, and pattern. They can also be set to appear only when there is content in the frame. With this setting rules terminate at the end of the content, even if that is before the bottom of the frame.
• Background properties
◦ Frame background (fFrame.backgroundColor property) covers the entire frame’s background and can be any color recognized by PTC Arbortext Layout Developer. If a frame has a rule with rounded corners, it is advisable to use the rule’s fill color as the background color. The color keeps within the shape drawn by the rule. The frame’s background color applies to the rectangle described by the frame’s height and width.
◦ The column background color (fFrame.columnColor property) covers the areas defined by the frame’s columns and can be any color recognized by PTC Arbortext Layout Developer.
• Rotation properties
◦ PTC Arbortext Layout Developer frames can be rotated to any angle specified in degrees (fFrame.rotation property). Positive values rotate the frame in a clockwise direction about the frame’s origin, the top left corner. Negative values rotate it in an anti-clockwise direction.
Frame have other useful properties. Some of these are exposed through Arbortext Styler:
• As with layers, frames can also be stacked on top of each other, both on a page and on the same layer. The stacking order is important as it impacts any avoid settings and the passing of information between frames.
• Frames can carry an avoid property (fFrame.avoid). When the property is activated, content in frames below the current frame avoids its area. Content can flow around frames, ensuring that overlapping frames do not hide content.
• When using avoid, it possible to specify an amount of space around the frame that should also be avoided. Use gap settings applied to the top, bottom, left, and right frame edges (fFrame.gapTop, fFrame.gapBottom, fFrame.gapLeft, and fFrame.gapRight properties).
• By default, frames that extend over the edge of a page are cut off at that point. The page clip property of a frame (fFrame.clipToPage) allows that frame to be drawn with its content bleeding off the edge of the page.
Advanced Frame Functionality
PTC Arbortext Layout Developer also provides some advanced frame capabilities:
• Copy fit allows frames, or their content, to be scaled to fit the available measure. When scaling the frame, you can select which edge to move and the amount by which to move it. The frame automatically resizes to fit the amount of content it contains. Copy fit settings for frames can also change content properties so that the content scales to fit the frame.
• PTC Arbortext Layout Developer can print individual frames from a page to any of its printer drivers.
• Cutting guides can be applied to frames. This is useful if a page contains information placed away from the main content area, but you want to mark the content area with cutting guides.
• Frame anchoring is PTC Arbortext Layout Developer’s mechanism to float content and anchor it to points in the text. With frame anchoring, each frame is created before formatting and assigned content and an anchor name. An anchor control stream describes the placement locations of the frames under specified conditions. During formatting, the anchor location reference calls a particular named frame with a condition name. PTC Arbortext Layout Developer’s formatting process places the frame accordingly. The anchor control stream’s conditions can allow the formatting process to try one location after another to ensure frames are placed well.
