|resources:||Home Release Notes Installation API / Examples Source Code Bugs Links Mailing List|
Examples / API
xptrService = xptrService.QueryInterface(Components.interfaces.nsIXPointerService);
After this step, you may call any of the four methods that the service API defines. The API provides two functions for creating XPointers and two functions for resolving them.
The two creation functions differ only in their input format: one takes an nsISelection object and the other takes a DOM Range. Both creation functions return a string containing the newly created XPointer.
Here is an example of creating an XPointer representing the selection in the main window:
var xptrString = xptrService.createXPointerFromSelection(window._content.getSelection(), window._content.document);
The resolution functions differ only in their return value. Of the two, the completely accurate function resolves to a DOM Range. The other function approximates to the DOM Node at the beginning of the resolved Range. The latter function exists for historical reasons--you should use the function that resolves to a DOM Range.
In actuality, an XPointer should resolve to an array of DOM Range (in XPointer terms, a location set). The next version of XPointerLib may implement that--for now, we make the simplifying assumption that an XPointer resolves only to a unified, contiguous location (the sort of thing a DOM Range will represent).
A sample resolution of the xpointer: xpointer(/html/body) for the current document is as follows:
var range = xptrService.parseXPointerToRange("xpointer(/html/body)", window._content.document);
In addition to creation and resolution, the XPointerLib also has a method called markElement which may be used to mark an element before inserting it into the DOM. Any element so marked, though visible in the document, will be ignored by XPointerLib processing--it will be as though it does not exist. So, if you want to insert an icon into the DOM without effecting resolution of further XPointers, be sure to call markElement on it before insertion. An example:
var icon = document.createElement("img");
// now you can insert the icon
// and XPointerLib will ignore it in processing