libs/js/jquery-geo-1.0a4/docs/geomap/index.html

   1 <!doctype html>
   2
   3 <html lang="en" class="no-js">
   4 <head>
   5   <meta charset="utf-8">
   6
   7   <title>geomap | jQuery Geo</title>
   8   <meta name="description" content="jQuery Geo geomap widget">
   9   <meta name="author" content="Ryan Westphal">
  10
  11   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  12
  13   <link rel="stylesheet" href="../css/style.css?v=2">
  14   <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
  15 </head>
  16
  17 <body>
  18
  19   <div id="geomap" data-role="page">
  20     <div data-role="header" data-theme="d">
  21       <h1>geomap widget</h1>
  22     </div>
  23
  24     <div data-role="content">
  25       <p>Once you have an HTML element to target, you can call the geographic map widget's function.</p>
  26
  27       <pre><code>.geomap( options )</code></pre>
  28
  29       <h2>overview</h2>
  30
  31       <p>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.</p>
  32
  33       <div class="geomap-indoc"></div>
  34
  35       <h2>options</h2>
  36
  37       <p>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 OpenStreetMap tile set.</p>
  38
  39       <p>After initializing a map with your first geomap call, you can get or set most of these options using the following syntax:</p>
  40
  41       <pre><code><span class="comment">// get the current value of a single option</span>
  42 var optionValue = $( <i>map selector</i> ).geomap( &quot;option&quot;, <i>optionName</i> );
  43
  44 <span class="comment">// set a new value for a single option</span>
  45 $( <i>map selector</i> ).geomap( &quot;option&quot;, <i>optionName</i>, <i>newValue</i> );
  46
  47 <span class="comment">// set new values for multiple options at the same time</span>
  48 $( <i>map selector</i> ).geomap( &quot;option&quot;, {
  49   <i>optionName</i>: <i>newValue</i>,
  50   <i>optionName</i>: <i>newValue</i>
  51 } );</code></pre>
  52
  53       <p>One exception is pixelSize, which is read-only.</p>
  54
  55       <p>The map view refreshes when you change these options: bbox, center, services, tilingScheme &amp; zoom.</p>
  56
  57       <ul data-role="listview" data-inset="true">
  58         <li><a href="bbox.html"><h3>bbox</h3><p>bounds of the currently visible viewport</p></a></li>
  59         <li><a href="bboxMax.html"><h3>bboxMax</h3><p>bounds of maximum viewport for non-tiled maps</p></a></li>
  60         <li><a href="center.html"><h3>center</h3><p>center of the currently visible viewport</p></a></li>
  61         <li><a href="zoom.html"><h3>zoom</h3><p>zoom level of the currently visible viewport</p></a></li>
  62         <li><a href="pixelSize.html"><h3>pixelSize</h3><p>read-only Earth-size of a pixel in the current map viewport</p></a></li>
  63         <li><a href="mode.html"><h3>mode</h3><p class="ui-li-desc">determines how the map, user, &amp; developer interact</p></a></li>
  64         <li><a href="pannable.html"><h3>pannable</h3><p class="ui-li-desc">allow or prohit map panning</p></a>
  65         <li><a href="scroll.html"><h3>scroll</h3><p class="ui-li-desc">determines how the map reacts to a mouse wheel</p></a>
  66         <li><a href="cursors.html"><h3>cursors</h3><p>cursors to display for each mode</p></a></li>
  67         <li><a href="measureLabels.html"><h3>measureLabels</h3><p>format to apply to label while measuring</p></a></li>
  68         <li><a href="drawStyle.html"><h3>drawStyle</h3><p>when drawing shapes, defines how they look during drawing</p></a></li>
  69         <li><a href="shapeStyle.html"><h3>shapeStyle</h3><p>defines how geomap draws shapes added via the append method</p></a></li>
  70         <li><a href="services.html"><h3>services</h3><p>determine the content of the map</p></a></li>
  71         <li><a href="tilingScheme.html"><h3>tilingScheme</h3><p>defines how tiles are placed in the viewport</p></a></li>
  72         <li><a href="axisLayout.html"><h3>axisLayout</h3><p>&quot;map&quot; or &quot;image&quot;</p></a></li>
  73       </ul>
  74       <h2>projection</h2>
  75       <p>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 either the <b>bbox</b> or the <b>center</b> 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.</p>
  76       <p>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.</p>
  77       <p>Changing bbox or center will affect all options and arguments that use map units. The options and arguments involved are:</p>
  78       <ul>
  79         <li>bbox option</li>
  80         <li>bboxMax option</li>
  81         <li>center option</li>
  82         <li>bbox property of the services object's src argument</li>
  83         <li>GeoJSON objects passed as the geo argument in all events</li>
  84         <li>return value of the toMap method</li>
  85       </ul>
  86       <p>To avoid confusion, it is recommended to stick to one map unit type for any single map widget.</p>
  87       <p>The geomap widget will use $.geo.proj when needed to convert between geodetic and projected coordinates.</p>
  88       <h2>events</h2>
  89       <p>All event callbacks receive two arguments: the original browser event and an object specific to the map action.</p>
  90       <p>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.</p>
  91       <p>Like jQuery UI widgets, geomap triggers events directly on the original map div.</p>
  92       <p>Programatic changes to options do not trigger events.</p>
  93       <p>The dblclick event is special in that you can prevent the default action,
  94         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.</p>
  95       <p>There are three geomap event <i>types</i>. The type of event determines what is sent to your event handler as the second argument, geo.</p>
  96       <h3>position events</h3>
  97       <p>With position events the geo argument to your callback is a <a href="http://geojson.org/geojson-spec.html#point" rel="external">GeoJSON Point</a> object having two properties: type &amp; coordinates. The coordinates property is a single <a href="http://geojson.org/geojson-spec.html#positions" rel="external">GeoJSON position</a>, i.e., an array containing the x/longitude and y/latitude value.</p>
  98       <p>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.</p>
  99       <ul data-role="listview" data-inset="true">
 100         <li>
 101             <a href="geomapmove.html">move</a>
 102         </li>
 103         <li>
 104             <a href="geomapclick.html">click</a>
 105         </li>
 106         <li>
 107             <a href="geomapdblclick.html">dblclick</a>
 108         </li>
 109       </ul>
 110       <h3>bbox events</h3>
 111       <p>With bbox events the geo argument to your callback is an object with single property, bbox, which is a <a href="http://geojson.org/geojson-spec.html#bounding-boxes" rel="external">GeoJSON bounding box</a>.</p>
 112       <ul data-role="listview" data-inset="true">
 113         <li>
 114             <a href="geomapbbox.html">bboxchange</a>
 115         </li>
 116       </ul>
 117       <h3>shape events</h3>
 118       <p>With shape events, the geo argument to your callback is a GeoJSON geometry object having two properties: type &amp; coordinates. The object type will be either Point, LineString or Polygon depending on the current geomap mode: drawPoint, drawLineString, or drawPolygon.</p>
 119       <p>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.</p>
 120       <ul data-role="listview" data-inset="true">
 121         <li>
 122             <a href="geomapshape.html">shape</a>
 123         </li>
 124       </ul>
 125       <h2>methods</h2>
 126       <p>The geomap widget provides some methods to help make interacting map data a little easier.</p>
 127       <h3>unit conversion</h3>
 128       <p>Convert positions between pixel and map coordinates.</p>
 129       <ul data-role="listview" data-inset="true">
 130         <li>
 131           <a href="toMap.html">toMap</a>
 132         </li>
 133         <li>
 134           <a href="toPixel.html">toPixel</a>
 135         </li>
 136       </ul>
 137       <h3>map methods</h3>
 138       <p>These methods update the map widget as a whole.</p>
 139       <ul data-role="listview" data-inset="true">
 140         <li>
 141           <a href="zoomMethod.html">zoom</a>
 142         </li>
 143         <li>
 144           <a href="refresh.html">refresh</a>
 145         </li>
 146         <li>
 147           <a href="resize.html">resize</a>
 148         </li>
 149         <li>
 150           <a href="destroy.html">destroy</a>
 151         </li>
 152       </ul>
 153       <h3>service modification</h3>
 154       <p>Methods that help update objects in the services array.</p>
 155       <ul data-role="listview" data-inset="true">
 156         <li>
 157           <a href="toggle.html">toggle</a>
 158         </li>
 159         <li>
 160           <a href="opacity.html">opacity</a>
 161         </li>
 162       </ul>
 163       <h3>shapes</h3>
 164       <p>These methods manage geometry or features drawn on the geomap widget itself or on individual servies within the map.</p>
 165       <ul data-role="listview" data-inset="true">
 166         <li><a href="append.html">append</a></li>
 167         <li><a href="remove.html">remove</a></li>
 168         <li><a href="empty.html">empty</a></li>
 169       </ul>
 170       <p>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.</p>
 171       <ul data-role="listview" data-inset="true">
 172         <li><a href="find.html">find</a></li>
 173       </ul>
 174       <h2>style</h2>
 175       <p>A geomap style is an object whose properties follow a subset of <a href="http://www.w3.org/TR/SVG/styling.html">SVG styling</a> properties. The specific styles that geomap recognizes and to which geometry they apply are listed below.</p>
 176       <p>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.</p>
 177       <p>Use the shapeStyle option to define the style of shapes drawn after being appended to the map via the append method.</p>
 178       <p>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.</p>
 179       <h3>geomap style properties</h3>
 180       <table class="objectProperties">
 181         <tr>
 182           <th>property</th>
 183           <th>default</th>
 184           <th>description</th>
 185         </tr>
 186         <tr>
 187           <td>borderRadius</td>
 188           <td>&quot;8px&quot;</td>
 189           <td>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.</td>
 190         </tr>
 191         <tr>
 192           <td>color</td>
 193           <td>#7f0000</td>
 194           <td>An indirect, fallback value for the fill and stroke properties if they are not set.</td>
 195         </tr>
 196         <tr>
 197           <td>fill</td>
 198           <td>undefined</td>
 199           <td>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.</td>
 200         </tr>
 201         <tr>
 202           <td>fillOpacity</td>
 203           <td>.2</td>
 204           <td>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.</td>
 205         </tr>
 206         <tr>
 207           <td>height</td>
 208           <td>&quot;8px&quot;</td>
 209           <td>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.</td>
 210         </tr>
 211         <tr>
 212           <td>opacity</td>
 213           <td>1</td>
 214           <td>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.</td>
 215         </tr>
 216         <tr>
 217           <td>stroke</td>
 218           <td>undefined</td>
 219           <td>Color to use when drawing along the outline of a shape. By default, stroke will use the value of the color property.</td>
 220         </tr>
 221         <tr>
 222           <td>strokeOpacity</td>
 223           <td>1</td>
 224           <td>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.</td>
 225         </tr>
 226         <tr>
 227           <td>strokeWidth</td>
 228           <td>&quot;2px&quot;</td>
 229           <td>The width of the stroke of a shape. A zero value causes no stroke to be drawn. Currently only pixel values are allowed.</td>
 230         </tr>
 231         <tr>
 232           <td>visibility</td>
 233           <td>&quot;visible&quot;</td>
 234           <td>Determines if the shape is drawn (&quot;visible&quot;) or not drawn (&quot;hidden&quot;) on the map. Shapes that are hidden can still be returned by the find method.</td>
 235         </tr>
 236         <tr>
 237           <td>width</td>
 238           <td>&quot;8px&quot;</td>
 239           <td>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.</td>
 240         </tr>
 241       </table>
 242       <p>All properties apply to Point shapes which means that you can adjust the stroke and fill of the box surrounding the point location.</p>
 243     </div>
 244   </div> <!-- end of #container -->
 245
 246   <script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
 247   <script src="http://code.jquerygeo.com/jquery.geo-1.0a4.min.js"></script>
 248   <script src="../js/script.js"></script>
 249   <script src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
 250 </body>
 251 </html>
 252