C

ViewportLimiter

Show Usages
Used by CanvasComponent to limit the interactive movement of the viewport.
Inheritance Hierarchy

Remarks

The viewportLimiter instance should be consulted whenever the user tries to change the viewport. Using method limitViewport the desired viewport can be validated and adjusted by the implementation. Note that setting the zoom property or viewPoint properties directly will not be influenced by implementations of this class. It is up to the caller to perform verification.

See Also

Developer's Guide

API

bounds

Members

Show:

Constructors

ViewportLimiter

()
Initializes a new instance of the ViewportLimiter class.

Parameters

Properties

bounds

: Rect
Gets or sets the maximal allowed navigable bounds for the viewport.
If you use either positive or negative infinity in the supplied bounds the limiter will calculate with +/-1e100 internally.
conversionfinal

Property Value

The bounds or null. This value will be used by the default implementation of limitViewport to crop the desired viewport to.

See Also

Developer's Guide

minimumViewportContentRatio

: Size
Gets or sets the percentage of the width and height of the viewport that should be reserved *at least* when viewportContentMargins are defined.
The margins are absolute in the view coordinate system and thus the remaining space could become void if the CanvasComponent gets resized. Setting these ratios will ensure that at least this amount of space is reserved for the actual content and will thus reduce the margins when the canvas gets too small. The default values are 0.8 for both dimensions, so 80% of the space is reserved for the contents and margins can take up at most 10% of the space on each side. In these cases this space is distributed such that it corresponds to the ratio of the left/right and/or top/bottom viewportContentMargins.
conversionfinal

policy

: ViewportLimitingPolicy
Gets or sets the policy on how the viewport is limited if the current viewport is not within the limits.
The default is WITHIN_MARGINS.
conversionfinal

See Also

Developer's Guide

strictBoundsContainment

: boolean
Gets or sets a value that describes how bounds should be treated.

If set to true the viewport is limited in a way that the viewport must only show elements inside the bounds and no area outside the bounds should ever be visible. If the aspect ratio of the viewport and bounds differ, parts of the viewport will always be cropped as zooming out will be restricted by one axis. In video terminology, this setting is often referred to as "crop" or "cropping". When combined with projection, this feature will effectively prevent the user from reaching all parts within bounds without zooming in very far because the space around the "tips" of the bounds in the viewport are not aligned with the viewport.

If set to false the viewport is only limited in a way that while it is possible to see parts outside the bounds, the process tries to minimize the amount of possible space outside the bounds. If the aspect ratio of the viewport and bounds differ, parts of the viewport will be outside the limits. In video terminology, this setting is often referred to as "letterbox" or "letterboxing". In other words, with this option, it will be possible to zoom out so that all bounds can be visible at the same time. When combined with projection, this feature will allow the user to fully see elements that lie at the border of bounds without zooming in very far because the viewport is allowed to go beyond the bounds, but only so far as not more whitespace will become visible than necessary to show more of the inside of the bounds.

Default is false.

final

Property Value

true if only bounds should be shown inside the viewport; otherwise, false.

See Also

Developer's Guide

useContentBounds

: boolean
Gets or sets a value that determines whether the CanvasComponent's contentBounds should be implicitly used as the bounds to limit against.
If set to true the contentBounds will be used as the bounds if none are specified, otherwise. getCurrentBoundingPolygon will obtain the bounds from the control if bounds is still unspecified (null). By default, this feature is enabled.
final

See Also

Developer's Guide
API
getCurrentBoundingPolygon

viewportContentMargins

: Insets
Gets or sets the margins in the view coordinate system around the tight bounds in world coordinates.
This allows you to have tight bounds in the world coordinate system, but still allow to pan/zoom to slightly larger bounds interactively so that you get some margins around the contents in view coordinates. Since the effective margin depends on the zoom, this value cannot be otherwise easily interpreted via the bounds property. The default is to have 20.0 margins on all sides. If the horizontal or vertical margins exceed the space given by the minimumViewportContentRatio the available space is distributed such that it corresponds to the ratio of the left/right and/or top/bottom viewportContentMargins.
conversionfinal

See Also

Developer's Guide

Methods

getCurrentBoundingPolygon

(
canvasComponent: CanvasComponent
requestedViewport: ViewportDescriptor
mode: ViewportLimitingMode
): Point
protected
Gets the bounding polygon that should be honored for the upcoming limiting call.
This method is used as callback by limitViewport for each limiting request. The default implementation just yields bounds as a list of points or contentBounds when useContentBounds is enabled.
protected

Parameters

canvasComponent: CanvasComponent
The canvas control.
requestedViewport: ViewportDescriptor
The requested new viewport.
mode: ViewportLimitingMode
The current limiting mode for the request.

Return Value

Point
The bounds in the world coordinate system in the form of a strictly convex polygon where the points are given in clockwise order. null if there are no restrictions.

See Also

Developer's Guide

limitViewport

(
canvasComponent: CanvasComponent
requestedViewport: ViewportDescriptor
mode: ViewportLimitingMode
): ViewportDescriptor
Inspects the requested new viewport for the given CanvasComponent and returns a valid viewport to use.

Parameters

canvasComponent: CanvasComponent
The canvas on which the viewport should be applied.
requestedViewport: ViewportDescriptor
The viewport as requested by the caller.
mode: ViewportLimitingMode
A context that describes the current request. Specifically, this controls whether the current viewport should be honored and/or whether this change is an incremental, interactive, or programmatically triggered change. This is used for example by fitContent or ZOOM_TO_CURRENT_ITEM where larger viewport changes are expected, whereas interactive drags and scrollbar movements can be handled more gracefully depending on context.

Return Value

ViewportDescriptor
A valid viewport that should be used.

See Also

Developer's Guide