The "port" in which the swap effect is viewed is termed the Swap Port.

The Swap Port contains two Views - one View for displaying the current item, and another View for revealing the next item. Both Views are positioned absolutely, with one on top of the other.

One item node in the Swap Port is termed a View.

There are two Views in the Swap Port: one View provides a view into the current item, and the other View provides a view into the next item that is being revealed. When a swap is performed, initial View coordinates (termed the View Seed) and final View coordinates (termed the View Final) are calculated. During the course of the swap effect, the View coordinates for the next item's View are interpolated between the View Seed coordinates and the View Final coordinates. Additionally, its opacity will be faded from completely transparent to completely opaque over the course of the animation if the dissolve set-get property is set to true.

If the crossFade set-get property is set to true, then the Crossfade behavior is enabled and the View coordinates for the current item's View will be interpolated between the View Final coordinates and the View Seed coordinates, and its opacity will be faded from completely opaque to completely transparent over the course of the animation if the dissolve set-get property is set to true. The additional crossFadeSize and crossFadeAlign set-get properties govern the nature of the Crossfade behavior.

The View Seed is the initial coordinates for a View.

The View Seed is derived by calculating View Seed Size and View Seed Alignment, in this process combining the coordinates of the View Final and the values of the viewSeedSizeX, viewSeedSizeY, viewSeedAlignX, and viewSeedAlignY set-get properties (discussed below).

2.2.3.1. View Seed Size

2.2.3.2. View Seed Alignment

The View Final is the final coordinates for a View, being the coordinates of the Swap Port.

Crossfade refers to the process by which the current item is progressively hidden while the next item is progressively revealed.

The crossFade set-get property allows one to enable or disable the Crossfade behavior. When crossFade is set to false, then the Crossfade behavior is disabled and the current item will be hidden only as a side effect of the next item being revealed to fully obscure it. When crossFade is set to true, then the Crossfade behavior is enabled and the current item will be progressively hidden while the next item is progressively revealed.

The way that the current item is hidden is essentially the reverse of the effect for revealing the next item. So, for example, if the exact settings for the swap effect mean that the next item will slide out from the right edge while also fading in from completely transparent to completely opaque, then the current item will hide by sliding out towards the right edge while also fading out from completely opaque to completely transparent.

The additional crossFadeSize and crossFadeAlign set-get properties govern the nature of the Crossfade behavior.

2.2.5.1. Crossfade Size

2.2.5.2. Crossfade Alignment

View Content Alignment refers to the positioning of an item within its corresponding View.

As the swap effect progresses, the coordinates of a View are animated between the View Seed coordinates and the View Final coordinates. At any one point during this transition, the way that the item is positioned within the View coordinates is determined by the viewContentAlignX and viewContentAlignY set-get properties (alignment can be controlled discretely for the X and Y axes). The values specified for these properties should be floating point numbers in the range of 0 to 1, where the value 0 represents left and top alignment, the value 1 represents right and bottom alignment, and the value .5 represents center alignment.

Additionally, the special value 'none' indicates that there should be no View Content Alignment for the axis for which the value 'none' is specified, meaning that the item's position for that axis will be fixed with respect to the Swap Port for the entire duration of the effect.

To better understand the principle of View Content Alignment, it may help to consider as an example the value of the Uize.Widget.Swap.presets.fadeSlideInFromRight preset...

{
  crossFade:false,
  crossFadeSize:0,
  crossFadeAlign:.5,
  dissolve:true,
  viewContentAlignX:0,
  viewContentAlignY:'none',
  viewSeedSizeX:0,
  viewSeedSizeY:1,
  viewSeedAlignX:1,
  viewSeedAlignY:0
}

With the fadeSlideInFromRight preset, the new item slides in from the right edge and also fades in as it slides into place to eventually fully cover the current item.

The View Seed is a vertical sliver, as defined by the values for the viewSeedSizeX and viewSeedSizeY set-get properties. The value of 0 for viewSeedSizeX means that the View Seed has a width of 0, and the value of 1 for viewSeedSizeY means that the View Seed starts out at the full height of the Swap Port. Moreover, the value of 1 for viewSeedAlignX means that the vertical sliver is aligned so that it is positioned at the right edge of the Swap Port. Because viewSeedSizeY is set to 1, the value of the viewSeedAlignY set-get property (0 in this case) has no effect on the vertical position of the View Seed.

Now, as the effect progresses, the new item is revealed within an ever growing rectangle that starts out as a vertical sliver on the right, to eventually become the entire Swap Port. As this rectangle grows, how is the positioning of the view content within this rectangle determined? How does one qualify the difference between a wipe reveal and a slide in reveal?

The answer is to be found in the values of the viewContentAlignX and viewContentAlignY set-get properties. In this example, viewContentAlignX is set to 0. What this means is that the new item is positioned within the ever growing View rectangle so that it is aligned against its left edge. This has the effect of creating a slide in effect. Were the value of viewContentAlignX to be 1 (ie. right aligned) or 'none', then you would end up with a wipe reveal.

The value 'none' has the same effect as right alignment in this case because the View Seed starts at the right edge of the Swap Port and the right edge of the View rectangle stays against the right edge of the Swap Port as the rectangle grows during the effect. By contrast, the value 'none' would not have the same effect as 1 if the viewSeedAlignX set-get property were set to .5.

Cycling Property Sets, as specified in the cyclingPropertySets set-get property, provide a convenient way to cycle through different swap effect settings on each transition from the current item to the next item.

The value of the cyclingPropertySets property should be an array, where each element of the array is an object containing values for the set-get properties of the Uize.Widget.Swap class. Each time, upon transitioning from the current item to the next item, the current element of the cyclingPropertySets is used to set new effect values and the array counter is advanced. Upon using the last element of the array, the counter is then reset back to 0, thereby starting again at the first element. Consider the following example...

EXAMPLE

page.addChildren (
  'imageSwap',
  Uize.Widget.Swap.Image,
  {
    cyclingPropertySets:[
      Uize.Widget.Swap.presets.fadeOutPauseThenFadeIn,
      Uize.Widget.Swap.presets.fadeWipeHorizontalFromCenter,
      Uize.Widget.Swap.presets.fadeSlideInFromBottom,
      Uize.Widget.Swap.presets.wipeOutWipeInLeft,
      Uize.Widget.Swap.presets.centerOpenCloseCrossFade
    ]
  }
);

In the above example, an instance of the Uize.Widget.Swap.Image subclass is being added as a child widget to the a page widget instance (that we can assume to have already been created). The cyclingPropertySets set-get property is being set to an array containing a limited number of preset effect settings that have been cherry-picked from the presets defined in the Uize.Widget.Swap.xPresets extension module (which we can assume to have been previously loaded). Now, each time a new value is set for the src set-get property of the imageSwap instance (src is implemented in the Uize.Widget.Swap.Image subclass), the next effect settings will be picked from the cyclingPropertySets array and set on the imageSwap instance. So, in a nutshell, each transition will use different effect settings.