Developer Guide

Feature Events

There are a few ways of handling events on features, each of which is suited best for specific tasks. For the most part you will be using the ALKMaps.Control.SelectFeature and ALKMaps.Control.FeatureEvent controls for handling these events. Please note that this does not include markers, any attempt to use these controls on a ALKMaps.Layer.Markers layer or ALKMaps.Marker object will not work.

Special Cases

Please note that the FeatureEvent and SelectFeature controls must be deactivated in order to perform certain actions on a layer. For example the control will need to be temporarily deactivated in order to be able to use a layer's setOpacity function. The control must also be deactivated in order to set a layer's z-index.

SelectFeature Control

The ALKMaps.Control.SelectFeature is best suited for actually selecting one or more features on hover, click, or drag box. The default functionality of this control is to simply highlight any selected features using a predetermined style object. You also have ability to use a custom style object for highlighting a feature when it is selected, or you can choose to not highlight the features at all. Another useful feature of this control is an optional set of user defined functions to be called right before a feature is selected, on selection, and on unselection; as well as triggering "beforefeatureselected", "featureselected", and "featureunselected" events respectively.

SelectFeature Parameters

Parameter	Type	Description/Values
`multipleKey`	`String`	An event modifier ('altKey' or 'shiftKey') that temporarily sets the `multiple` property to true. Default is null.
`toggleKey`	`String`	An event modifier ('altKey' or 'shiftKey') that temporarily sets the `toggle` property to true. Default is null.
`multiple`	`Boolean`	Allow selection of multiple geometries. Default is false.
`clickout`	`Boolean`	Unselect features when clicking outside any feature. Default is true.
`toggle`	`Boolean`	Unselect a selected feature on click. Default is false. Only has meaning if hover is false.
`hover`	`Boolean`	Select on mouse over and deselect on mouse out. If true, this ignores clicks and only listens to mouse moves. Default is false.
`highlightOnly`	`Boolean`	If true do not actually select features (that is place them in the layer's selected features array), just highlight them. This property has no effect if hover is false. Defaults to false.
`box`	`Boolean`	Allow feature selection by drawing a box.
`onBeforeSelect`	`Function`	Optional function to be called before a feature is selected. The function should expect to be called with a feature.
`onSelect`	`Function`	Optional function to be called when a feature is selected. The function should expect to be called with a feature.
`onUnselect`	`Function`	Optional function to be called when a feature is unselected. The function should expect to be called with a feature.
`scope`	`Object`	The scope to use with the onBeforeSelect, onSelect, onUnselect callbacks. If null the scope will be this control.
`geometryTypes`	`Array(String)`	To restrict selecting to a limited set of geometry types, send a list of strings corresponding to the geometry class names.
`layers`	`Array(ALKMaps.Layer.Vector \| ALKMaps.Layer.VectorMarkers)`	The layers this control will work on.
`selectStyle`	`Object`	Hash of styles to be used for feature selection.

Click The Point To Highlight It

var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {style:ALKMaps.STYLE.LIGHTNESS}, {displayInLayerSwitcher: false});
var vectorLayer = new ALKMaps.Layer.Vector("Vector Layer");
map.addLayers([layer, vectorLayer]);

var center = new ALKMaps.LonLat(-96, 38).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
map.setCenter(center, 4);
                    
var pointFeature = new ALKMaps.Feature.Vector(
	new ALKMaps.Geometry.Point(-96, 38).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject()), 
	null,
	{
		pointRadius: 25,
		fillColor: "#4444FF",
        strokeColor: "#0000CC"
	}
);

vectorLayer.addFeatures([pointFeature]);
                    
var select =  new ALKMaps.Control.SelectFeature(
    vectorLayer,
    {
        multiple: false, hover: false,
        toggleKey: "ctrlKey", // ctrl key removes from selection
        multipleKey: "shiftKey", // shift key adds to selection
        selectStyle: {
            pointRadius: 30,
            fillColor: "#33CCFF",
            strokeColor: "#0099FF"          
        }
    }
);
map.addControl(select);
select.activate();

FeatureEvent Control

The ALKMaps.Control.FeatureEvent control is very useful for detecting mouse events on a feature and triggering a corresponding event. The FeatureEvent control has a couple significant advantages over the SelectFeature control. When dealing with multiple layers, it is important to note that the FeatureEvent control gives you the ability to handle these events on a per layer basis by only triggering the event on the layer which the feature is from. Another exciting aspect is the control's ability to filter out specific features by attribute and have the control ignore the rest. This control now also supports right click events on features. The following table outlines the list of supported events for the FeatureEvent control.

Supported Events
Event	Description
featureclicked	Triggered when a feature is clicked.
featurerightclicked	Triggered when a feature is right clicked.
featureclickedout	Triggered when there is a click outside of a feature after a "featureclicked" or "featurerightclicked" event has been triggered for that feature. Last stored feature will be returned in the event.
featurerightclickedout	Triggered when there is a right click outside of a feature after a "featureclicked" or "featurerightclicked" event has been triggered for that feature. Last stored feature will be returned in the event.
overFeature	Triggered when mouse over a feature.
outFeature	Triggered when mouse out a feature.

Hover Over The Left Point To Remove It

As you can see in the sample below, the event can be registered to the specific layer preventing features on other layers from interfering. This FeatureEvent in this sample also uses the featureAttributesFilter option so that only features containing the eventDetection attribute with a value of true will trigger the "overFeature" event.

var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {style:ALKMaps.STYLE.LIGHTNESS}, {displayInLayerSwitcher: false});
var vectorLayer = new ALKMaps.Layer.Vector("Vector Layer");
map.addLayers([layer, vectorLayer]);
var center = new ALKMaps.LonLat(-96, 38).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
map.setCenter(center, 4);
                    
vectorLayer.events.register("overFeature",this,function(event){
   vectorLayer.removeFeatures(event.feature);                 
});
var style =  {
	pointRadius: 25,
	fillColor: "#4444FF",
    strokeColor: "#0000CC"
};
var point = new ALKMaps.Geometry.Point(-96, 38).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
var point2 = new ALKMaps.Geometry.Point(-110, 38).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());                                       
var pointFeature = new ALKMaps.Feature.Vector(point, {eventDetection: false}, style);                 
var pointFeature2 = new ALKMaps.Feature.Vector(point2, {eventDetection: true}, style);
vectorLayer.addFeatures([pointFeature, pointFeature2]);
                    
var featureEvent = new ALKMaps.Control.FeatureEvent([vectorLayer],
    {
        featureAttributesFilter: [{ property: 'eventDetection', value: true }]
    });
map.addControls([featureEvent]);
featureEvent.activate();