ArborX

<?frame>

Longname: frame   Open the Documentation Legend
Released: 7.67a 
Created: 7.67a 
See also: <?page> clear default width height kill add-to-page raw position size text text-margins page-kill event pageoffset end-of pb (n/a) after-page resize update ttmaptab (n/a) select setcols

Summary
 Using the frame command, frames can be created inline during a format. Similar to footnotes and anchors, these inline frames are removed at the beginning of the format and are regenerated. This command is used in conjunction with a multitude of keywords and raw verbs.
Example extract

This sample when placed inline and formatted will create a frame of 80 x 30mm positioned at 50mm down 70mm accross with the frame name "Simple_1".

 <?frame clear> 1
 <?frame size 80mm, 30mm> 2
 <?frame position 50mm, 70mm> 3
 <?frame raw name "Simple_1"> 4
 <?frame add-to-page> 5
4
Always clear any preexisting frame properties that may be in memory, otherwise they could get applied to the frame that you are creating.
6
The size of your frame.
8
The position of your frame.
10
Give the frame a name. This is because frames are always referred to by name if they require modification (the frame number is never used). This is also useful because of the way auto frames are handled internally - the name is required to uniquely identify a frame. This is particularly important for the autocopy feature, and for killing frames.
12
Always add to page (this actually adds the frame to the page).

Syntax (7.67a)
<?frame  keyw_param:keyw+ >
keyw_param:keyw One of the many frame verbs, raw verbs and applicable parameters. See the associated commands for details.

The inline frame verbs can be used in any order, although <?frame clear> must always start a new frame and <?frame add-to-page> must be at the end.

Auto frame/page parameters must always be placed consecutively without any other commands, like footnotes or anchors, in between, or the successful result cannot be guaranteed.
In-Depth

Contents

Getvars

Error Messages

Warning Messages

Using autoframes

Creating a document from the preformat stream

Creating layers

Creating layers to add later

Creating Autoframes

Resizing pages and frames

Errors and warnings

Formatting Autoframes on frozen pages

Preventing duplicate autoframes

Getvars

Attributes of the most recently created auto frame, can be accessed by getvar 01693, for example:
 getvar 24550(^01693) "left","top","width","height"

Within a script.
 <?show $21550(^01693)v>

or as a showstring

Error Messages

The following error messages are displayed in the format log.They indicate a page or frame which could not be created.
 Pg 2 Could not place frame : Pos x, y Size w, h Pg 2 Frame Position "margin left, margin top" - the auto frame could not be placed - the requested position was already occupied, the frame was too big to ¢t at the position specified etc. 1
 Pg 1 Page layer has no name - cannot create page - a page layers i.e. overlay, underlay, pasteboards must have a name to be created Pg 4 Page name "overlay_name" already in use - cannot create page - name already exists for another tag. If this action were allowed, it would overwrite the existing tag. 2

Warning Messages

The following warning messages are displayed in the format log, although the frame had been successfully created.
 Pg 2 Auto Frame 2 Pos x, y Size w, h overlaps frame 3 with overlap lock - auto frame overlaps a frame with overlap lock Pg 1 Auto Frame 3 not placed in initial position - the positioning offered a range of possible positions for the frame, and as it could not be placed at the initial position, further positions were tried until the frame could be placed. 1
 Pg 2 Auto commands moved onto next page - the placement of an auto frame caused the command to be pushed onto the next page. 2
 Pg 2 Auto frame contains no text or graphics - the frame contains no text stream or raster/object graphics. 3
 Pg 1 Warning - frame out of bounds: Pos 0mm,271.6mm Size 246.2mm,25mm - the placement of the frame exceeds the page boundaries. 4

Using autoframes

Creating a document from the preformat stream

You need to first create a 'base' page on which to place any frames, underlays, overlays.This can be as simple as <?page clear><?page insert> and is the same as the tpins macro.

Creating layers

The tplay macro can create an overlay/underlay and add it to a range of pages. To do this with auto pages requires three steps:

First you need to create the layer:
 <?page clear> 1
 <?page name "under_lay"> 2
 <?page raw underlay> 3
 <?page create> 4
A page layer must always have a name.

Second, add any frames to the page:
 <?frame clear> 1
 <?frame raw frame 0,0,210,297> 2
 <?frame raw text "strm0", 0, 0, 0, 0> 3
 <?frame raw name "mainframe"> 4
 <?frame add-to-page> 5

Here it is not necessary to do <?page clear> before defining the frame because it is being added to the page which has just been created.
It should also be noted that autoframes on autopage layers cannot be addressed later with <?frame ...> commands. For this reason if layers are used and a frame on a layer needs to change, then the layer must be removed and replaced with another one containing the changed frame.

Finally, add the layer to the 'base' page:
 <?page apply "under_lay",1,1,0>

The default, without a range of pages given, will put the layer on the current page.

Creating layers to add later

Page layers can be created at any point in the document, and only used at a later stage. When the layer needs to be used it can be added by using :
 <?page add-layer "under_lay">

To remove an autopage layer at any point :
 <?page remove-layer "under_lay">

Creating Autoframes

<?frame clear> must always be done at the start of each new frame. Autoframes must always have a name, in order to address them again later. If ?frame raw frame l,t,r,b is used to specify the frame's position and size, this must be done immediately after <?frame clear> as it reinitialises all other frame attributes.

A good way to discover which 'raw' verbs are needed to enable certain properties, is to copy a selected frame to an internal 'file' with tp:tcopy "{0}before", make changes to the frame, copy it again with tp:tcopy "{0}after" and then compare the "before" and "after" streams.This will also show how the parameters of each verb are used. Autoframes, like footntotes, are deleted when a page is formatted, except if the page is frozen and the autoframe contains a cut/frozen text stream.To find out if a frame is an autoframe, do the above, and look if the frame has an attribute $auto 1.

When a document is saved, the information about which autoframes exist at the start and end of a page is written to the fdf section of the .3d file. This information can be extracted with the tputfdf (n/a) macro.

Resizing pages and frames

If you change the size of a frame at the beginning of a page, and that page contains frames which have size or positioning relative to the frame which has changed, then if that frame's size/position is wrong after formatting the page you will have to do <?frame update> after changing the size of the frame.This re-adjusts the internal layout of the page to the new frame size. e.g.:
 <?frame resize "frame_name" w,h,l,t> 1
 <?frame update> 2

Errors and warnings

Various error and warning messages are output in the format log, so if something is not working correctly, try turning the format log on to display any messages.

Formatting Autoframes on frozen pages

A new document preference for version 9 under Format Control selects the action to take place if the contents of a cut/frozen auto stream change when autoframes on a frozen page are formatted.

— Do not recreate the auto stream and give a warning in the format log
During formatting:

8 If the auto stream does not change, then the autoframe is not recreated either, (as it is still on the page), and the old frame and stream are left as they are. The new stream (atx1_strm_1__FR) is deleted.

10 If the stream does change, the new document preference is applied:

— the old frame still on the page is removed, and the new frame added (but if the stream does change, any subsequent frozen pages containing the rest of the stream will not change, but the changes to the page where the streamwas created will indicate that the following pages will change.)

Preventing duplicate autoframes

It is highly recommended that autoframe commands are NOT used in 3B2’s "fstart" loop, as you may end upwith duplicate autoframes around a page break. Thismeans you should, as a general rule, use the <?> (or <?=>..<?=0>) command before your autoframe commands. An alternative approach would be to use the <?queue> command to queue up your autoframe commands until the first printable character.

For further information on inline pages and frames, please see Technote 0057; Inline Pages and Frames; 7.67a for further details.

Document created on 08-Feb-2003 (revision 1)