A utility class for performing common DOM and AJAX operations safely across browsers.
| Name and Signature | Return Type | Description |
|---|---|---|
| getBrowser() | Seadragon.Browser value | Returns the user's browser. This method is resistant to user-agent spoofing. |
| getBrowserVersion() | Number | Returns the version of the user's browser, or 0 if the browser is unknown. The version is up to one decimal place and does not include any letters (e.g. 'a' for an alpha release). |
| getElement(elmt) | HTML Element | Convenience method that returns the HTML Element object for the given argument, which can be the element itself or the element's id. |
| getElementPosition(elmt) | Seadragon.Point | Returns the position of the given element, relative to the document. |
| getElementSize(elmt) | Seadragon.Point | Returns the size of the given element. |
| getElementStyle(elmt) | CSS Object | Returns the computed style of the given element. This style object exposes the same Javascript properties as the inline elmt.style object, e.g. "textAlign" for the CSS "text-align" property. |
| getEvent(event) | HTML Event | Convenience method that returns the HTML Event object for the given argument, which can be the event itself or undefined, since IE doesn't pass the event object to event handlers. |
| getMousePosition(event) | Seadragon.Point | Returns the position of the mouse during the given event, relative to the document. |
| getMouseScroll(event) | Number | Returns the amount the mouse wheel was scrolled during the given event, normalized between -1 and 1. |
| getPageScroll() | Seadragon.Point | Returns the amount that the page is currently scrolled. |
| getWindowSize() | Seadragon.Point | Returns the current size of the browser's viewport. |
| imageFormatSupported(ext) | Boolean | Returns true if the browser can natively display images of the given format. |
| makeCenteredNode(elmt) | HTML Element | Returns an HTML element that contains the given HTML node (which can be a text node). The node will be centered both vertically and horizontally when the returned element is placed inside any container. This method ensures vertical centering in IE, whereas the W3C CSS table-cell technique does not. |
| makeNeutralElement(tagName) | HTML Element | Creates and returns an HTML element for the given tag name. This element has inline style to neutralize any inherited style. |
| makeTransparentImage(src) | HTML Element | Returns an HTML element for the image at the given URL. This element supports alpha channels used by the PNG format safely. This method should be called to ensure transparency in IE6. |
| setElementOpacity(elmt, opacity, usesAlpha?) | - |
Sets the opacity of the given element to the given amount, which
should be between 0 and 1. Preserves non-alpha filters (e.g.
AlphaImageLoader) in IE. If usesAlpha is true, adjusts for browsers which do not handle multi-bit alpha channels properly. If the element is a PNG image that uses an alpha channel, or if the element contains such PNG images, usesAlpha should be true. This is not required for GIF images, which use 1-bit alpha channels. |
| addEvent(elmt, eventName, handler, useCapture?) | - | Attaches the given handler function to the given element, for the event with the given name (without the "on" prefix). If useCapture is true and the browser is IE, the element begins capturing all mouse events. If useCapture is true and the browser is not IE, the handler is registered for the event's capture phase instead of the event's bubble phase. 1 |
| removeEvent(elmt, eventName, handler, useCapture?) | - | Detaches the given handler function from the given element, for the event with the given name (without the "on" prefix). If useCapture is true and the browser is IE, the element releases capture of mouse events. If useCapture is true and the browser is not IE, the handler for the event's capture phase is removed, instead of for the event's bubble phase. 1 |
| cancelEvent(event) | - | Cancels the given event so that its default action will not be performed by the browser. Note that the event will still continue to propagate up or down the DOM tree unless stopEvent() is called. |
| stopEvent(event) | - | Stops the given event so that it no longer propagates up or down the DOM tree. Note that its default action will still be performed by the browser unless cancelEvent() is called. |
| createCallback(object, func, ...) | Function |
Returns a function that calls the given function with the given
object as the execution scope. That is, the Javascript keyword
this will refer to the given object
inside the given function. Any additional arguments passed to this function will also be passed to the given function, in addition to arguments passed to the returned function. The additional arguments are concatenated to the previous arguments. For example, Seadragon.Utils.createCallback(null, func, 1, 2, 3)(4, 5) is equivalent to func(1, 2, 3, 4, 5). |
| getUrlParameter(key) | String | Returns the value for the given key in the URL search string, or null if the URL search string includes no such parameter. |
| makeAjaxRequest(url, callback?) | XMLHttpRequest |
Makes an AJAX request to the given URL. If a callback function is given, the request
is asynchronous, and the XMLHttpRequest object is passed as the sole parameter to
the callback upon completion (readyState of 4). Otherwise, the XML is loaded synchronously
and the XMLHttpRequest object is returned by this method. If there is a security error or any other error in simply creating the request, null is passed or returned. Otherwise, the status property of the XMLHttpRequest object can be used to determine success (status of 200 usually means successful). |
| parseXml(string) | XML Document | Parses the given string into an XML document and returns the Document object. This method is synchronous. |