astMirrorVariantsastMirrorVariants - Make the current Frame mirror the variant Mappings in another Frame

Description:
This function indicates that all access to the VariantVariant attribute of the current FrameFrame should should be forwarded to some other nominated Frame in the FrameSetFrameSet. For instance, if a value is set subsequently for the Variant attribute of the current Frame, the current Frame will be left unchanged and the setting is instead applied to the nominated Frame. Likewise, if the value of the Variant attribute is requested, the value returned is the value stored for the nominated Frame rather than the current Frame itself.

This provides a mechanism for propagating the effects of variant Mappings around a FrameSet. If a new Frame is added to a FrameSet by connecting it to an pre-existing Frame that has two or more variant Mappings, then it may be appropriate to set the new Frame so that it mirrors the variants Mappings of the pre-existing Frame. If this is done, then it will be possible to select a specific variant MappingMapping using either the pre-existing Frame or the new Frame.

Synopsis:
void astMirrorVariants( AstFrameSet $*$this, int iframe, int $*$status )
Parameters:
this
Pointer to the FrameSet.
iframe
The index of the Frame within the FrameSet which is to be mirrored by the current Frame. This value should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). If AST__NOFRAME is supplied (or the current Frame is specified), then any mirroring established by a previous call to this function is disabled.
Notes:
  • Mirrors can be chained. That is, if Frame B is set to be a mirror of Frame A, and Frame C is set to be a mirror of Frame B, then Frame C will act as a mirror of Frame A.

  • Variant Mappings cannot be added to the current Frame if it is mirroring another Frame. So calls to the astAddVariantastAddVariant function will cause an error to be reported if the current Frame is mirroring another Frame.

  • A value of AST__BASE may be given for the "iframe" parameter to specify the base Frame.

  • Any variant Mappings explicitly added to the current Frame using astAddVariant will be ignored if the current Frame is mirroring another Frame.