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

   1 <!doctype html>
   2
   3 <html lang="en" class="no-js">
   4 <head>
   5   <meta charset="utf-8">
   6
   7   <title>mode | geomap</title>
   8   <meta name="description" content="geomap mode option">
   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="mode" data-role="page">
  20     <div data-role="header" data-theme="f">
  21       <h1>mode</h1>
  22     </div>
  23
  24     <div data-role="content">
  25       <table>
  26         <tr>
  27           <th>type</th>
  28           <td>String</td>
  29         </tr>
  30         <tr>
  31           <th>default</th>
  32           <td>&quot;pan&quot;</td>
  33         </tr>
  34         <tr>
  35           <th>init</th>
  36           <td><pre><code>$( <i>selector</i> ).geomap( { mode: &quot;pan&quot; } );</code></pre></td>
  37         </tr>
  38         <tr>
  39           <th>get</th>
  40           <td><pre><code>var mode = $( <i>selector</i> ).geomap( &quot;option&quot;, &quot;mode&quot; );</code></pre></td>
  41         </tr>
  42         <tr>
  43           <th>set</th>
  44           <td><pre><code>$( <i>selector</i> ).geomap( &quot;option&quot;, &quot;mode&quot;, &quot;drawPoint&quot; );</code></pre></td>
  45         </tr>
  46       </table>
  47       <p>The mode option determines how the map responds to user interaction and which events the developer receives.</p>
  48
  49       <p>The current list of built-in modes is:</p>
  50       <ul>
  51         <li>static</li>
  52         <li>pan</li>
  53         <li>zoom</li>
  54         <li>drawPoint</li>
  55         <li>drawLineString</li>
  56         <li>drawPolygon</li>
  57         <li>measureLength</li>
  58         <li>measureArea</li>
  59       </ul>
  60
  61       <p>You are free to set mode to any other string, this is called <a href="javascript:document.getElementById('custom-modes').scrollIntoView();" rel="external">custom modes</a> in jQuery Geo and described at the end of this page.</p>
  62
  63       <h2>options</h2>
  64       <p>Each mode has a matching property on the <a href="cursors.html">cursors</a> option. For example, to change the cursor for drawPoint mode to an I-beam, you can initialize the geomap widget like this:</p>
  65       <pre><code>$( <i>selector</i> ).geomap( { cursors: { drawPoint: &quot;text&quot; } } )</code></pre>
  66
  67       <p>The <a href="drawStyle.html">drawStyle</a> option determines how shapes look while being drawn in all of the draw modes and all of the measure modes.</p>
  68
  69       <p>The <a href="measureLabels.html">measureLabels</a> option determines how the text is formatted while using the measure modes.</p>
  70
  71       <p>You can remove a user's ability to pan the map by setting the <a href="panning.html">panning</a> option to false. Yes, you can disable panning even when mode is set to &quot;pan&quot;.<p>
  72
  73       <p>You can shut off mouse wheel scroll in any mode by setting the <a href="scroll.html">scroll</a> option to &quot;off&quot;.</p>
  74
  75       <p>However, when mode is static, setting panning to true or scroll to &quot;zoom&quot; will not enable panning or mouse wheel zoom. In static mode, the geomap widget ignores the panning and scroll options.</p>
  76
  77       <h2>style</h2>
  78       <p>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:</p>
  79
  80       <pre><code>.geo-measure-label { font-size: 1.5em; }</code></pre>
  81
  82       <h2>static</h2>
  83
  84       <h3>user experience</h3>
  85       <p>The default cursor is the default arrow pointer.</p>
  86       <p>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 <a href="pannable.html">pannable</a> option is set to true.</p>
  87
  88       <p>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.</p>
  89
  90       <h3>events</h3>
  91       <p>All regular browser events bubble up to parent controls and eventually the document. No widget-specific events trigger.</p>
  92
  93       <h2>pan</h2>
  94       <h3>user experience</h3>
  95       <p>The default cursor is an open hand in browsers that support data URIs and a four point arrow otherwise.</p>
  96
  97       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
  98
  99       <h3>events</h3>
 100       <p>In pan mode, the geomap widget triggers the following events on the original map div.</p>
 101       <ul>
 102         <li>move &ndash; when the user moves the mouse above the map but is not actively panning</li>
 103         <li>click &ndash; when the user clicks or taps a point on the map without initiating a pan, i.e., they let go of the map at the same point and within a short time threshold</li>
 104         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map</li>
 105         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 106       </ul>
 107
 108       <h2>zoom</h2>
 109
 110       <h3>user experience</h3>
 111       <p>The default cursor is a crosshair.</p>
 112
 113       <p>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.</p>
 114       <p>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.</p>
 115       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 116       <p>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.</p>
 117
 118       <h3>events</h3>
 119       <p>In zoom mode the geomap widget triggers the following events on the original map div.</p>
 120       <ul>
 121         <li>move &ndash; when the user moves the mouse above the map but is not actively performing a marquee zoom</li>
 122         <li>click &ndash; when the user clicks or taps a point on the map without initiating a marquee zoom, i.e., they let go of the map at the same point and within a short time threshold</li>
 123         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map</li>
 124         <li>bboxchange &ndash; when the user changes the bbox by zooming</li>
 125       </ul>
 126
 127       <h2>drawPoint</h2>
 128
 129       <h3>user experience</h3>
 130       <p>The default cursor is a crosshair.</p>
 131
 132       <p>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.</p>
 133
 134       <p>A visual point will appear temporarily until they either let go to draw the point or begin panning.</p>
 135
 136       <p>Similar to pan mode, 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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 137
 138       <h3>events</h3>
 139       <p>In drawPoint mode, the geomap widget triggers the following events on the original map div. Note that the shape event replaces the click event.</p>
 140       <ul>
 141         <li>move &ndash; when the user moves the mouse above the map but is not actively panning</li>
 142         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map</li>
 143         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 144         <li>shape &ndash; when the user clicks or taps a point on the map, this action will send a GeoJSON Point object to the developer</li>
 145       </ul>
 146
 147       <h2>drawLineString</h2>
 148
 149       <h3>user experience</h3>
 150       <p>The default cursor is a crosshair.</p>
 151
 152       <p>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.</p>
 153
 154       <p>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.</p>
 155
 156       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 157
 158       <h3>events</h3>
 159       <p>In drawLineString mode, the geomap widget triggers the following events on the original map div.</p>
 160       <ul>
 161         <li>move &ndash; when the user moves the mouse above the map but is not actively panning, this event triggers even while drawing a shape</li>
 162         <li>click &ndash; when the user clicks or taps a point on the map without initiating a pan, this event triggers even while drawing a shape</li>
 163         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map but is not actively drawing</li>
 164         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 165         <li>shape &ndash; when the user double-clicks or taps a point on the map after beginning a drawing operation with a single click, this action will send a GeoJSON LineString object to the developer</li>
 166       </ul>
 167
 168       <h2>drawPolygon</h2>
 169
 170       <h3>user experience</h3>
 171       <p>The default cursor is a crosshair.</p>
 172
 173       <p>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.</p>
 174
 175       <p>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.</p>
 176
 177       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 178
 179       <h3>events</h3>
 180       <p>In drawPolygon mode, the geomap widget triggers the following events on the original map div.</p>
 181       <ul>
 182         <li>move &ndash; when the user moves the mouse above the map but is not actively panning, this event triggers even while drawing a shape</li>
 183         <li>click &ndash; when the user clicks or taps a point on the map without initiating a pan, this event triggers even while drawing a shape</li>
 184         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map but is not actively drawing</li>
 185         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 186         <li>shape &ndash; when the user double-clicks or taps a point on the map after beginning a drawing operation with a single click, this action will send a GeoJSON Polygon object to the developer</li>
 187       </ul>
 188
 189       <h2>measureLength</h2>
 190
 191       <h3>user experience</h3>
 192       <p>The default cursor is a crosshair.</p>
 193
 194       <p>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.</p>
 195
 196       <p>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.</p>
 197
 198       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 199
 200       <p>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.</p>
 201       <h3>events</h3>
 202       <p>In measureLength mode, the geomap widget triggers the following events on the original map div.</p>
 203       <ul>
 204         <li>move &ndash; when the user moves the mouse above the map but is not actively panning, this event triggers even while measuring</li>
 205         <li>click &ndash; when the user clicks or taps a point on the map without initiating a pan, this event triggers even while measuring</li>
 206         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map but is not actively measuring</li>
 207         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 208       </ul>
 209
 210       <h2>measureArea</h2>
 211
 212       <h3>user experience</h3>
 213       <p>The default cursor is a crosshair.</p>
 214
 215       <p>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.</p>
 216
 217       <p>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.</p>
 218
 219       <p>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 &quot;pinch zoom&quot; (currently not available on Android).</p>
 220
 221       <p>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.</p>
 222
 223       <h3>events</h3>
 224       <p>In measureArea mode, the geomap widget triggers the following events on the original map div.</p>
 225       <ul>
 226         <li>move &ndash; when the user moves the mouse above the map but is not actively panning, this event triggers even while measuring</li>
 227         <li>click &ndash; when the user clicks or taps a point on the map without initiating a pan, this event triggers even while measuring</li>
 228         <li>dblclick &ndash; when the user double-clicks or double-taps a point on the map but is not actively measuring</li>
 229         <li>bboxchange &ndash; when the user changes the bbox by panning or zooming</li>
 230       </ul>
 231
 232       <h2 id="custom-modes">custom modes</h2>
 233
 234       <p>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:</p>
 235
 236       <pre><code>var map = $( &quot;#map&quot; ).geomap( {
 237   mode: &quot;click&quot;,
 238   cursors: { click: &quot;crosshair&quot; }
 239 } );</code></pre>
 240
 241       <p>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 &amp; bboxchange. A mode like this is useful if you want to give users more accuracy when clicking the map.</p>
 242
 243       <p>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.</p>
 244
 245       <pre><code>function setMode( mode ) {
 246   map.geomap( &quot;option&quot;, {
 247     mode: mode,
 248     panning: mode !== &quot;click&quot;
 249   } );
 250 }</code></pre>
 251
 252       <p>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.</p>
 253
 254       <pre><code>var map = $( &quot;#map&quot; ).geomap( {
 255   mode: &quot;drawPoint&quot;,
 256   cursors: {
 257     find: &quot;crosshair&quot;,
 258     remove: &quot;crosshair&quot;
 259   },
 260   shape: function( e, geo ) {
 261     <span class="comment">// only the draw modes trigger this event</span>
 262     map.geomap( &quot;append&quot;, geo );
 263   },
 264   click: function( e, geo ) {
 265     switch( map.geomap( &quot;option&quot;, &quot;mode&quot; ) ) {
 266       case &quot;find&quot;:
 267         <span class="comment">// search for shapes but just alert the user</span>
 268         var shapes = map.geomap( &quot;find&quot;, geo, 3 );
 269         if ( shapes.length &gt; 0 ) {
 270           alert( &quot;Found &quot; + shapes.length + &quot; shape(s) !&quot; );
 271         }
 272         break;
 273
 274       case &quot;remove&quot;:
 275         <span class="comment">// search for shapes and remove one of them</span>
 276         var shapes = map.geomap( &quot;find&quot;, geo, 3 );
 277         if ( shapes.length &gt; 0 ) {
 278           map.geomap( &quot;remove&quot;, shapes[ 0 ] );
 279         }
 280         break;
 281
 282       default:
 283         <span class="comment">// ignore the click event for all other modes: pan, zoom, etc.</span>
 284         break;
 285     }
 286   }
 287 } );</code></pre>
 288
 289     </div>
 290   </div> <!-- end of #container -->
 291
 292   <script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
 293   <script src="http://code.jquerygeo.com/jquery.geo-1.0a4.min.js"></script>
 294   <script src="../js/script.js"></script>
 295   <script src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
 296 </body>
 297 </html>
 298