ice.pilots.html4
Class SelectionAgent

java.lang.Object
  ice.pilots.html4.SelectionAgent

public class SelectionAgent

extends Object

The SelectionAgent removes the selection code from CSSLayout into a separate entity. The CSSLayout class will defer to this class to manage ObjectSelection, but will not need to know the details of how it's handled.

This object, for the moment, uses references to the CSSLayout object to perform various operations, but this reference should be replaced by an controller interface instance that is passed into the methods that require it.

This object is tightly coupled with the TextBox, and performs selection logic that should likely be in that object, given the way that selection was done in the past. This is a bit that requires refactoring. In general, selection is only a slightly more involved aspect of the accessability code, and leverages those methods to a certain degree. In the future, accessability and the more general topic of handling a HTML document as a language document will be addressed.

This object is also a repository of state for a variety of operations. Clicking the mouse causes selection text to be cleared, but it also can position a cursor for later operations.

Since:

6.1

Constructor Summary

SelectionAgent(DRange range)
Construct a new SelectionAgent.

Method Summary

void	clearHighlights() Remove all highlight areas from the system.
void	clearSelection(ice.pilots.html4.CSSLayout layout) Clear the text Selection.
void	defineHighlight(ice.pilots.html4.CSSBox box, int startIndex, int endIndex) Allow a client to define a highlight section.
void	empty()
DNode	getEndContainer()
int	getEndOffset()
DElement	getSelectionParentNode() Retrieve the highest DElement from the selection hierarchy.
DNode	getStartContainer()
int	getStartOffset()
boolean	isInside(ice.pilots.html4.CSSLayout layout, int xPos, int yPos, int scrollX, int scrollY) Provide a higher resolution solution to the above method.
boolean	isInside(DNode node) Test if a given DNode falls within the currently selected Node hierarchy.
boolean	isSelectionActive() Retrieve a boolean value indicating if a selection region is currently active.
void	markDocument(ice.pilots.html4.CSSLayout layout, int xPos, int yPos, int scrollX, int scrollY) The same mouse down event has the effect of placing an apparent cursor on the screen for the purposes of (modifier)+arrow text selection.
void	postSelectedToClipboard(ice.pilots.html4.CSSLayout layout) Post any currently selected text to the Application clipboard, if applicable.
void	select(DNode n1, int off1, DNode n2, int off2, ice.pilots.html4.CSSLayout layout) Select a range of text.
void	selectAll(ice.pilots.html4.CSSLayout layout) Select all the nodes in a document.
void	selectCharLeft(ice.pilots.html4.CSSLayout layout) Move the selection end marker one character to the left.
void	selectCharRight(ice.pilots.html4.CSSLayout layout) Move the selection end marker one character to the right and apply the new selection.
void	selectSentenceLeft(ice.pilots.html4.CSSLayout layout) Move the selection end marker one sentence to the left.
void	selectSentenceRight(ice.pilots.html4.CSSLayout layout) Move the selection end marker one sentence to the left.
void	selectWordByIndex(ice.pilots.html4.CSSLayout layout, int index) Select a word from the document by absolute index.
void	selectWordLeft(ice.pilots.html4.CSSLayout layout) Move the selection end marker one word to the left, and apply the new selection.
void	selectWordRangeByIndex(ice.pilots.html4.CSSLayout layout, int startIndex, int endIndex) This method will select a range of words starting at the starting word index, and continuing through the end of the word indicated by the ending word index.
void	selectWordRight(ice.pilots.html4.CSSLayout layout) Move the selection end marker one word to the right and apply the new selection.
void	setSelection(ice.pilots.html4.CSSLayout layout, int x1, int y1, int x2, int y2, int scrollX, int scrollY) Set a selection region within the content.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SelectionAgent

public SelectionAgent(DRange range)

Construct a new SelectionAgent. Currently, the DRange comes from the Document, but there is no reason for that to be.

Method Detail

empty

public void empty()

clearSelection

public void clearSelection(ice.pilots.html4.CSSLayout layout)

Clear the text Selection. This is currently caused by a mouse down event.

Parameters:

layout - reference to CSSLayout class

markDocument

public void markDocument(ice.pilots.html4.CSSLayout layout,
                         int xPos,
                         int yPos,
                         int scrollX,
                         int scrollY)

The same mouse down event has the effect of placing an apparent cursor on the screen for the purposes of (modifier)+arrow text selection. If this mouse location is within a textbox, then we will set the starting markers. It is currently intended that this method is to be called after the clearSelection event, since the same mouse event must do both.

Parameters:

layout - CSSLayout reference

xPos - visible x position

yPos - visible y position

scrollX - Horizontal scroll bar value

scrollY - Vertical scroll bar value

selectAll

public void selectAll(ice.pilots.html4.CSSLayout layout)

Select all the nodes in a document. This will include in the selection range all the nodes

Parameters:

layout - The CSSLayout class to provide some document access

setSelection

public void setSelection(ice.pilots.html4.CSSLayout layout,
                         int x1,
                         int y1,
                         int x2,
                         int y2,
                         int scrollX,
                         int scrollY)

Set a selection region within the content. Given a rectangular area described by the mouse over the Browser window, at a given scroll location in the document, this method identifies the starting node and ending node of the selection. This method notifies the selection range object of the end paths of the selection range.

