<?frame>
Description
This command permits the inline creation of frames during a format operation. In a similar way to the treatment for footnotes and anchors, these inline frames are removed at the beginning of the format cycle and are regenerated once it has been completed.
Example 461. Create an inline frame
This sample, when placed inline and formatted, will create a frame of size 80mm x 30mm, at position 50mm down and 70mm across. The frame is named "Simple_1" and uses frame 1 from the default pasteboard.
<?frame clear default 1>
<?frame size 80mm, 30mm>
<?frame position 50mm, 70mm>
<?frame raw name "Simple_1">
<?frame event after-page 2>
<?frame add-to-page>
1. Clear existing frames. Always clear any pre-existing frame properties that may be in memory, otherwise they could get applied to the frame that you are creating.
2. Set the width and height of the frame.
3. Specify the position of your frame.
4. Give the frame a name. This is important since 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.
5. Specify an (optional) start condition.
6. Always include add to page to ensure the frame appears on the page.
Syntax
<?frame keyw_param:keyw+>
|
keyw_param
|
Applicable keywords and flags for the verb:
• add-to-page
• after-page
• auto-height
• clear
• default
• end-of
• event
• height
• ht
• kill
• page-kill
• pageoffset
|
|
|
|
keyw_param (cont...)
|
• pb
• pos
• position
• raw
• resize
• rf-auto
• rf-none
• rf-now
• select
• setcols
• size
• text
|
|
|
|
keyw_param (cont...)
|
• text-flags
• text-margins
• ttignesp
• ttignmsp
• ttignret
• ttignsp
• ttignssp
• ttmapret
• ttmaprety
• ttmaptab
• update
• width
|
Additional Information
Inline frame verbs can be used in any order within the <?frame> syntax, with only two exceptions: <?frame clear> must always start a new frame and <?frame add-to-page> must appear at the end.
|
|
Any auto frame/page parameters must always be placed consecutively, without being split up by other commands such as those for footnotes or anchors. A successful result cannot be guaranteed if this is not the case.
|
Getvars
The attributes of the most recently created auto frame can be accessed by getvar 01693, for example:
• Within a script: getvar 24550(^01693) "left","top","width","height"
• As a showstring: <?show $21550(^01693)v>
Using autoframes
Creating a document from the preformat stream
The first step is to create a 'base' page on which to place any frames, underlays, and 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:
1. Create the layer, ensuring that it has a name or it will not be created:<?page clear> <?page name "under_lay"> <?page raw underlay> <?page create>
2. Add any frames to the page: <?frame clear> <?frame raw frame 0,0,210,297> <?frame raw text "strm0", 0, 0, 0, 0> <?frame raw name "mainframe"> <?frame add-to-page>. It is not necessary to add a <?page clear> command 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.
|
3. Add the layer to the 'base' page:<?page apply "under_lay",1,1,0>. If a range of pages is not specified here the layer will be placed on the current page.
Creating layers to add later
Page layers can be created at any point in the document and, if required, not used until a later point in the document.
To use the autopage layer specified in step 1 above:<?page add-layer "under_lay">
To remove the autopage layer at any point:<?page remove-layer "under_lay">
Creating autoframes
The following points must be borne in mind when creating autoframes:
• The <?frame clear> must be triggered at the start of every new frame.
• Autoframes must always have a name, in order to address them 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 reinitializes all other frame attributes.
To discover which 'raw' verbs are needed to enable certain properties, copy an existing frame to an internal 'file' using the tpcopy macro: tp:tcopy "{0}before", make changes to the frame, copy it again with tp:tcopy "{0}after" and then compare the properties in each of the "before" and "after" streams. This will also show how the parameters of each verb are used.
Autoframes, like footnotes, 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, carry out the same steps as listed above and, during the "compare" phase, verify if the frame contains the 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 macro.
Resizing pages and frames
If you change the size of a frame at the beginning of a page, and that page contains other frames that have size or positioning properties calculated relative to the frame that has changed, if that frame's size/position is wrong after formatting the page you will have to carry out a <?frame update> command after changing the size of the frame. This re-adjusts the internal layout of the page to the new frame size and ensures all frames linked under a relative size property are also updated, e.g.:
<?frame resize "frame_name" w,h,l,t>
<?frame update>
Formatting autoframes on frozen pages
A document preference, accessed under the Format Control tab of the tdpref dialog box, can be set to select the action that should take place if the contents of a cut/frozen auto stream change when autoframes on a frozen page are formatted:
• Create stream, no level pages: Recreate the auto stream, but do not create level pages and give warning in the format log (default)
• Create stream, and possible level pages: Recreate the auto stream and any necessary level pages
• Don't create stream, give warning: Do not recreate the auto stream and give a warning in the format log
In general, auto text streams and frames are processed as follows when either they or the page are frozen:
• Auto generated text streams that are cut/frozen at the top will not be deleted at the start of the format
• Auto frames containing text streams that are cut/frozen will not be deleted. When a command to create an auto text stream is processed :
◦ the auto stream name is created with a suffix of "_FR", e.g atx1_strm_1__FR
◦ this stream is compared to the existing, frozen stream (i.e. atx1_strm_1__1) for the length of the old stream.
• If the auto stream does not change, then the autoframe is not recreated either (since 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.
• If the stream does change, the new document preference detailed above is applied:
◦ if the auto stream is to change, the old frozen stream and its parent (atx1_strm_1__1 and atx1_strm_1) are deleted and the new stream renamed as atx1_strm_1.
◦ the old frame that remains 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 stream was created will indicate that the following pages will change.)
Preventing duplicate autoframes
It is highly recommended that autoframe commands are NOT used in PTC ALDfstart loop, as you may end up with duplicate autoframes around a page break. There are two options for creating autoframes and ensuring duplicates are avoided:
• Use the <?> (or the <?=>..<?=0>) command before your autoframe commands
• Use the <?queue> command to queue up your autoframe commands until the first printable character.
Error Messages
The following error messages are displayed in the format log if a page or frame 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.
Pg 1 Page layer has no name - cannot create page - a page layer
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.
Warning Messages
The following warning messages are displayed in the format log, even if a frame has 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.
Pg 2 Auto commands moved onto next page - the placement of
an auto frame caused the command to be pushed onto the next
page.
Pg 2 Auto frame contains no text or graphics - the frame
contains no text stream or raster/object graphics.
Pg 1 Warning - frame out of bounds: Pos 0mm,271.6mm Size
246.2mm,25mm - the placement of the frame exceeds the
page boundaries.
Related Links
