2gis-maps

<h2 id="utility">Utility</h2><dl class="api-incut"><ul class="page-contents"><li><a href="#dgbrowser">DG.Browser</a><ul><li><a href="#properties">Properties</a></li></ul></li><li><a href="#dgutil">DG.Util</a><ul><li><a href="#functions">Functions</a></li><li><a href="#properties-1">Properties</a></li></ul></li><li><a href="#dglineutil">DG.LineUtil</a><ul><li><a href="#functions-1">Functions</a></li></ul></li><li><a href="#dgpolyutil">DG.PolyUtil</a><ul><li><a href="#functions-2">Functions</a></li></ul></dl> <h3 id="dgbrowser">DG.Browser</h3>A namespace with static properties for browser/feature detection. <pre><code>if (DG.Browser.ie6) { alert('Upgrade your browser, dude!'); } </code></pre><h4 id="properties">Properties</h4><table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr id="browser-ie"> <td><code>ie</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all Internet Explorer versions (not Edge).</td> </tr> <tr id="browser-ielt9"> <td><code>ielt9</code></td> <td><code>Boolean</code></td> <td><code>true</code> for Internet Explorer versions less than 9.</td> </tr> <tr id="browser-edge"> <td><code>edge</code></td> <td><code>Boolean</code></td> <td><code>true</code> for the Edge web browser.</td> </tr> <tr id="browser-webkit"> <td><code>webkit</code></td> <td><code>Boolean</code></td> <td><code>true</code> for webkit-based browsers like Chrome and Safari (including mobile versions).</td> </tr> <tr id="browser-gecko"> <td><code>gecko</code></td> <td><code>Boolean</code></td> <td><code>true</code> for gecko-based browsers like Firefox.</td> </tr> <tr id="browser-android"> <td><code>android</code></td> <td><code>Boolean</code></td> <td><code>true</code> for any browser running on an Android platform.</td> </tr> <tr id="browser-android23"> <td><code>android23</code></td> <td><code>Boolean</code></td> <td><code>true</code> for browsers running on Android 2 or Android 3.</td> </tr> <tr id="browser-chrome"> <td><code>chrome</code></td> <td><code>Boolean</code></td> <td><code>true</code> for the Chrome browser.</td> </tr> <tr id="browser-safari"> <td><code>safari</code></td> <td><code>Boolean</code></td> <td><code>true</code> for the Safari browser.</td> </tr> <tr id="browser-ie3d"> <td><code>ie3d</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all Internet Explorer versions supporting CSS transforms.</td> </tr> <tr id="browser-webkit3d"> <td><code>webkit3d</code></td> <td><code>Boolean</code></td> <td><code>true</code> for webkit-based browsers supporting CSS transforms.</td> </tr> <tr id="browser-gecko3d"> <td><code>gecko3d</code></td> <td><code>Boolean</code></td> <td><code>true</code> for gecko-based browsers supporting CSS transforms.</td> </tr> <tr id="browser-opera12"> <td><code>opera12</code></td> <td><code>Boolean</code></td> <td><code>true</code> for the Opera browser supporting CSS transforms (version 12 or later).</td> </tr> <tr id="browser-any3d"> <td><code>any3d</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all browsers supporting CSS transforms.</td> </tr> <tr id="browser-mobile"> <td><code>mobile</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all browsers running in a mobile device.</td> </tr> <tr id="browser-mobilewebkit"> <td><code>mobileWebkit</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all webkit-based browsers in a mobile device.</td> </tr> <tr id="browser-mobilewebkit3d"> <td><code>mobileWebkit3d</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all webkit-based browsers in a mobile device supporting CSS transforms.</td> </tr> <tr id="browser-mobileopera"> <td><code>mobileOpera</code></td> <td><code>Boolean</code></td> <td><code>true</code> for the Opera browser in a mobile device.</td> </tr> <tr id="browser-mobilegecko"> <td><code>mobileGecko</code></td> <td><code>Boolean</code></td> <td><code>true</code> for gecko-based browsers running in a mobile device.</td> </tr> <tr id="browser-touch"> <td><code>touch</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all browsers supporting <a href="https://developer.mozilla.org/docs/Web/API/Touch_events">touch events</a>.</td> </tr> <tr id="browser-mspointer"> <td><code>msPointer</code></td> <td><code>Boolean</code></td> <td><code>true</code> for browsers implementing the Microsoft touch events model (notably IE10).</td> </tr> <tr id="browser-pointer"> <td><code>pointer</code></td> <td><code>Boolean</code></td> <td><code>true</code> for all browsers supporting <a href="https://msdn.microsoft.com/en-us/library/dn433244%28v=vs.85%29.aspx">pointer events</a>.</td> </tr> <tr id="browser-retina"> <td><code>retina</code></td> <td><code>Boolean</code></td> <td><code>true</code> for browsers on a high-resolution "retina" screen.</td> </tr> <tr id="browser-canvas"> <td><code>canvas</code></td> <td><code>Boolean</code></td> <td><code>true</code> when the browser supports <a href="https://developer.mozilla.org/docs/Web/API/Canvas_API"><code><canvas></code></a>.</td> </tr> <tr id="browser-vml"> <td><code>vml</code></td> <td><code>Boolean</code></td> <td><code>true</code> if the browser supports <a href="https://en.wikipedia.org/wiki/Vector_Markup_Language">VML</a>.</td> </tr> <tr id="browser-svg"> <td><code>svg</code></td> <td><code>Boolean</code></td> <td><code>true</code> when the browser supports <a href="https://developer.mozilla.org/docs/Web/SVG">SVG</a>.</td> </tr> </tbody> </table> <h3 id="dgutil">DG.Util</h3>Various utility functions. <h4 id="functions">Functions</h4><table> <thead> <tr> <th>Function</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="util-extend"> <td><code>extend( <Object> dest, <Object> src? ) </code></td> <td><code>Object</code></td> <td>Merges the properties of the <code>src</code> object (or multiple objects) into <code>dest</code> object and returns the latter. Has an <code>DG.extend</code> shortcut.</td> </tr> <tr id="util-create"> <td><code>create( <Object> proto, <Object> properties? ) </code></td> <td><code>Object</code></td> <td>Compatibility polyfill for <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/create">Object.create</a></td> </tr> <tr id="util-bind"> <td><code>bind( <Function> fn, … ) </code></td> <td><code>Function</code></td> <td>Returns a new function bound to the arguments passed, like <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function/bind">Function.prototype.bind</a>. Has a <code>DG.bind()</code> shortcut.</td> </tr> <tr id="util-stamp"> <td><code>stamp( <Object> obj ) </code></td> <td><code>Number</code></td> <td>Returns the unique ID of an object, assiging it one if it doesn't have it.</td> </tr> <tr id="util-throttle"> <td><code>throttle( <Function> fn, <Number> time, <Object> context ) </code></td> <td><code>Function</code></td> <td>Returns a function which executes function <code>fn</code> with the given scope <code>context</code> (so that the <code>this</code> keyword refers to <code>context</code> inside <code>fn</code>'s code). The arguments received by the bound function will be any arguments passed when binding the function, followed by any arguments passed when invoking the bound function. Has an <code>DG.bind</code> shortcut.</td> </tr> <tr id="util-wrapnum"> <td><code>wrapNum( <Number> num, <Number[]> range, <Boolean> includeMax? ) </code></td> <td><code>Number</code></td> <td>Returns the number <code>num</code> modulo <code>range</code> in such a way so it lies within <code>range[0]</code> and <code>range[1]</code>. The returned value will be always smaller than <code>range[1]</code> unless <code>includeMax</code> is set to <code>true</code>.</td> </tr> <tr id="util-falsefn"> <td><code>falseFn()</code></td> <td><code>Function</code></td> <td>Returns a function which always returns <code>false</code>.</td> </tr> <tr id="util-formatnum"> <td><code>formatNum( <Number> num, <Number> digits? ) </code></td> <td><code>Number</code></td> <td>Returns the number <code>num</code> rounded to <code>digits</code> decimals, or to 5 decimals by default.</td> </tr> <tr id="util-trim"> <td><code>trim( <String> str ) </code></td> <td><code>String</code></td> <td>Compatibility polyfill for <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/Trim">String.prototype.trim</a></td> </tr> <tr id="util-splitwords"> <td><code>splitWords( <String> str ) </code></td> <td><code>String[]</code></td> <td>Trims and splits the string on whitespace and returns the array of parts.</td> </tr> <tr id="util-setoptions"> <td><code>setOptions( <Object: options: Object> obj ) </code></td> <td><code>Object</code></td> <td>Merges the given properties to the <code>options</code> of the <code>obj</code> object, returning the resulting options. See <code>Class options</code>. Has an <code>DG.setOptions</code> shortcut.</td> </tr> <tr id="util-getparamstring"> <td><code>getParamString( <Object> obj, <String> existingUrl?, <Boolean> uppercase? ) </code></td> <td><code>String</code></td> <td>Converts an object into a parameter URL string, e.g. <code>{a: "foo", b: "bar"}</code> translates to <code>'?a=foo&b=bar'</code>. If <code>existingUrl</code> is set, the parameters will be appended at the end. If <code>uppercase</code> is <code>true</code>, the parameter names will be uppercased (e.g. <code>'?A=foo&B=bar'</code>) Simple templating facility, accepts a template string of the form <code>'Hello {a}, {b}'</code> and a data object like <code>{a: 'foo', b: 'bar'}</code>, returns evaluated string <code>('Hello foo, bar')</code>. You can also specify functions instead of strings for data values — they will be evaluated passing <code>data</code> as an argument.</td> </tr> <tr id="util-isarray"> <td><code>isArray(obj)</code></td> <td><code>Boolean</code></td> <td>Compatibility polyfill for <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray">Array.isArray</a></td> </tr> <tr id="util-indexof"> <td><code>indexOf()</code></td> <td><code>Number</code></td> <td>Compatibility polyfill for <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf">Array.prototype.indexOf</a></td> </tr> <tr id="util-requestanimframe"> <td><code>requestAnimFrame( <Function> fn, <Object> context?, <Boolean> immediate? ) </code></td> <td><code>requestId: Number</code></td> <td>Schedules <code>fn</code> to be executed when the browser repaints. <code>fn</code> is bound to <code>context</code> if given. When <code>immediate</code> is set, <code>fn</code> is called immediately if the browser doesn't have native support for <a href="https://developer.mozilla.org/docs/Web/API/window/requestAnimationFrame"><code>window.requestAnimationFrame</code></a>, otherwise it's delayed. Returns an id that can be used to cancel the request.</td> </tr> <tr id="util-cancelanimframe"> <td><code>cancelAnimFrame( <Number> id ) </code></td> <td><code></code></td> <td>Cancels a previous <code>requestAnimFrame</code>. See also <a href="https://developer.mozilla.org/docs/Web/API/window/cancelAnimationFrame">window.cancelAnimationFrame</a>.</td> </tr> </tbody> </table> <h4 id="properties-1">Properties</h4><table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr id="util-lastid"> <td><code>lastId</code></td> <td><code>Number</code></td> <td>Last unique ID used by <a href="#util-stamp"><code>stamp()</code></a></td> </tr> <tr id="util-emptyimageurl"> <td><code>emptyImageUrl</code></td> <td><code>String</code></td> <td>Data URI string containing a base64-encoded empty GIF image. Used as a hack to free memory from unused images on WebKit-powered mobile devices (by setting image <code>src</code> to this string).</td> </tr> </tbody> </table> <h3 id="dglineutil">DG.LineUtil</h3>Various utility functions for polyine points processing, used by Leaflet internally to make polylines lightning-fast. <h4 id="functions-1">Functions</h4><table> <thead> <tr> <th>Function</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="lineutil-simplify"> <td><code>simplify( <Point[]> points, <Number> tolerance ) </code></td> <td><code>Point[]</code></td> <td>Dramatically reduces the number of points in a polyline while retaining its shape and returns a new array of simplified points, using the <a href="http://en.wikipedia.org/wiki/Douglas-Peucker_algorithm">Douglas-Peucker algorithm</a>. Used for a huge performance boost when processing/displaying Leaflet polylines for each zoom level and also reducing visual noise. tolerance affects the amount of simplification (lesser value means higher quality but slower and with more points). Also released as a separated micro-library <a href="http://mourner.github.com/simplify-js/">Simplify.js</a>.</td> </tr> <tr id="lineutil-pointtosegmentdistance"> <td><code>pointToSegmentDistance( <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p, <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p1, <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p2 ) </code></td> <td><code>Number</code></td> <td>Returns the distance between point <code>p</code> and segment <code>p1</code> to <code>p2</code>.</td> </tr> <tr id="lineutil-closestpointonsegment"> <td><code>closestPointOnSegment( <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p, <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p1, <<a href="/doc/maps/en/manual/basic-types#dgpoint">Point</a>> p2 ) </code></td> <td><code>Number</code></td> <td>Returns the closest point from a point <code>p</code> on a segment <code>p1</code> to <code>p2</code>.</td> </tr> </tbody> </table> <h3 id="dgpolyutil">DG.PolyUtil</h3>Various utility functions for polygon geometries. <h4 id="functions-2">Functions</h4><table> <thead> <tr> <th>Function</th> <th>Returns</th> <th>Description</th> </tr> </thead> <tbody> <tr id="polyutil-clippolygon"> <td><code>clipPolygon( <Point[]> points, <<a href="/doc/maps/en/manual/basic-types#dgbounds">Bounds</a>> bounds, <Boolean> round? ) </code></td> <td><code>Point[]</code></td> <td>Clips the polygon geometry defined by the given <code>points</code> by the given bounds (using the <a href="https://en.wikipedia.org/wiki/Sutherland%E2%80%93Hodgman_algorithm">Sutherland-Hodgeman algorithm</a>). Used by Leaflet to only show polygon points that are on the screen or near, increasing performance. Note that polygon points needs different algorithm for clipping than polyline, so there's a seperate method for it.</td> </tr> </tbody> </table>