Applications that allow editing of large, structured documents such as code listings might often benefit from the ability to track positions in the document as it is edited. Typically, recording offsets into the document solves this problem. This solution does not scale well because it requires updating the offset values whenever the text is edited. Swing provides a Position interface that does the hard work of updating offsets for you.

To create a Position instance, you first need to determine where in the document to set it. For the purpose of the sample code, assume that you have an active JTextPane object called “aTextPane.” If you are displaying text and want to get a Position for the current caret position, you can use this snippet:

 int documentOffset = aTextPane.getCaret().getDot();

You can also search for patterns in the document (like method declarations or section headings) and use those offsets instead. Once you have an offset value, you just need to get a reference to the relevant Document instance and call createPosition() with your offset, as is done here:

 javax.swing.text.Position aPosition =aTextPane.getDocument().createPosition(documentOffset);

When you need to reset the caret to the offset represented by thePosition you have saved, just get the updated offset from the Position object:

 aTextPane.getCaret().setDot(aPosition.getOffset());

Depending on your application, you may also need to check when aPosition becomes invalid, such as when the section being tracked is deleted. Such checking still needs to be implemented manually.

The Position interface provides a simple way to track locations in text content as the rest of the document is edited. One application for Position would be to manage a list of methods contained in a source file with a popup menu that takes the caret to that method when it is selected. Long, structured documents with multiple sections and subsections would also benefit from a simple navigation menu implemented through the Position interface.