Adding New Frames to a FrameSet

We can now add further Frames to the FrameSetFrameSet created above (§13.2). To do so, we must supply a new FrameFrame and an associated MappingMapping that relates it to any of the Frames that are already present (there is only one present so far). To keep the example simple, we will just use a ZoomMapZoomMap that multiplies coordinates by 10. The required Objects are created as follows:


\begin{terminalv}
AstFrame *frame2;
AstMapping *mapping12;
\par
...
\par
frame2 ...
...ame( 2, ''Domain=B'' );
mapping12 = astZoomMap( 2, 10.0, '''' );
\end{terminalv}

To add the new Frame into our FrameSet, we use the astAddFrameastAddFrame function:


\begin{terminalv}
astAddFrame( frameset, 1, mapping12, frame2 );
\end{terminalv}

Whenever a Frame is added to a FrameSet, it is assigned an integer index. This index starts with 1 for the initial Frame used to create the FrameSet (§13.2) and increments by one every time a new Frame is added. This index is the primary way of identifying the Frames within a FrameSet.

When a Frame is added, we also have to specify which of the existing ones the new Frame is related to. Here, we chose number 1, the only one present so far, and the new one we added became number 2.

Note that a FrameSet does not make copies of the Frames and Mappings that you insert into it. Instead, it holds pointers to them. This means that if you retain the original pointers to these Objects and alter them, you will indirectly be altering the FrameSet's contents. You can, of course, always use astCopyastCopy (§4.13) to make a separate copy of any ObjectObject if you need to ensure its independence.

We could also add a third Frame into our FrameSet, this time defining a coordinate system which is reached by multiplying the original coordinates (of “frame1”) by 5:


\begin{terminalv}
astAddFrame( frameset, 1, astZoomMap( 2, 5.0, '''' ), astFrame( 2, ''Domain=C'' ) );
\end{terminalv}

Here, we have avoided storing unnecessary pointer values by using function invocations directly as arguments for astAddFrame. This assumes that we are using astBeginastBegin and astEndastEnd (§4.10) to ensure that Objects are correctly deleted when no longer required.

Our example FrameSet now contains three Frames and two Mappings with the arrangement shown in Figure 14.

Figure 14: An example FrameSet, in which Frames 2 and 3 are related to Frame 1 by multiplying its coordinates by factors of 10 and 5 respectively. The FrameSet's BaseBase attribute has the value 1 and its CurrentCurrent attribute has the value 3. The transformation performed when the FrameSet is used as a Mapping (i.e. from its base to its current Frame) is shown in bold.
[width=0.7]sun211_figures/fsexample
The total number of Frames is given by its read-only NframeNframe attribute.