22.7 The NavigationFilter Class

The NavigationFilter class is similar to the DocumentFilter class except that it oversees caret positioning instead of edits to the Document. Like DocumentFilter, NavigationFilter was introduced in SDK 1.4. Unlike DocumentFilter, you can easily install a NavigationFilter on any Swing text component without having to perform a cast. Just pass your NavigationFilter into the component's setNavigationFilter( ) method, and the component's Caret will filter all movement through it. NavigationFilters can also be specified by subclasses of AbstractFormatter (see Chapter 20).

Two of NavigationFilter's methods work just like DocumentFilter's methods. The Caret's moveDot( ) and setDot( ) methods check for the existence of a NavigationFilter. If there is one, they forward the call to the like-named method of the NavigationFilter object. But the NavigationFilter methods are passed an extra parameter called the FilterBypass. The FilterBypass object has its own moveDot( ) and setDot( ) methods, and these actually change the position of the Caret. FilterBypass also provides access to the Caret via its getCaret( ) method.

A third method, getNextVisualPositionFrom( ), is called by the default caret movement Actions^[28] when they are acting on a component that has a NavigationFilter. Thus, a NavigationFilter can completely control how the caret reacts to the arrow keys. (If no NavigationFilter exists, the default caret movement Actions call the like-named method of the appropriate View object instead. See Section 22.5.2 earlier in this chapter.) There is no FilterBypass involved with this method.

^[28] These Actions are defined in DefaultEditorKit (see Chapter 23) and are bound by the existing L&Fs to the arrow keys (to move the caret) and Shift-arrow keys (to extend the current selection).

22.7.1 Constructor

public NavigationFilter( )

Instantiate a NavigationFilter that reproduces the default caret movement behavior.

22.7.1.1 Methods

NavigationFilter's methods reproduce the default caret movement behavior, so you override only the ones you want to behave differently.

public void setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

public void moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

The bias parameter is not present in the corresponding methods in the Caret interface. Except for forwarding it to the FilterBypass methods when necessary, you can ignore it.

public int getNextVisualPositionFrom(JTextComponent comp, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) throws BadLocationException

See the like-named method in Section 22.5.2 for a description of this method. The default implementation delegates (by way of the component's TextUI) to the appropriate View object. If you override this method, you can call super.getNextVisualPositionFrom(comp, pos, bias, biasRet) to determine where the caret would go if there is no NavigationFilter. Note that the caret is not guaranteed to actually appear at the offset returned by this method because the NavigationFilter's moveDot( ) and setDot( ) methods may not allow it.

22.7.1.2 NavigationFilter.FilterBypass methods

public Caret getCaret( )

public void setDot(int dot, Position.Bias bias)

public void moveDot(int dot, Position.Bias bias)

This was a long chapter, but now you know all about Swing's handling of styled text. You have only one more chapter to go, and then the Swing text components will no longer hold any mysteries for you. In the next chapter we cover the last of the Swing text components: the flexible and powerful JEditorPane.