From 4f1cd4f3854b75504d38cb116b15ed0f3852eb45 Mon Sep 17 00:00:00 2001 From: rgvassar Date: Fri, 9 Sep 2016 06:53:44 -0700 Subject: [PATCH] openlayers - Updated many of the interactions according to documentation. (#10946) * Updated many of the interactions according to documentation. * Spelling error fixed. Function definition too specific. Added documentation. * Added SelectEvent. * Fixed incorrect return type on dragBox.getGeometry --- openlayers/openlayers.d.ts | 578 ++++++++++++++++++++++++++++++++++--- 1 file changed, 540 insertions(+), 38 deletions(-) diff --git a/openlayers/openlayers.d.ts b/openlayers/openlayers.d.ts index 37a3fad9c84877..7cc216f1c2fd2f 100644 --- a/openlayers/openlayers.d.ts +++ b/openlayers/openlayers.d.ts @@ -626,46 +626,365 @@ declare namespace olx { namespace interaction { interface DefaultsOptions { + /*** Whether Alt-Shift-drag rotate is desired. Default is true.*/ altShiftDragRotate?: boolean; + /*** Whether double click zoom is desired. Default is true.*/ doubleClickZoom?: boolean; + /*** Whether keyboard interaction is desired. Default is true.*/ keyboard?: boolean; + /*** Whether mousewheel zoom is desired. Default is true.*/ mouseWheelZoom?: boolean; + /*** Whether Shift-drag zoom is desired. Default is true.*/ shiftDragZoom?: boolean; + /*** Whether drag pan is desired. Default is true.*/ dragPan?: boolean; + /*** Whether pinch rotate is desired. Default is true.*/ pinchRotate?: boolean; + /*** Whether pinch zoom is desired. Default is true.*/ pinchZoom?: boolean; + /*** Zoom delta*/ zoomDelta?: number; + /*** Zoom duration*/ zoomDuration?: number; } + interface InteractionOptions { + /** + * Method called by the map to notify the interaction that a browser event was dispatched to the map. + * The function may return false to prevent the propagation of the event to other interactions in + * the map's interactions chain. Required. + */ + handleEvent: Function; + } interface ModifyOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event will + * be considered to add or move a vertex to the sketch. Default is ol.events.condition.primaryAction. + */ + condition?: ol.events.ConditionType; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should + * be handled. By default, ol.events.condition.singleClick with ol.events.condition.noModifierKeys results + * in a vertex deletion. + */ deleteCondition?: ol.events.ConditionType; + /*** Pixel tolerance for considering the pointer close enough to a segment or vertex for editing. Default is 10.*/ pixelTolerance?: number; + /*** Style used for the features being modified. By default the default edit style is used (see ol.style).*/ style?: ol.style.Style | Array | ol.style.StyleFunction; + /*** The features the interaction works on. Required.*/ features: ol.Collection; + /*** Wrap the world horizontally on the sketch overlay. Default is false.*/ wrapX?: boolean; } + interface DragBoxOptions { + /*** CSS class name for styling the box. The default is ol-dragbox.*/ + className?: string; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.always. + */ + condition?: ol.events.ConditionType; + /*** A function that takes a ol.MapBrowserEvent and two ol.Pixels to indicate whether a boxend event should be fired.*/ + boxEndCondition?: ol.interaction.DragBoxEndConditionType; + } interface DrawOptions { + /** + * The maximum distance in pixels between "down" and "up" for a "up" event to be considered a "click" event and actually + * add a point/vertex to the geometry being drawn. Default is 6 pixels. That value was chosen for the draw interaction + * to behave correctly on mouse as well as on touch devices. + */ clickTolerance?: number; + /** + * Destination collection for the drawn features. + */ features?: ol.Collection; + /** + * Destination source for the drawn features. + */ source?: ol.source.Vector; + /** + * Pixel distance for snapping to the drawing finish. Default is 12. + */ snapTolerance?: number; + /** + * Drawing type ('Point', 'LineString', 'Polygon', 'MultiPoint', 'MultiLineString', 'MultiPolygon' or 'Circle'). Required. + */ type: ol.geom.GeometryType; + /** + * The number of points that can be drawn before a polygon ring or line string is finished. The default is no restriction. + */ maxPoints?: number; + /** + * The number of points that must be drawn before a polygon ring or line string can be finished. Default is 3 for polygon + * rings and 2 for line strings. + */ minPoints?: number; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether the drawing can be finished. + */ + finishCondition?: ol.events.ConditionType; + /** + * Style for sketch features. + */ style?: ol.style.Style | Array | ol.style.StyleFunction; + /** + * Function that is called when a geometry's coordinates are updated. + */ geometryFunction?: ol.interaction.DrawGeometryFunctionType; + /** + * Geometry name to use for features created by the draw interaction. + */ + geometryName?: string; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * By default ol.events.condition.noModifierKeys, i.e. a click, adds a vertex or deactivates freehand drawing. + */ + condition?: ol.events.ConditionType; + /** + * Condition that activates freehand drawing for lines and polygons. This function takes an ol.MapBrowserEvent and returns + * a boolean to indicate whether that event should be handled. The default is ol.events.condition.shiftKeyOnly, meaning that + * the Shift key activates freehand drawing. + */ + freehandCondition?: ol.events.ConditionType; + /** + * Wrap the world horizontally on the sketch overlay. Default is false. + */ wrapX?: boolean; } + interface DoubleClickZoomOptions { + /** + * Animation duration in milliseconds. Default is 250. + */ + duration?: number; + /** + * The zoom delta applied on each double click, default is 1. + */ + delta?: number; + } + interface DragAndDropOptions { + /** + * Format constructors. + */ + formatConstructors?: Array; + /** + * Target projection. By default, the map's view's projection is used. + */ + projection: ol.proj.ProjectionLike; + /** + * The element that is used as the drop target, default is the viewport element. + */ + target?: Element; + } + interface DragPanOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.noModifierKeys. + */ + condition?: ol.events.ConditionType; + /** + * Kinetic inertia to apply to the pan. + */ + kinetic?: ol.Kinetic; + } + interface DragRotateOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.altShiftKeysOnly. + */ + condition?: ol.events.ConditionType; + /** + * Animation duration in milliseconds. Default is 250. + */ + duration?: number; + } + interface DragRotateAndZoomOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.shiftKeyOnly. + */ + condition?: ol.events.ConditionType; + /** + * Animation duration in milliseconds. Default is 400. + */ + duration?: number; + } + interface DragZoomOptions { + /** + * CSS class name for styling the box. The default is ol-dragzoom. + */ + className?: string; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.shiftKeyOnly. + */ + condition?: ol.events.ConditionType; + /** + * Animation duration in milliseconds. Default is 200. + */ + duration?: number; + /** + * Use interaction for zooming out. Default is false. + */ + out?: boolean; + } + interface KeyboardPanOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.noModifierKeys and ol.events.condition.targetNotEditable. + */ + condition?: ol.events.ConditionType; + /** + * Animation duration in milliseconds. Default is 100. + */ + duration?: number; + /** + * Pixel The amount to pan on each key press. Default is 128 pixels. + */ + pixelDelta?: number; + } + interface KeyboardZoomOptions { + /** + * Animation duration in milliseconds. Default is 100. + */ + duration?: number; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * Default is ol.events.condition.targetNotEditable. + */ + condition?: ol.events.ConditionType; + /** + * The amount to zoom on each key press. Default is 1. + */ + delta?: number; + } + interface MouseWheelZoomOptions { + /** + * Animation duration in milliseconds. Default is 250. + */ + duration?: number; + /** + * Enable zooming using the mouse's location as the anchor. Default is true. + * When set to false, zooming in and out will zoom to the center of the screen instead of zooming on the mouse's location. + */ + useAnchor?: boolean; + } + interface PinchRotateOptions { + /** + * The duration of the animation in milliseconds. Default is 250. + */ + duration?: number; + /** + * Minimal angle in radians to start a rotation. Default is 0.3. + */ + threshold?: number; + } + interface PinchZoomOptions { + /** + * Animation duration in milliseconds. Default is 400. + */ + duration?: number; + } + interface PointerOptions { + /** + * Function handling "down" events. If the function returns true then a drag sequence is started. + */ + handleDownEvent?: Function; + /** + * Function handling "drag" events. This function is called on "move" events during a drag sequence. + */ + handleDragEvent?: Function; + /** + * Method called by the map to notify the interaction that a browser event was dispatched to the map. + * The function may return false to prevent the propagation of the event to other interactions in the map's interactions chain. + */ + handleEvent?: Function; + /** + * Function handling "move" events. This function is called on "move" events, also during a drag sequence + * (so during a drag sequence both the handleDragEvent function and this function are called). + */ + handleMoveEvent?: Function; + /** + * Function handling "up" events. If the function returns false then the current drag sequence is stopped. + */ + handleUpEvent?: Function; + } + interface SnapOptions { + /** + * Snap to these features. Either this option or source should be provided. + */ + features?: ol.Collection; + /** + * Snap to edges. Default is true. + */ + edge?: boolean; + /** + * Snap to vertices. Default is true. + */ + vertex?: boolean; + /** + * Pixel tolerance for considering the pointer close enough to a segment or vertex for snapping. Default is 10 pixels. + */ + pixelTolerance?: number; + /** + * Snap to features from this source. Either this option or features should be provided. + */ + source?: ol.source.Vector; + } interface SelectOptions { + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * By default, this is ol.events.condition.never. + * Use this if you want to use different events for add and remove instead of toggle. + */ addCondition?: ol.events.ConditionType; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * This is the event for the selected features as a whole. By default, this is ol.events.condition.singleClick. + * Clicking on a feature selects that feature and removes any that were in the selection. + * Clicking outside any feature removes all from the selection. + * See toggle, add, remove options for adding/removing extra features to/ from the selection. + */ condition?: ol.events.ConditionType; + /** + * A list of layers from which features should be selected. Alternatively, a filter function can be provided. + * The function will be called for each layer in the map and should return true for layers that you want to be selectable. + * If the option is absent, all visible layers will be considered selectable. + */ layers?: Array | ((layer: ol.layer.Layer) => boolean); + /** + * Style for the selected features. By default the default edit style is used (see ol.style). + */ style?: ol.style.Style | Array | ol.style.StyleFunction; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * By default, this is ol.events.condition.never. + * Use this if you want to use different events for add and remove instead of toggle. + */ removeCondition?: ol.events.ConditionType; + /** + * A function that takes an ol.MapBrowserEvent and returns a boolean to indicate whether that event should be handled. + * This is in addition to the condition event. By default, ol.events.condition.shiftKeyOnly, + * i.e. pressing shift as well as the condition event, adds that feature to the current selection if it is not currently + * selected, and removes it if it is. See add and remove if you want to use different events instead of a toggle. + */ toggleCondition?: ol.events.ConditionType; + /** + * A boolean that determines if the default behaviour should select only single features or all (overlapping) + * features at the clicked map position. Default is false i.e single select + */ multi?: boolean; + /** + * Collection where the interaction will place selected features. Optional. If not set the interaction will create a collection. + * In any case the collection used by the interaction is returned by ol.interaction.Select#getFeatures. + */ features?: ol.Collection; + /** + * A function that takes an ol.Feature and an ol.layer.Layer and returns true if the feature may be selected or false otherwise. + */ filter?: ol.interaction.SelectFilterFunction; + /** + * Wrap the world horizontally on the selection overlay. Default is true. + */ wrapX?: boolean; } } @@ -3754,79 +4073,262 @@ declare namespace ol { } namespace interaction { - - class DoubleClickZoom { + /** + * Allows the user to zoom by double-clicking on the map. + */ + class DoubleClickZoom extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.DoubleClickZoomOptions); } - - class DragAndDrop { + /** + * Handles input of vector data by drag and drop. + */ + class DragAndDrop extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.DragAndDropOptions); } - + /** + * Events emitted by ol.interaction.DragAndDrop instances are instances of this type. + */ class DragAndDropEvent extends ol.events.Event { } - - class DragBox { + /** + * Allows the user to draw a vector box by clicking and dragging on the map, + * normally combined with an ol.events.condition that limits it to when the shift or other key is held down. + * This is used, for example, for zooming to a specific area of the map + * (see ol.interaction.DragZoom and ol.interaction.DragRotateAndZoom). + * + * This interaction is only supported for mouse devices. + */ + class DragBox extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.DragBoxOptions); + /** + * Returns geometry of last drawn box. + */ + getGeometry(): ol.geom.Polygon; } - - class DragPan { + /** + * Allows the user to pan the map by dragging the map. + */ + class DragPan extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.DragPanOptions); } - - class DragRotate { + /** + * Allows the user to rotate the map by clicking and dragging on the map, + * normally combined with an ol.events.condition that limits it to when the alt and shift keys are held down. + * + * This interaction is only supported for mouse devices. + */ + class DragRotate extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.DragRotateOptions); } - - class DragRotateAndZoom { + /** + * Allows the user to zoom and rotate the map by clicking and dragging on the map. + * By default, this interaction is limited to when the shift key is held down. + * + * This interaction is only supported for mouse devices. + * + * And this interaction is not included in the default interactions. + */ + class DragRotateAndZoom extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.DragRotateAndZoomOptions); } - - class DragZoom { + /** + * Allows the user to zoom the map by clicking and dragging on the map, + * normally combined with an ol.events.condition that limits it to when a key, shift by default, is held down. + * + * To change the style of the box, use CSS and the .ol-dragzoom selector, or your custom one configured with className. + */ + class DragZoom extends ol.interaction.DragBox { + constructor(opt_options?: olx.interaction.DragZoomOptions); } - + /** + * Interaction for drawing feature geometries. + */ class Draw extends ol.interaction.Pointer { - constructor(opt_options?: olx.interaction.DrawOptions) + constructor(opt_options?: olx.interaction.DrawOptions); } - + /** + * Events emitted by ol.interaction.Draw instances are instances of this type. + */ class DrawEvent extends ol.events.Event { + /** + * The feature being drawn. + */ + feature: ol.Feature; + /** + * The event target. + */ + target: ol.Object; + /** + * The event type. + */ + type: string; } - + /** + * Abstract base class; normally only used for creating subclasses and not instantiated in apps. + * User actions that change the state of the map. Some are similar to controls, but are not associated with a DOM element. + * For example, ol.interaction.KeyboardZoom is functionally the same as ol.control.Zoom, but triggered by a keyboard event + * not a button element event. Although interactions do not have a DOM element, + * some of them do render vectors and so are visible on the screen. + */ class Interaction extends ol.Object { + constructor (options: olx.interaction.InteractionOptions) + /** + * Return whether the interaction is currently active. + */ + getActive (): boolean; + /** + * Get the map associated with this interaction. + */ + getMap (): ol.Map; + /** + * Activate or deactivate the interaction. + */ + setActive (active: boolean): void; } - - class KeyboardPan { + /** + * Allows the user to pan the map using keyboard arrows. Note that, although this interaction is by default included in maps, + * the keys can only be used when browser focus is on the element to which the keyboard events are attached. + * By default, this is the map div, though you can change this with the keyboardEventTarget in ol.Map. + * document never loses focus but, for any other element, focus will have to be on, and returned to, + * this element if the keys are to function. See also ol.interaction.KeyboardZoom. + */ + class KeyboardPan extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.KeyboardPanOptions); } - - class KeyboardZoom { + /** + * Allows the user to zoom the map using keyboard + and -. Note that, although this interaction is by default included in maps, + * the keys can only be used when browser focus is on the element to which the keyboard events are attached. By default, + * this is the map div, though you can change this with the keyboardEventTarget in ol.Map. document never loses focus but, + * for any other element, focus will have to be on, and returned to, this element if the keys are to function. + * See also ol.interaction.KeyboardPan. + */ + class KeyboardZoom extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.KeyboardZoomOptions); } - + /** + * Interaction for modifying feature geometries. + */ class Modify extends ol.interaction.Pointer { - constructor(opt_options?: olx.interaction.ModifyOptions) + constructor(opt_options?: olx.interaction.ModifyOptions); } - - class MouseWheelZoom { + /** + * Allows the user to zoom the map by scrolling the mouse wheel. + */ + class MouseWheelZoom extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.MouseWheelZoomOptions); } - - class PinchRotate { + /** + * Allows the user to rotate the map by twisting with two fingers on a touch screen. + */ + class PinchRotate extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.PinchRotateOptions); } - - class PinchZoom { + /** + * Allows the user to zoom the map by pinching with two fingers on a touch screen. + */ + class PinchZoom extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.PinchZoomOptions); } - + /** + * Base class that calls user-defined functions on down, move and up events. This class also manages "drag sequences". + * + * When the handleDownEvent user function returns true a drag sequence is started. During a drag sequence the handleDragEvent + * user function is called on move events. The drag sequence ends when the handleUpEvent user function is called and returns false. + */ class Pointer extends ol.interaction.Interaction { + constructor(opt_options?: olx.interaction.PointerOptions); } - + /** + * Interaction for selecting vector features. By default, selected features are styled differently, so this interaction can be used + * for visual highlighting, as well as selecting features for other actions, such as modification or output. There are three ways of + * controlling which features are selected: using the browser event as defined by the condition and optionally the toggle, + * add/remove, and multi options; a layers filter; and a further feature filter using the filter option. + * + * Selected features are added to an internal unmanaged layer. + */ class Select extends ol.interaction.Interaction { constructor(opt_options?: olx.interaction.SelectOptions); + /** + * Returns the associated vectorlayer of the (last) selected feature. + * Note that this will not work with any programmatic method like pushing features to collection. + */ getLayer(): ol.layer.Layer; + /** + * Get the selected features. + */ getFeatures(): ol.Collection; } - - class Snap { + /** + * Events emitted by ol.interaction.Select instances are instances of this type. + */ + class SelectEvent extends ol.events.Event { + /** + * Deselectd features array. + */ + deselected: Array; + /** + * Associated ol.MapBrowserEvent. + */ + mapBrowserEvent: ol.MapBrowserEvent; + /** + * Selected features array. + */ + selected: Array; + /** + * The event target. + */ + target: ol.Object; + /** + * The event type. + */ + type: string; + /** + * Stop event propagation. + */ + preventDefault(): void; + /** + * Stop event propagation. + */ + stopPropagation(): void; } - + /** + * Handles snapping of vector features while modifying or drawing them. The features can come from a ol.source.Vector or + * ol.Collection Any interaction object that allows the user to interact with the features using the mouse can benefit + * from the snapping, as long as it is added before. + * + *The snap interaction modifies map browser event coordinate and pixel properties to force the snap to occur + * to any interaction that them. + */ + class Snap extends ol.interaction.Pointer { + constructor(opt_options?: olx.interaction.SnapOptions); + } + /** + * Set of interactions included in maps by default. Specific interactions can be excluded by setting the appropriate option + * to false in the constructor options, but the order of the interactions is fixed. If you want to specify a different order for + * interactions, you will need to create your own ol.interaction.Interaction instances and insert them into a ol.Collection in + * the order you want before creating your ol.Map instance. + */ function defaults(opts: olx.interaction.DefaultsOptions): ol.Collection; - interface DrawGeometryFunctionType { (coordinates: ol.Coordinate[], geom?: ol.geom.Geometry): ol.geom.Geometry; } + /** + * Function that takes coordinates and an optional existing geometry as arguments, and returns a geometry. + * The optional existing geometry is the geometry that is returned when the function is called without a second argument. + */ + interface DrawGeometryFunctionType { (coordinates: ol.Coordinate, geom?: ol.geom.Geometry): ol.geom.Geometry; } + /** + * A function that takes an ol.Feature or ol.render.Feature and an ol.layer.Layer and returns true if the feature + * may be selected or false otherwise. + */ interface SelectFilterFunction { (feature: ol.Feature | ol.render.Feature, layer: ol.layer.Layer): boolean; } + /** + * A function that takes a ol.MapBrowserEvent and two ol.Pixels and returns a {boolean}. + * If the condition is met, true should be returned. + */ + interface DragBoxEndConditionType { + (evt: ol.MapBrowserEvent, startPixel: ol.Pixel, endPixel: ol.Pixel): boolean + } } namespace layer { - /** * Abstract base class; normally only used for creating subclasses and not instantiated in apps. Note that with ol.layer.Base and all its subclasses, any property set in the options is set as a ol.Object property on the layer object, so is observable, and has get/set accessors. */