Image Viewer Sync

Summary

Both the HTML5/JavaScript and .NET ImageViewer have the ability to sync with the inputs from other ImageViewers. When two or more ImageViewers are synced, their ImageViewer.SyncId properties will have the same integer value. As long as the ImageViewer control receiving input (A) has a value of true for ImageViewer.IsSyncSource and the ImageViewer that should react to input (B) has a value of true for ImageViewer.IsSyncTarget, both ImageViewer instances (A and B) can react to the input provided to the receiving ImageViewer (A). The details of this feature are discussed further below.

Automatic syncing features include:

Set ImageViewer.ViewLayout*
ImageViewer.Zoom
ImageViewer.ScrollBy / ImageViewer.ScrollByRestrict
ImageViewer.ZoomToRect
Mousewheel / Scrollbar / Touch scrolling
ImageViewer.DisableTransitions / ImageViewer.EnableTransitions (for JavaScript only)
All features of ImageViewerPanZoomInteractiveMode, including Inertia Scroll

* Note that in the case of setting a ViewLayout to an ImageViewer, each ImageViewer instance often has its own ViewLayout. The developer may wish to disable sync temporarily to manually modify the ViewLayout for synced ImageViewers.

By default, all ImageViewer instances begin with a value of -1 for ImageViewer.SyncId. This means the ImageViewer is not synced with any other ImageViewer. When two ImageViewer instances are synced, both will have their ImageViewer.SyncId set to the same integer value. Thus, the synced viewers can be considered a part of a "sync group".

The following static methods exist for syncing between ImageViewers:

Static Method	Description
void ImageViewer.Sync(List<ImageViewer> imageViewers)	Establishes sync groups (assigns ImageViewers to the same ImageViewer.SyncId)
List<ImageViewer> ImageViewer.GetSynced(int syncId	Returns a list of all ImageViewer instances that match the given sync ID. If none exist for the provided ID, null is returned. This list should be copied before it is modified.
void ImageViewer.UnSync(ImageViewer imageViewer)	Removes a single viewer from the sync group. If the sync group has fewer than 2 members after the removal of the ImageViewer, the remaining members are also un-synced.
List<ImageViewer> ImageViewer.UnsyncGroup(int syncId)	Un-syncs all members of the sync group of the given Sync ID, then returns those formerly-synced viewers. If no group exists, null is returned.

Syncing

The static ImageViewer.Sync method assigns the provided ImageViewer instances the same Sync ID, establishing them as a sync group. If the number of provided non-null ImageViewer instances is less than 2, no syncing occurs. If all the ImageViewer instances are already in the same sync group, nothing happens. If none of the ImageViewer instances are a part of a sync group, a new sync group is established and all the instances are assigned the new Sync ID.

In the case where some ImageViewers are already a part of a sync group, all ImageViewers (and their currently associated sync groups) are assigned to the sync group of the ImageViewer with the lowest ImageViewer.SyncId value. This means ImageViewers that were not provided in the initial input to ImageViewer.Sync will still be affected if a member of their sync group is included in the input parameter list.

Example of this case:

Step	Cause	Effect
1	ImageViewer.Sync is called with ImageViewers A and B, and then separately with C and D.	Two sync groups are created. Sync Group 0: A, B Sync Group 1: C, D
2	ImageViewer.Sync is called with just ImageViewer E.	Nothing changes; at least two non-null ImageViewers must be provided. Sync Group 0: A, B Sync Group 1: C, D
3	ImageViewer.Sync is called with D (which has ImageViewer.SyncId value of 1) and E.	E is added to the current sync group of D. Sync Group 0: A, B Sync Group 1: C, D, E
4	ImageViewer.Sync is called with A, C, and F. A has a Sync ID of 0, and C has a Sync ID of 1.	All ImageViewer instances are added to the lowest-value Sync ID, which is 0, because of ImageViewer A. Sync Group 0: A, B, C, D, E, F

Working with Synced ImageViewers

Once a sync group is established, the above ImageViewer features will sync between all ImageViewers by default. To temporarily disable syncing for a group while keeping the group itself intact, use the ImageViewer.DisableSync, ImageViewer.IsSyncDisabled, and ImageViewer.EnableSync static methods. While a group's sync is temporarily disabled, all ImageViewer instances in the group will still report the same ImageViewer.SyncId; thus, ImageViewer.IsSyncDisabled will be the only way to tell if the sync group is enabled or disabled.

Some of the automatic commands that sync between ImageViewers, such as ImageViewer.Zoom, will internally call other ImageViewer methods that would also sync. To prevent endless sync loop cycles, these automatic commands will internally call ImageViewer.DisableSync and ImageViewer.EnableSync. For this reason, some callbacks for ImageViewer.TransformChanged or other events will sometimes return ImageViewer.IsSyncDisabled as true.

Individual Sync Control

Each ImageViewer instance can make use of ImageViewer.IsSyncSource and ImageViewer.IsSyncTarget to fine-tune any directional syncing needs. Both properties are true by default, meaning interactions with ImageViewer A will cause ImageViewer B to change and vice versa. Interactions on an ImageViewer will always cause the source ImageViewer to react.

A given synced ImageViewer will only react if sourceImageViewer.IsSyncSource && targetImageViewer.IsSyncTarget.

See Also