Image Viewer Interactive Modes

The ImageViewer class supports rich built-in and fully customizable and extensible user-interface interaction support for panning, zooming, the magnify glass, rubber-banding and many more operations. The class supports mouse, touch screen and/or multi-touch input.

To use an interactive mode, create an instance of one of the types derived from the ImageViewerInteractiveMode object and add it to the ImageViewer.InteractiveModes collection. For example:

// Create an instance of Pan/Zoom interactive mode 
var mode = new lt.Controls.ImageViewerPanZoomInteractiveMode(); 
// Add it to the viewer 
imageViewer.interactiveModes.add(mode); 

When the viewer is set up like the example above, clicking and dragging the mouse over the viewer surface will pan the image. CTRL-clicking and dragging will zoom the image in and out. Similarly, on devices that support touch input, pressing down and dragging will pan the image while dragging with two fingers will zoom in and out.

The ImageViewer supports the following built-in and fully functional interactive modes:

Customizing Mode Behavior

These interactive modes have extra functionality to further customize the behavior as well as being fully extensible for further detailed operations.

The ImageViewer.InteractiveModes property is a collection. Consequently, you can add as many modes to the viewer as desired. This makes it possible to:

• Add all the interactive modes needed by the application once, then enable only the mode for the current application state

• Combine some interactive modes together for additional functionality

The following example will be used by all the code snippets below to demonstrate how to use this collection. Assume imageViewer is the ID of a div in the HTML page:

// Get the div item for the viewer 
var div = document.getElementById("imageViewer"); 
var createOptions = new lt.Controls.ImageViewerCreateOptions(div); 
// Create a new image viewer instance using the default constructor 
var imageViewer = new lt.Controls.ImageViewer(createOptions); 
// Load an image into it 
imageViewer.imageUrl = "http://localhost/images/image1.png"; 

The behavior resulting from the input action depends on several settings, as follows:

Mode Order The IsEnabled Value The MouseButtons Value The CanStartWork Value

The Order of the Modes in the Collection

The mode at the top of the collection (at index 0) will have the first chance of handling the action. If the interactive mode determines it should handle the event, it will set InteractiveEventArgs.IsHandled to true to indicate this to any remaining modes. The next mode in the collection then views the event, and so on with every registered interactive mode. A mode can be implemented to disregard the value of InteractiveEventArgs.IsHandled or to not set the value to true when handling the event so that multiple actions can result from one event. See the documentation for each of the built-in interactive modes for more information on how that particular mode reads or sets this property.

Add the following code to the example after setting the image:

// Add Pan/Zoom mode first 
var panZoomMode = new lt.Controls.ImageViewerPanZoomInteractiveMode(); 
imageViewer.interactiveModes.add(panZoomMode); 
// And Rubber Band mode second 
var rubberBandMode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
imageViewer.interactiveModes.add(rubberBandMode); 

Run the example and notice that only pan/zoom is usable: rubber-banding does not work. Now change the code as follows:

// And Rubber Band mode first 
var rubberBandMode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
imageViewer.interactiveModes.add(rubberBandMode); 
// Add Pan/Zoom mode second 
var panZoomMode = new lt.Controls.ImageViewerPanZoomInteractiveMode(); 
imageViewer.interactiveModes.add(panZoomMode); 

Run the example and notice that now you can draw rubber bands, but cannot pan/zoom anymore.

You can also change the order by using the collection to add/remove and insert items in different locations.

The Value of ImageViewerInteractiveMode.IsEnabled

Modes that are disabled will never run and ignore all events. IsEnabled is true by default.

Change the code in the example as follows:

// Add Rubber band first 
var rubberBandMode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
// But disable it 
rubberBandMode.isEnabled = false; 
imageViewer.interactiveModes.add(rubberBandMode); 
// Add Pan/Zoom mode second 
var panZoomMode = new lt.Controls.ImageViewerPanZoomInteractiveMode(); 
imageViewer.interactiveModes.add(panZoomMode); 

Run the example and note that even though the rubber band is the first mode, it is not usable: pan zoom is.

This is handled by each mode through the use of the InteractiveEventArgs.IsHandled property.

The Value of ImageViewerInteractiveMode.MouseButtons

The 'MouseButtons' are used when the device supports mouse input. The default value is MouseButtons.Left, but you can change it to attach an interactive mode to a different button.

Change the code in the example as follows:

// Add Rubber band first 
var rubberBandMode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
// Assign it to the left mouse button (this is the default) 
rubberBandMode.mouseButtons = lt.Controls.MouseButtons.left; 
imageViewer.interactiveModes.add(rubberBandMode); 
// Add Pan/Zoom mode second 
var panZoomMode = new lt.Controls.ImageViewerPanZoomInteractiveMode(); 
// Assign it to the right mouse button 
panZoomMode.mouseButtons = lt.Controls.MouseButtons.right; 
imageViewer.interactiveModes.add(panZoomMode); 

Run the example. Now using the left mouse button will draw a rubber band, while using the right mouse button will pan and zoom.

The order of the modes and the state of IsEnabled still applies when multiple modes are attached to the same mouse button.

Note that in touch devices that do not support a mouse, the touch input is treated as a left mouse button. Attaching a mode to any other mouse button will have no effect. However, if the application is designed to support both mouse and touch events (for example, a web application) then you can assign modes to left and right mouse buttons for extra functionality when the application is running in a desktop browser that supports mouse or both mouse and touch.

