| type | String |
|---|---|
| default | "pan" |
| init | $( selector ).geomap( { mode: "pan" } ); |
| get | var mode = $( selector ).geomap( "option", "mode" ); |
| set | $( selector ).geomap( "option", "mode", "drawPoint" ); |
The mode option determines how the map responds to user interaction and which events jQuery Geo triggers for the developer.
jQuery Geo puts these modes into four small groups:
Basic modes are most common to what people expect to be able to do with a map: drag it around, zoom it in and out, or just have it sit there an look pretty.
Drag modes disable panning and turn single swipes into shape events.
Draw modes turn user clicks into shape events, panning is allowed.
Measure modes display length and area based on clicks and drags.
You are free to set mode to any other string, this is called custom modes in jQuery Geo and described at the end of this page.
Each mode has a matching property on the cursors option. For example, to change the cursor for drawPoint mode to an I-beam, you can initialize the geomap widget like this:
$( selector ).geomap( { cursors: { drawPoint: "text" } } )
The drawStyle option determines how shapes look while being drawn in all of the draw, drag, and measure modes.
The measureLabels option determines how the text is formatted while using the measure modes.
You can remove a user's ability to pan the map by setting the pannable option to false. Yes, you can disable panning even when mode is set to "pan".
You can shut off mouse wheel scroll in any mode by setting the scroll option to "off".
However, when mode is static, setting panning to true or scroll to "zoom" will not enable panning or mouse wheel zoom. In static mode, the geomap widget ignores the panning and scroll options.
The label containing the measure length or area text has the geo-measure-label CSS class. To change how the measure text looks, you can update properties in that rule:
.geo-measure-label { font-size: 1.5em; }
The default cursor is the default arrow pointer.
The map widget displays tiles and map images as normal but the user cannot interact with them, e.g., the user can't pan or zoom in any way, even if the pannable option is set to true.
As a developer, you can still call geomap methods and set options in order to change the static map's appearance. Events are not triggered when you change the map programmatically.
All regular browser events bubble up to parent elements and eventually the document. No widget-specific events trigger. You are free to handle events on the map div as normal events, e.g., click, but you won't get the geo argument. You can ask the map widget for information such as map locations based on the pixel arguments in the event. See the Inset example for help with this.
The default cursor is an open hand in browsers that support data URIs and a four point arrow otherwise.
The user can drag the map to pan. The map will continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. They can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In pan mode, the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can perform a marquee zoom by clicking and holding one point and dragging the mouse cursor. A box will form. When the user lets go of the mouse, the map will zoom to the closest approximation of the bbox of the drawn shape.
Shingled (dynamic) services are only limited by the ratio between the size of the drawn shape and the map div's current size. Cached services are limited to those as well but also specific map zoom levels so the final bbox will not be as close.
The user can also zoom in or out with the scroll wheel as well as double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
This is not a very useful mode for mobile applications but provides a more exact method of zooming into an area for desktop users who want it.
In zoom mode the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can single-click or tap the map. Apart from the default cursor, this mode is similar to pan in that the user can drag the map to pan. They can zoom in or out with the scroll wheel. They can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In click mode, the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
Similar to zoom, in this mode the user can click and hold one point and then drag the mouse cursor. A box will form. When the user lets go of the mouse, jQuery Geo will trigger a shape event passing a GeoJSON Polygon representation of the dragged bbox as the geo argument. The Polygon object also has the GeoJSON the bbox property.
The user can also click the map instead of dragging a box. In this case, jQuery Geo will still trigger a shape event, but this time it will pass a GeoJSON Point representing the clicked location. The Point object will also have the bbox property with the min and max values matching each other, i.e., bbox[0] (minx) = bbox[2] (maxx) and bbox[1] (miny) = bbox[3] (maxy).
The user cannot pan the map while in dragBox mode. The user can zoom in or out with the scroll wheel as well as double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In dragBox mode the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can click and hold one point and then drag the mouse cursor. A circle will form from the center outward. When the user lets go of the mouse, jQuery Geo will trigger a shape event passing a GeoJSON Polygon representation of the dragged circle as the geo argument. The Polygon object also has the GeoJSON the bbox property.
The user can also click the map instead of dragging a circle. In this case, jQuery Geo will still trigger a shape event, but this time it will pass a GeoJSON Point representing the clicked location. The Point object will also have the bbox property with the min and max values matching each other, i.e., bbox[0] (minx) = bbox[2] (maxx) and bbox[1] (miny) = bbox[3] (maxy).
The user cannot pan the map while in dragCircle mode. The user can zoom in or out with the scroll wheel as well as double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In dragCircle mode the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can digitize a Point shape by single-clicking or tapping the map. Apart from the default cursor, this mode is similar to pan in that the user can drag the map to pan. However, to allow a user more accuracy during digitization, the map will not continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. They can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
A visual point will appear temporarily until they either let go to draw the point or begin panning.
The user can hold the shift key to temporarily switch to zoom mode.
In drawPoint mode, the geomap widget triggers the following events on the original map div. Note that the shape event replaces the click event.
The default cursor is a crosshair.
In this mode the user can digitize a LineString shape. The first single-click or tap on the map will begin the shape drawing. Once initialized, subsequent single-clicks will add points to the LineString. Finally, a double-click or tap will end the digitization and trigger the shape event.
On a non-touch device a visual line will follow the mouse cursor from the last point to show the user the next segment of the line they will draw. On all devices, the next segment becomes visible when the user confirms the next point location by clicking or tapping. At any point, the user can hit the escape key to remove one point or, if there is only one point, stop drawing the shape alltogether.
Similar to pan mode, the user can drag the map to pan, even while drawing a shape. However, to allow a user more accuracy during digitization, the map will not continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. While not drawing, they can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In drawLineString mode, the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can digitize a Polygon shape. The first single-click or tap on the map will begin the shape drawing. Once initialized, subsequent single-clicks will add points to the Polygon. Finally, a double-click or tap will end the digitization and trigger the shape event.
On a non-touch device two visual lines will follow the mouse cursor. One from the last point to show the user the next segment of the Polygon they will draw, the other from the first point to show the user an extra segment that will complete the Polygon. On all devices, the next segment becomes visible when the user confirms the next point location by clicking or tapping. At any point, the user can hit the escape key to remove one point or, if there is only one point, stop drawing the shape alltogether.
Similar to pan mode, the user can drag the map to pan, even while drawing a shape. However, to allow a user more accuracy during digitization, the map will not continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. While not drawing, they can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
In drawPolygon mode, the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can visually measure the length of lines on the map. The first single-click or tap on the map will begin the measurement. Once initialized, subsequent single-clicks or taps will add points to a LineString being measured. Whenever the mouse moves, a label follows the cursor which displays the total length so far. Touch devices will only see an updated measurment when they add a new point. A double-click or tap will end the measurement and remove all graphics and labels.
On a non-touch device a visual line will follow the mouse cursor from the last point to show the user the next segment of the line they are measuring and update the measurement. On all devices, the next segment becomes visible when the user confirms the next point location by clicking or tapping. At any point, the user can hit the escape key to remove one point or, if there is only one point, stop measuring alltogether.
Similar to pan mode, the user can drag the map to pan, even while measuring. The map will continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. While not measuring, they can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
By default the unit of measurment is meters because the default projection is web mercator meters. If you change the tilingScheme (on tiled services) or switch to a shingled service, the unit of measurment will be based on your new service's units.
In measureLength mode, the geomap widget triggers the following events on the original map div.
The default cursor is a crosshair.
In this mode the user can visually measure an area on the map. The first single-click or tap on the map will begin the measurement. Once initialized, subsequent single-clicks or taps will add points to a Polygon being measured. Whenever the mouse moves, a label follows the center of the polygon that displays the total area so far. Touch devices will only see an updated measurment when they add a new point. A double-click or tap will end the measurement and remove all graphics and labels.
On a non-touch device two visual lines will follow the mouse cursor. One from the last point to show the user the next segment of the Polygon they will draw, the other from the first point to show the user an extra segment that will complete the Polygon we need to calculate area. On all devices, the next segment becomes visible when the user confirms the next point location by clicking or tapping. At any point, the user can hit the escape key to remove one point or, if there is only one point, stop measuring alltogether.
Similar to pan mode, the user can drag the map to pan, even while measuring. The map will continue panning a little after the user lets go. They can zoom in or out with the scroll wheel. While not measuring, they can also double-click or double-tap to zoom in one level. On some multitouch devices, users can use two fingers to "pinch zoom" (currently not available on Android).
The user can hold the shift key to temporarily switch to zoom mode.
By default the unit of measurment is meters because the default projection is web mercator meters. If you change the tilingScheme (on tiled services) or switch to a shingled service, the unit of measurment will be based on your new service's units.
In measureArea mode, the geomap widget triggers the following events on the original map div.
As mentioned above, you can also set mode to any other string. It will behave exactly like pan mode. However, you can set a different cursor:
var map = $( "#map" ).geomap( {
mode: "click",
cursors: { click: "crosshair" }
} );
The above example creates a new custom mode, click, and sets the geomap widget to that mode during initialization. When the widget is in this mode, it will behave exactly like pan, but have a crosshair. This means you will get all the same events as pan: move, click, dblclick & bboxchange. A mode like this is useful if you want to give users more accuracy when clicking the map.
Custom modes will still allow panning. While panning, the cursor will temporarily switch to the pan cursor. You can disable panning for your mode by setting the widget's panning option to false whenever you change the mode option.
function setMode( mode ) {
map.geomap( "option", {
mode: mode,
panning: mode !== "click"
} );
}
In this last example, we create a new map with two modes, find and remove. They both trigger the click event so we can check our current mode and behave differently depending on which one is set, or do nothing if we're not in find or remove mode.
var map = $( "#map" ).geomap( {
mode: "drawPoint",
cursors: {
find: "crosshair",
remove: "crosshair"
},
shape: function( e, geo ) {
// only the draw modes trigger this event
map.geomap( "append", geo );
},
click: function( e, geo ) {
switch( map.geomap( "option", "mode" ) ) {
case "find":
// search for shapes but just alert the user
var shapes = map.geomap( "find", geo, 3 );
if ( shapes.length > 0 ) {
alert( "Found " + shapes.length + " shape(s) !" );
}
break;
case "remove":
// search for shapes and remove one of them
var shapes = map.geomap( "find", geo, 3 );
if ( shapes.length > 0 ) {
map.geomap( "remove", shapes[ 0 ] );
}
break;
default:
// ignore the click event for all other modes: pan, zoom, etc.
break;
}
}
} );