Parameters:

layout - Instance of the layout class

x1 - top left x coordinate

y1 - top left y coordinate

x2 - bottom right x coordinate

y2 - bottom right y coordinate

scrollX - horizontal scroll bar position

scrollY - Vertical scroll bar position

isSelectionActive

public boolean isSelectionActive()

Retrieve a boolean value indicating if a selection region is currently active.

Returns:

true if a selection region is currently active, false if not.

selectWordByIndex

public void selectWordByIndex(ice.pilots.html4.CSSLayout layout,
                              int index)

Select a word from the document by absolute index. The proper range of the index is:

0 <= index <= layout.getCount( Html4DocumentAccess.WORD_TYPE);

Parameters:

layout - The CSSLayout class

index - The index of the word to select

selectWordRangeByIndex

public void selectWordRangeByIndex(ice.pilots.html4.CSSLayout layout,
                                   int startIndex,
                                   int endIndex)

This method will select a range of words starting at the starting word index, and continuing through the end of the word indicated by the ending word index. The range must be inclusive in the document, but need not be within the same DTextNode. Ranges of word selection is:

0 <= startIndex <= endIndex <= layout.getCount( Html4DocumentAccess.WORD_TYPE);

This method does not set the selection markers for incremental line selection.

Parameters:

layout - Reference to CSSLayout instance

startIndex - the selection starting word index.

endIndex - The selection ending word index.

selectWordRight

public void selectWordRight(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one word to the right and apply the new selection. There must be some initial text selection already in place for this to take effect. #4263

Parameters:

layout - instance of CSSLayout

selectCharRight

public void selectCharRight(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one character to the right and apply the new selection. There must be some initial text selection already in place for this to take effect. #4263

Parameters:

layout - instance of CSSLayout

selectSentenceRight

public void selectSentenceRight(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one sentence to the left. In a normal LTR page, this is selecting up the page.

selectWordLeft

public void selectWordLeft(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one word to the left, and apply the new selection. There must be some initial text selection already in place for this to take effect. #4263

Parameters:

layout - instance of CSSLayout

selectCharLeft

public void selectCharLeft(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one character to the left.

Parameters:

layout -

selectSentenceLeft

public void selectSentenceLeft(ice.pilots.html4.CSSLayout layout)

Move the selection end marker one sentence to the left. In a normal LTR page, this is selecting up the page.

toString

public String toString()

getStartContainer

public DNode getStartContainer()

getEndContainer

public DNode getEndContainer()

getStartOffset

public int getStartOffset()

getEndOffset

public int getEndOffset()

select

public void select(DNode n1,
                   int off1,
                   DNode n2,
                   int off2,
                   ice.pilots.html4.CSSLayout layout)

Select a range of text. This is utilized by the search algorithm, or other clients who have access to the startingOffsets and nodes already

Parameters:

n1 - Starting nodes

off1 - Offset within starting nodes

n2 - Ending nodes

off2 - Offset within ending nodes

layout - CSSLayout reference.

isInside

public boolean isInside(DNode node)

Test if a given DNode falls within the currently selected Node hierarchy. This method will return true if the node argument is a Node that falls within the hierarchical umbrella of nodes that can be represented graphically as follows:

                  commonAncestor
                /               \
               node    *is       node     *is outside
              /       inside      \
  startContainer                   endContainer
 

Parameters:

node - The node to test

Returns:

True if the node falls within the selection hierarchy, false if outside

isInside

public boolean isInside(ice.pilots.html4.CSSLayout layout,
                        int xPos,
                        int yPos,
                        int scrollX,
                        int scrollY)

Provide a higher resolution solution to the above method. The above method is suitable for TextBoxes that want to know if they're one of the selected boxes, since a separate path manages chr selection . This method needs to determine the character offset of a given point in the document, and determine if this chr offset is in the selection range. This method defers the ultimate decision to the DRange object, since that node has access to the start and ending character offsets, and the startPaths.

Parameters:

xPos - x position within window

yPos - y position within window

scrollX - Horizontal scroll bar position

scrollY - Vertical scroll bar position

Returns:

true if this mouse position is within the selected text region, false otherwise

getSelectionParentNode

public DElement getSelectionParentNode()

Retrieve the highest DElement from the selection hierarchy.

Returns:

The DELement that corresponds to the HTML node

defineHighlight

public void defineHighlight(ice.pilots.html4.CSSBox box,
                            int startIndex,
                            int endIndex)

Allow a client to define a highlight section. The highlight section must be completely within a a box. This SelectionAgent will manage the removal of all highlight ranges upon the clearing of the highlight ranges. Currently, this will only do something on TextBoxes, although it is not illegal to pass any type of Box, nor is it an error to pass ranges that are not valid. They will be ignored.

Parameters:

box - The CSSBox to mark.

startIndex -

endIndex -

See Also:

clearHighlights()

clearHighlights

public void clearHighlights()

Remove all highlight areas from the system.

postSelectedToClipboard

public void postSelectedToClipboard(ice.pilots.html4.CSSLayout layout)

Post any currently selected text to the Application clipboard, if applicable. This is also useful as a location to publish Selection Defined events, since this location is common to all selection types.

Parameters:

layout - reference to CSSLayout