You can also set an interactive mode MouseButtons property to a combination of values. For example, MouseButtons.Left | MouseButtons.Right will instruct the mode to run when either mouse button is pressed.

Some interactive modes can run when the value of MouseButtons is MouseButtons.None. For example:

// Add auto-pan attached to left mouse button 
var autoPanMode = new lt.Controls.ImageViewerAutoPanInteractiveMode(); 
autoPanMode.mouseButtons = lt.Controls.MouseButtons.left; 
imageViewer.interactiveModes.add(autoPanMode); 

Run the example and click and move the mouse to the edge of the viewer and see how it pans the image to that direction. Now change it as follows:

// Add auto-pan, not attached to any button 
var autoPanMode = new lt.Controls.ImageViewerAutoPanInteractiveMode(); 
autoPanMode.MouseButtons = lt.Controls.MouseButtons.none; 
imageViewer.interactiveModes.add(autoPanMode); 

Run the example and see how auto-pan works now when no mouse buttons is pressed.

The Value of ImageViewerInteractiveMode.CanStartWork

This virtual method is called by the base class to determine the status of the standard conditions (such as the IsEnabled and MouseButtons properties described above) as well as the values of custom conditions such as the values of WorkOnBounds, Item, ItemPart.

Change the code in the example to use multiple items:

// Get the div item for the viewer 
var div = document.getElementById("imageViewer"); 
// Create a new image viewer instance with a vertical layout 
var createOptions = new lt.Controls.ImageViewerCreateOptions(div); 
createOptions.viewLayout = new lt.Controls.ImageViewerVerticalViewLayout(); 
var imageViewer = new lt.Controls.ImageViewer(createOptions); 
// Add a border (need some padding as well) 
imageViewer.imageBorderThickness = 1; 
// Add some padding 
imageViewer.itemPadding = lt.Controls.ControlPadding.createAll(80); 
// Use a border around the items so we can see them 
imageViewer.itemBackgroundColor = "yellow"; 
imageViewer.itemBorderThickness = 1; 
// Add a couple of items 
imageViewer.items.addFromUrl("http://localhost/images/image1.png", lt.LeadSizeD.empty); 
imageViewer.items.addFromUrl("http://localhost/images/image2.png", lt.LeadSizeD.empty); 

Now add the following interactive mode:

var mode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
imageViewer.interactiveModes.add(mode); 

Notice how if you try to draw a rubber band outside the yellow item boxes, the mode does not run. This is because the default value of ItemPart is Content and the default value of WorkOnBounds is true.

These settings are interpreted to mean to only work on the content (inside the item) part of an item. The mode will perform hit-testing on the item and if the condition is not met, it will not run.

Change the code as follows:

var mode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
mode.workOnBounds = false; 
imageViewer.interactiveModes.add(mode); 

Now, even though the part is still Content, we instructed the mode to ignore this value and not perform hit-testing. Run the code and notice how you can pan/zoom on any part inside the viewer control.

To work on a specific part of the item, it is necessary to use the following settings:

• Set the AutoItemMode . So set AutoItemMode to ImageViewerAutoItemMode.AutoSet or ImageViewerAutoItemMode.AutoSetActive

• Set WorkOnBounds to true

• Set ItemPart to the desired value

For example, the following code will make sure rubber band will only work on the image part of an item.

var mode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
mode.autoItemMode = lt.Controls.ImageViewerAutoItemMode.autoSet; 
mode.itemPart = lt.Controls.ImageViewerItemPart.image; 
mode.workOnBounds = true; 
imageViewer.interactiveModes.add(mode); 

It is also possible to restrict the mode to work on a certain item. The following code will allow rubber band to work on the second item (index of 1) only. Note that AutoItemMode is set to None so the mode does not change the Item property.

var mode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
mode.autoItemMode = lt.Controls.ImageViewerAutoItemMode.none; 
mode.item = imageViewer.items.item(1); 
mode.itemPart = lt.Controls.ImageViewerItemPart.image; 
mode.workOnBounds = true; 
imageViewer.interactiveModes.add(mode); 

Run this example and notice that rubber banding only works on the second item.

Combining Interactive Modes

Some interactive modes can be combined with others to provide extra functionality. For example, ImageViewerAutoPanInteractiveMode can be combined with any other mode to allow auto-panning the viewer while the other mode is running.

Change the code as follows:

// Add auto-pan, also left button 
var autoPanMode = new lt.Controls.ImageViewerAutoPanInteractiveMode(); 
autoPanMode.mouseButtons = lt.Controls.MouseButtons.left; 
imageViewer.interactiveModes.add(autoPanMode); 
// Add rubber-band, left button 
var rubberBandMode = new lt.Controls.ImageViewerRubberBandInteractiveMode(); 
rubberBandMode.mouseButtons = lt.Controls.MouseButtons.left; 
imageViewer.interactiveModes.add(rubberBandMode); 

Run the example, and notice that when drawing a rubber band and moving towards the edge of the viewer, it will pan in that direction. This is the auto-pan adding functionality to the rubber-band.

This is possible because auto-pan does not set the value of InteractiveEventArgs.IsHandled to true, hence the event will propagate to the next interactive mode in the list: the rubber-band.