# geomap widget

Once you have an HTML element to target, you can call the geographic map widget's function.

    .geomap( options )

## overview

The widget creates an interactive map. Users can pan and zoom on desktop and mobile browsers against many different cached tile sets or dynamic map servers. Developers can handle events triggered by user action.

## options

The options argument is a JavaScript object that configures the map widget during the first instantiation on a div. No options are required. By default the map will show the whole world using the mapquest open tile set.

After initializing a map with your first geomap call, you can get or set most of these options using the following syntax:

    // get the current value of a single option
    var optionValue = $( map selector ).geomap( "option", optionName );

    // set a new value for a single option
    $( map selector ).geomap( "option", optionName, newValue );

    // set new values for multiple options at the same time
    $( map selector ).geomap( "option", {
      optionName: newValue,
      optionName: newValue
    } );

One exception is pixelSize, which is read-only.

The map view refreshes when you change these options: bbox, center, services, tilingScheme, bboxMax, & zoom.

- ### bbox

  bounds of the currently visible viewport

- ### bboxMax

  bounds of maximum viewport for non-tiled maps

- ### center

  center of the currently visible viewport

- ### zoom

  zoom level of the currently visible viewport

- ### zoomMin

  minimum zoom level for all services in the map

- ### zoomMax

  maximum zoom level for all services in the map

- ### pixelSize

  read-only Earth-size of a pixel in the current map viewport

- ### mode

  determines how the map, user, & developer interact

- ### pannable

  allow or prohit map panning

- ### scroll

  determines how the map reacts to a mouse wheel

- ### shift

  determines how holding the shift key affects the map

- ### cursors

  cursors to display for each mode

- ### measureLabels

  format to apply to label while measuring

- ### drawStyle

  when drawing shapes, defines how they look during drawing

- ### shapeStyle

  defines how geomap draws shapes added via the append method

- ### services

  determine the content of the map

- ### tilingScheme

  defines how tiles are placed in the viewport

- ### axisLayout

  "map" or "image"

## projection

The geomap widget will match how you use projection with map units. The map unit type (projected or geodetic) you used when you last set the bbox, bboxMax, or the center option will be used as output for options and as values for arguments. If you never set the bbox or center options, the geomap widget will return geodetic coordinates.

For example, if you set the map's center option using geodetic coordinates (a longitude, latitude array), future requests for the value of the map's center or bbox options will be returned in geodetic coordinates. However, if you later set the bbox option using web mercator, future requests for the center or bbox options will be returned in that projection.

Changing bbox or center will affect all options and arguments that use map units. The options and arguments involved are:

- bbox option
- bboxMax option
- center option
- bbox property of the services object's src argument
- GeoJSON objects passed as the geo argument in all events
- return value of the toMap method

To avoid confusion, it is recommended to stick to one map unit type for any single map widget.

The geomap widget will use the $.geo.proj object when needed to convert between geodetic and projected coordinates.

## events

All event callbacks receive two arguments: the original browser event and an object specific to the map action.

The map unit type (projected or geodetic) of the map event arguments depends on the way you initialize the map widget. If you have set the center or bbox option using geodetic coordinates, the event arguments will also be in geodetic coordinates.

Like jQuery UI widgets, geomap triggers events directly on the original map div.

Programatic changes to options do not trigger events.

The dblclick event is special in that you can prevent the default action, zoom-in one level, by calling e.preventDefault() in your callback. This is currently the only geomap event that you can prevent the default action. Calling preventDefault in the callback of any other geomap event has undefined results.

There are four geomap event types. The type of event determines what is sent to your event handler as the second argument, geo.

### position events

With position events the geo argument to your callback is a GeoJSON Point object having two properties: type & coordinates. The coordinates property is a single GeoJSON position, i.e., an array containing the x/longitude and y/latitude value.

The geo argument to your callback is a true GeoJSON object and you can pass this object directly to the append method. You can also send it directly to a database for storage knowing that there are no non-GeoJSON properties wasting space.

- move
- click
- dblclick

### bbox events

With bbox events the geo argument to your callback is an object with single property, bbox, which is a GeoJSON bounding box.

- bboxchange

### shape events

With shape events, the geo argument to your callback is a GeoJSON geometry object having two properties: type & coordinates. The object type will be either Point, LineString or Polygon depending on the current geomap mode: measureLength, measureArea, drawPoint, drawLineString, and drawPolygon.

The geo argument to your callback is a true GeoJSON object and you can pass this object directly to the append method. You can also send it directly to a database for storage knowing that there are no non-GeoJSON properties wasting space.

- shape

### load events

With load events, the geo argument is currently undefined. You can add the argument to your handler's argument list if you wish but attempting to access any property on it will cause a JavaScript error.

- loadstart
- loadend

## methods

The geomap widget provides some methods to help make interacting map data a little easier.

### unit conversion

Convert positions between pixel and map coordinates.

- toMap
- toPixel

### map methods

These methods update the map widget as a whole.

- zoom
- refresh
- resize
- destroy

### service modification

Methods that help update objects in the services array.

- toggle
- opacity

### shapes

These methods manage geometry or features drawn on the geomap widget itself or on individual servies within the map.

- append
- remove
- empty

The find method allows you to search for shapes appended to the map. Its syntax and service-level operation is slightly different than the other three shape methods so the link is visually broken out from the rest.

- find

## style

A geomap style is an object whose properties follow a subset of SVG styling properties. The specific styles that geomap recognizes and to which geometry they apply are listed below.

Use the drawStyle option of the geomap widget to define the style used on incomplete lines and polygons as they are being drawn when mode is drawLineString or drawPolygon.

Use the shapeStyle option to define the style of shapes drawn after being appended to the map via the append method.

Please note that in drawPoint mode, the shape event is triggered immediately and so no shape will appear until you append a point to the map at which time the shapeStyle will be used.

### geomap style properties

property | default | description
--- | --- | ---
borderRadius | "8px" | The radii of a quarter ellipse that defines the shape of the corner of the outer border of a box drawn around Point shapes, which means it turns your boxes into curved rectangles. If the width, height and borderRadius properties of a style are the same (the default), the point is drawn as a circle.
color | #7f0000 | An indirect, fallback value for the fill and stroke properties if they are not set.
fill | undefined | Color to use when drawing the interior of a shape. The area to be drawn consists of any areas inside the outline of the shape. By default, fill will use the value of the color property.
fillOpacity | .2 | Specifies the opacity of the drawing operation used to draw the interior of a shape. The final fill opacity also depends on the value of the opacity property.
height | "8px" | The height of a box drawn around Point shapes. Currently only pixel values are allowed. If either width or height are zero, no shape is drawn for the Point.
opacity | 1 | The object opacity of the entire shape. This is a multiplicative operation when determining the final fillOpacity and strokeOpacity where any fill or stroke operation is made even more translucent if this value is below 1.0.
stroke | undefined | Color to use when drawing along the outline of a shape. By default, stroke will use the value of the color property.
strokeOpacity | 1 | Specifies the opacity of the drawing operation used to draw the outline of a shape. The final stroke opacity also depends on the value of the opacity property.
strokeWidth | "2px" | The width of the stroke of a shape. A zero value causes no stroke to be drawn. Currently only pixel values are allowed.
visibility | "visible" | Determines if the shape is drawn ("visible") or not drawn ("hidden") on the map. Shapes that are hidden can still be returned by the find method.
width | "8px" | The width of a rounded rectangle drawn around Point shapes. Currently only pixel values are allowed. If either width or height are zero, no shape is drawn for the Point.

All properties apply to Point shapes which means that you can adjust the stroke and fill of the box surrounding the point location.