[Contents] [Previous] [Next] [Last]
Composer Plug-ins can perform a variety of operations on selected text. To do this, the plug-in must be able to find the current selection of text, tags, and images, and take the selection from the document so that it can be modified.
This chapter describes using Composer Plug-in methods to tokenize and select text, tags, and images for the plug-in to act upon.
HTML selection comments precede and follow selected text. At the beginning of the document, the plug-in is outside the selection. After it encounters the selection start comment, it is inside the selection. After encountering the selection end comment, it passes beyond the selection into unselected text. A plug-in uses Comment class methods to find out whether a comment is an HTML selection comment.
[Top]
The plug-in finds the current selection of text, tags, and images by advancing through a document and testing each comment to see if it is the beginning of a selection.
[Top]
To test for the beginning of the selection, use the comment.isSelectionStart method, which specifies whether a comment is a selection start comment.
public boolean isSelectionStart()
The method returns true if the comment is a selection start comment and false otherwise.
See "Testing a Comment: Sample Code" for an example that uses isSelectionStart and isSelectionEnd.
[Top] [Finding Selection Start and End]
To test for the end of the selection, use the comment.isSelectionEnd method, which specifies whether a the comment is a selection end comment.
public boolean isSelectionEnd()
The method returns true if the comment is a selection end comment and false otherwise.
See "Testing a Comment: Sample Code" for an example that uses isSelectionStart and isSelectionEnd.
[Top] [Finding Selection Start and End]
This code fragment checks whether the comment is a selection start, and, if so, sets the previously declared inSelection variable to true. If the comment is a selection end, it sets the same variable to false.
/* Null means you have finished examining the document. */
if ( token == null ) break;
/* If the next token is a Comment, */
/* check for selection start. */
else if (token instanceof Comment ) {
Comment comment = (Comment) token;
if ( comment.isSelectionStart() ){
inSelection = true;
}
/* Check for selection end. */
else if (comment.isSelectionEnd() ){
inSelection = false;
}
[Top] [Finding Selection Start and End]
Before a plug-in can select text, it must break the text into tokens. Text is selected when the plug-in inserts a begin comment before the first piece of text and an end comment after the last one.
Note:
To create an insertion point, place the end comment immediately
after the start comment, with nothing in between. 
See "Testing a Comment: Sample Code" for an extended example.
[Top]
To create the start point of a selection, use one of the forms of the comment.createSelectionStart method, which creates and returns a begin comment. This method has two forms:
public static Comment createSelectionStart()
public static Comment createSelectionStart(
boolean stickyafter)
The form without parameters returns a selection start comment. The form with the boolean stickyAfter parameter returns the start comment plus an additional bit that is used to make sure that the document returns to its exact previous state after an undo operation. You almost never need to set this value.
[Top] [Creating Selection Start and End]
To create the end point of a selection, use the comment.createSelectionEnd method, which creates and returns an end comment. This method has two forms:
public static Comment createSelectionEnd()
public static Comment createSelectionEnd(boolean stickafter);
The method form without parameters returns a selection end comment. The form with the boolean stickyAfter parameter returns the end comment plus an additional bit that is used to tell where the cursor should be placed when text is broken across two lines after an undo operation.
[Top] [Creating Selection Start and End]
Sometimes you may prefer to process the raw HTML of a document without tokenizing it. To select raw HTML, the plug-in must place the beginning and end comments itself. Selecting raw HTML may be more effective when you want to select only a small portion of a large document and modify the current selection without looking at the entire document, for example, in a spelling checker.
Selecting raw HTML involves these steps:
See "Selecting Text: Sample Code" for an extended example. For more information about raw HTML, see "Reading and Writing Raw HTML."
[Top]
This example is from the TagStrip sample plug-in, included in the Composer Plug-in Kit, which finds and removes all HTML tags from the selected text in a document. The perform method of TagStrip includes these operations:
public boolean perform(Document document) throws IOException{
/* Create a print stream for the new document text. */
PrintWriter out = new PrintWriter(document.getOutput());
/* Create a lexical stream to tokenize the old document text. */
LexicalStream in = new LexicalStream(new SelectedHTMLReader(
document.getInput(), out));
Next, TagStrip finds the selected text and uses isSelectionStart() and isSelectionEnd to keep track of whether the plug-in is in the selected text.
/* Set inSelection variable value to false. */
boolean inSelection = false;
String paragraphTag = "P";
for(;;){
/* Get the next token of the document. */
Token token = in.next();
/* Null = you have finished examining the document. */
if ( token == null ) break;
/* If the next token is a comment, */
/* check for selection start. */
else if (token instanceof Comment ) {
Comment comment = (Comment) token;
if ( comment.isSelectionStart() ){
inSelection = true;
}
else if ( comment.isSelectionEnd()){
inSelection = false;
}
else {
/* Don't output this generic comment. */
continue;
}
}
else if ( inSelection && token instanceof Tag) {
Tag tag = (Tag) token;
if ( ! paragraphTag.equals(tag.getName()) ) {
/* Don't output this tag. */
continue;
}
}
out.print(token);
}
out.close();
return true;
}
}
TagStrip removes the HTML tags from the document by reading them without writing them back again.
[Top] [Contents] [Previous] [Next] [Last]
Copyright © 1997 Netscape Communications Corporation