net.sourceforge.nite.gui.textviewer
Class NTextArea

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.text.JTextComponent
                  javax.swing.JEditorPane
                      javax.swing.JTextPane
                          net.sourceforge.nite.gui.textviewer.NTextArea

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.awt.print.Printable, java.io.Serializable, javax.accessibility.Accessible, javax.swing.Scrollable, QueryResultHandler, SimpleQueryResultHandler, ScrollingTimeHandler, TimeHandler

Direct Known Subclasses:

AnnotationArea, NTranscriptionView

public class NTextArea
extends javax.swing.JTextPane
implements ScrollingTimeHandler, QueryResultHandler, java.awt.print.Printable, SimpleQueryResultHandler

The basic NITE GUI element used to display text - add text to the TextArea using addElement(NTextElement element). This GUI element can respond to timing highlights as well as query highlights and also implements the Printable interface.

Selection, highlighting and time aligned replay

The selection and highlighting mechanisms of the NTextArea are composed of several parts.
Caret tracking: As a descendant of JTextPane, the NTextArea uses a Caret for tracking cursor positions (influenced by arrow keys and mouse clicking and dragging). NTextArea uses an NTACaretListener to keep track of those cursor changes. Whenever the selection span changes, there are two possible reactions: Ctrl was NOT pressed, the method newSelection will be called, causing a change in the currently selected elements. Ctrl was pressed, the method newTimeSelection will be called, causing a replay of the media aligned with the selected elements.
Interpreting user selections: When the selection changes, the NTextArea will reinterpret the selection span to determine which NTextElements were really selected. Those will then be highlighted. E.g. if you click on one NTextElement, that will be highlighted. If you partially select several NTextElements, all of those elements will be fully highlighted and selected.
Highlighting functionalities: There are four independent types of highlighting in NTextArea, that are defined by integer type constants:

• SELECTION_HIGHLIGHTS are connected to GUI selections in the text area described above.
• TIME_HIGHLIGHTS are highlights caused by time alignment.
• QUERY_HIGHLIGHTS are caused by displaying query results on the NTextArea.
• USER_HIGHLIGHTS allow programmers to define their own highlightings for displaying some custom information (see also 'Defining your own highlighting').

Time and query highlighting:
Retrieving selection information: Information about current highlights (and therefore also selections) can be retrieved using getHighlightedTextElements(int type). The methods getSelectedNOMElementsOrdered, getSelectedTextElements, getSelectedElements and getSelectedElementsOrdered give a more flexible access to the selection information, though they will be renamed in the future to a more consistent set of function calls.
Furthermore, NTextArea offers the possibility to register an NTASelectionListener. Whenever the selection of the NTextArea changes, e.g. through mouse dragging, the NTASelectionListeners are notified of the change. They can then call the above methods and react to the new selections. This only works for selections, and not for time or query highlights.
Defining your own highlightings: If you want to display your own highlights for one reason or another, the easiest way is to us setHighlighted(NTextArea.USER_HIGHLIGHTS, element). If you want to use various colours in your custom highlighting (for example to highlight the source and target element of some link), you can use setHighlighted(NTextArea.USER_HIGHLIGHTS, element, templatestyle), passing different styles for the different highlight colours. To remove those user highlights call clearHighlights(NTextArea.USER_HIGHLIGHTS) The highlights are stored in TreeSets ordered by the transcript order. If you're planning to have highlights of 2000 or more elements, this will cause performance degradation, and you need to either reconsider the interface, or implement a different highlighting mechanism.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.text.JTextComponent

javax.swing.text.JTextComponent.AccessibleJTextComponent, javax.swing.text.JTextComponent.KeyBinding

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Field Summary

static int	QUERY_HIGHLIGHTS
static int	SELECTION_HIGHLIGHTS
static int	TIME_HIGHLIGHTS
static int	USER_HIGHLIGHTS

Fields inherited from class javax.swing.JEditorPane

HONOR_DISPLAY_PROPERTIES, W3C_LENGTH_UNITS

Fields inherited from class javax.swing.text.JTextComponent

DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.print.Printable

NO_SUCH_PAGE, PAGE_EXISTS

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

NTextArea()
create a screen area for the display of textual information with syncing-to-signal and search highlighting functionality.

Method Summary

void	acceptQueryResult(NOMElement result) display query result Old query highlights are removed.
void	acceptQueryResults(java.util.List results) display query results (arg should be a list of NOMElements).
void	acceptResults(java.util.List results) Accept the given list of query results, which can contain a mixture of NOMElements and further lists.
void	acceptTimeChange(double t) Accept a new time (generally from another registered TimeHandler) and highlight the appropriate elements.
void	acceptTimeSpanChange(double start, double end) Accept a new time span from another registered time handler and highlight the appropriate elements.
void	addCaretListener(javax.swing.event.CaretListener newl)
void	addElement(NTextElement te) Inserts the content specified in the text element argument at the end of the current document.
void	addElement(NTextElement newEl, NTextElement oldEl) Insert a new NTextElement into the document after the given existing element.
void	addNTASelectionListener(NTASelectionListener newListener)
void	clear() clear the display and (re)initialise all indexes
void	clearHighlights(int type) Clears all highlights of the given type.
void	clearSelection() A convenience method to clear all selection highlights.
Clock	getClock() Return the Clock that is currently syncronising this TimeHandler
java.util.Set	getElementsBetweenTimes(double start, double end) return a set of NTextElements which appear in the span
java.util.List	getHighlightedModelElements(int type) Returns a set of ObjectModelElements associated with a highlight for a given type.
java.util.List	getHighlightedNOMElements(int type) Returns a set of NOMElements associated with a highlight for a given type.
java.util.SortedSet	getHighlightedTextElements(int type) Returns a (shared) set of highlighted NTextElements for the given type.
double	getMaxTime() get the largest end time of any NTextElement so far added to this NTextArea.
NTextElement	getNTextElementAtPoint(java.awt.Point clickpoint) given a Point (most likely a mouseEvent.getPoint() intercepted by a MouseListener), return the NTextElement beneath it (or return null).
NTextElement	getNTextElementAtPosition(int position) Given a position in a document (probably because of trying to move the cursor), return the NTextElement at it, or null
ObjectModelElement	getObjectModelElementAtPoint(java.awt.Point clickpoint) given a Point (most likely a mouseEvent.getPoint() intercepted by a MouseListener), return the ObjctModelElement beneath it (or return null).
ObjectModelElement	getObjectModelElementAtPosition(int position) Given a position in a document (probably because of trying to move the cursor), return the ObjectModelElement at it, or null
java.util.Set	getSelectedElements() Deprecated. This method will be renamed to achieve more consistent naming.
java.util.List	getSelectedElementsOrdered() Deprecated. This method will be renamed to achieve more consistent naming.
java.util.List	getSelectedNOMElements() Returns a list of currently selected NOMElements, that is, those highlighted with SELECTION_HIGHLIGHTS.
java.util.Set	getSelectedNOMElementsOrdered() Deprecated. This method will be renamed to achieve more consistent naming.
java.util.Set	getSelectedTextElements() Deprecated. Use getHighlightedTextElements(NTextArea.SELECTION_HIGHLIGHTS)
int	getSelectionEndPosition() Returns the position of the selection end, or -1 if nothing is selected.
int	getSelectionStartPosition() Returns the position of the selection start, or -1 if nothing is selected.
java.util.Set	getTextElements(ObjectModelElement ome) return the set of screen elements (NTextElements) represented by the given object model element.
void	gotoDocumentEnd() Scroll to the end of the displayed text
void	gotoDocumentStart() Scroll to the start of the displayed text
javax.swing.text.Style	insertCopyOfStyle(NTextElement element, javax.swing.text.Style templateStyle, java.lang.String name) Inserts a copy of the given style for the style hierarchy of the NTEXTelement, using the given name (which should be unique).
void	insertDisplayElement(ObjectModelElement newElement, ObjectModelElement parent, int position) Insert a new text element into the parent at the given position
void	insertElement(NTextElement te, int pos) This method inserts NTextElement e in the NTA at the certain position Positions of the elements in the NTA are refreshed.
boolean	isResultRelevant(NOMElement result) Is the given query result relevant to this text area?
void	newSelection(int dot, int mark) WRITE BETTER DOCUMENTATION HERE! THIS IS OBSCURE This latest version extends the highlighting to NOMObjectModelElements instead of NTextElements.
void	newTimeSelection(int dot, int mark) the user has highlighted a bit of text while holding down control, so reset the time on the clock to the timing data stored with the data corresponding to the selection
int	print(java.awt.Graphics g, java.awt.print.PageFormat pf, int pi) print the document: calls the print method in NITEStyledDocument.
void	printTextArea() Print the document if an print service can be found - winds up calling the print method in the NITEStyledDocument.
void	redisplayElement(NTextElement element, java.lang.String newstring) This version of redisplay takes the actual text element that needs to be replaced as an argument along with the new text.
void	redisplayElement(ObjectModelElement element) Method redisplayElement.
void	redisplayElement(ObjectModelElement element, java.lang.String oldstring, java.lang.String newstring) Method redisplayElement.
void	redisplayTextElement(NTextElement oldEl, NTextElement newEl) swap one NTextElement for another
void	removeDisplayComponent(ObjectModelElement element) Remove all representations of the ObjectModelElement from the NTextArea.
void	removeHighlighted(int type, NTextElement el) Remove the highlights from the given element for the given highlighting type.
void	removeNTASelectionListener(NTASelectionListener listener)
javax.swing.text.Style	removeStyleFromChain(NTextElement element, Predicate isAlignStyle) Searches the style hierarchy on the text element and removes the first style that satisfies the predicate.
void	scrollTo(NTextElement el) Chopped out of the old setTimeHighlighted to scroll the window to highlight a particular element
void	setAutoScroll(boolean scrolling) Turn off scrolling to the appropriate place in the NTextArea when highlights are applied.
void	setClock(Clock clock) Set the Clock to which this TimeHandler is registered
void	setHighlighted(int type, java.util.Iterator elements) Passes on to setHighlighted(int type, NTextElement el)
void	setHighlighted(int type, NTextElement el) TO DOCUYMENT: SETHIGHLIGHTED WILL MOVE THE CARET!!!!!!!!! this means that you should be careful with setting highlights from your own caretlisteners, because they would get a loop-callback! Highlight the given element as 'highlighted' for the given type of highlighting.
void	setHighlighted(int type, NTextElement el, javax.swing.text.Style templatestyle)
void	setHighlighted(int type, ObjectModelElement el) Highlight the given ObjectModelElement(typically corresponding to a NOMElement) with a given highlight type and default style
void	setHighlighted(int type, ObjectModelElement el, javax.swing.text.Style templateStyle) Highlight the given ObjectModelElement(typically corresponding to a NOMElement) with a given highlight type, using the specified style
void	setHighlighted(int type, java.util.Set elements) Passes on to setHighlighted(int type, NTextElement el)
void	setHighlightingStyle(int type, javax.swing.text.Style newStyle) THIS is the method that you call if you want to have your own special Style for showing highlighting.
void	setQueryHighlightColor(java.awt.Color color) set the colour of the highlighting for queries.
void	setReplayEnabled(boolean value) turn off media / time playing ability for this text area.
void	setSelected(ObjectModelElement el) A convenience method to highlight a given object model element as if it was selected by the user.
void	setTime(double t) Broadcast a new time to any concurrent TimeHandlers
void	setTimeHighlightColor(java.awt.Color color) this method is NOT preferred: use setHighlightingStyle.
void	setTimeSpan(double start, double end) Broadcast a new time span to any concurrent TimeHandlers
void	showTimeSpan(double start, double end) time alignment is reimplemented in this class using a time alignment style.

Methods inherited from class javax.swing.JTextPane

addStyle, getCharacterAttributes, getInputAttributes, getLogicalStyle, getParagraphAttributes, getStyle, getStyledDocument, getUIClassID, insertComponent, insertIcon, removeStyle, replaceSelection, setCharacterAttributes, setDocument, setEditorKit, setLogicalStyle, setParagraphAttributes, setStyledDocument

Methods inherited from class javax.swing.JEditorPane

addHyperlinkListener, createEditorKitForContentType, fireHyperlinkUpdate, getAccessibleContext, getContentType, getEditorKit, getEditorKitClassNameForContentType, getEditorKitForContentType, getHyperlinkListeners, getPage, getPreferredSize, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getText, read, registerEditorKitForContentType, registerEditorKitForContentType, removeHyperlinkListener, scrollToReference, setContentType, setEditorKitForContentType, setPage, setPage, setText

Methods inherited from class javax.swing.text.JTextComponent

addInputMethodListener, addKeymap, copy, cut, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, read, removeCaretListener, removeKeymap, removeNotify, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, updateUI, viewToModel, write

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SELECTION_HIGHLIGHTS

public static final int SELECTION_HIGHLIGHTS

See Also:

Constant Field Values

TIME_HIGHLIGHTS

public static final int TIME_HIGHLIGHTS

See Also:

Constant Field Values

QUERY_HIGHLIGHTS

public static final int QUERY_HIGHLIGHTS

See Also:

Constant Field Values

USER_HIGHLIGHTS

public static final int USER_HIGHLIGHTS

See Also:

Constant Field Values

Constructor Detail

NTextArea

public NTextArea()

create a screen area for the display of textual information with syncing-to-signal and search highlighting functionality.

Method Detail

addCaretListener

public void addCaretListener(javax.swing.event.CaretListener newl)

Overrides:

addCaretListener in class javax.swing.text.JTextComponent

acceptResults

public void acceptResults(java.util.List results)

Description copied from interface: SimpleQueryResultHandler

Accept the given list of query results, which can contain a mixture of NOMElements and further lists.

Specified by:

acceptResults in interface SimpleQueryResultHandler

Parameters:

results - the results.

acceptQueryResults

public void acceptQueryResults(java.util.List results)

display query results (arg should be a list of NOMElements). Old query highlights are removed. New results are highlighted. Afterwardss, getHighlightedTextElements(QUEYR_HIGH) contains the corresponding text elements.

Specified by:

acceptQueryResults in interface QueryResultHandler

acceptQueryResult

public void acceptQueryResult(NOMElement result)

display query result Old query highlights are removed. New results are highlighted. Afterwardss, getHighlightedTextElements(QUEYR_HIGH) contains the corresponding text elements.

Specified by:

acceptQueryResult in interface QueryResultHandler

isResultRelevant

public boolean isResultRelevant(NOMElement result)

Is the given query result relevant to this text area?

Parameters:

result - the result.

Returns:

true if the result is relevant.

setQueryHighlightColor

public void setQueryHighlightColor(java.awt.Color color)

set the colour of the highlighting for queries. IGNORED. use setHighlightingStyle

Specified by:

setQueryHighlightColor in interface QueryResultHandler

printTextArea

public void printTextArea()

Print the document if an print service can be found - winds up calling the print method in the NITEStyledDocument.

print

public int print(java.awt.Graphics g,
                 java.awt.print.PageFormat pf,
                 int pi)
          throws java.awt.print.PrinterException

print the document: calls the print method in NITEStyledDocument.

Specified by:

print in interface java.awt.print.Printable

Throws:

java.awt.print.PrinterException

clear

public void clear()

clear the display and (re)initialise all indexes

addNTASelectionListener

public void addNTASelectionListener(NTASelectionListener newListener)

removeNTASelectionListener

public void removeNTASelectionListener(NTASelectionListener listener)

newSelection

public void newSelection(int dot,
                         int mark)

WRITE BETTER DOCUMENTATION HERE! THIS IS OBSCURE This latest version extends the highlighting to NOMObjectModelElements instead of NTextElements. This method gets called whenever the user clicks or drags a new selection in the NTextArea.

The superclass (JTextPane) uses a Caret for keeping track of GUI manipulations that manipulate the cursor in text, such as click or drag. The NTASelectionTracker of this NTextArea keeps track of changes in the caret. Whenever the caret changes (i.e. the user wants to change the selection), the tracker calls this newselection method. We usually want to select only complete NTextElemetns, even if the user dragged only a few words or characters. The newSelection method interprets the caret span, determines which NTextElements should be considered 'selected', takes care of proper highlighting and makes sure that the relevant elements are made available as being 'selected' (getSelectedTextElements and getSelectedElements). [DR: this is changed into getHighlightedTextElements NB: the Caret that originally caused this call is left unchanged!!! this means that the Caret does NOT always reflect the exact selection and highlighting information!

newTimeSelection

public void newTimeSelection(int dot,
                             int mark)

the user has highlighted a bit of text while holding down control, so reset the time on the clock to the timing data stored with the data corresponding to the selection

gotoDocumentStart

public void gotoDocumentStart()

Scroll to the start of the displayed text

gotoDocumentEnd

public void gotoDocumentEnd()

Scroll to the end of the displayed text

scrollTo

public void scrollTo(NTextElement el)

Chopped out of the old setTimeHighlighted to scroll the window to highlight a particular element

getElementsBetweenTimes

public java.util.Set getElementsBetweenTimes(double start,
                                             double end)

return a set of NTextElements which appear in the span

setAutoScroll

public void setAutoScroll(boolean scrolling)

Turn off scrolling to the appropriate place in the NTextArea when highlights are applied. This is mainly to get round a (Swing?) bug which ocassionally happens: scrollRectToVisible seems to hang and doesn't raise an exception.

showTimeSpan

public void showTimeSpan(double start,
                         double end)

time alignment is reimplemented in this class using a time alignment style.

The actual work is done by setTimeAlignmentStyle and showTimeSpan

Note the following: If we align using a style, and the time alignment should be removed again, we do want to remove the style, but we do NOT want to remove possible styles that were present on the text before alignment. So we cannot just set an attribute such as ITALIC to true, and set it to false again afterwards. So what we do is the following. Internally we create a Style object used as "rubber stamp template". When a certain NTextElement should be highlighted, we copy this style giving it a unique name, give it as parent the current style of that NTextElement, and set this style as the new style of the NTextElement. When the timealignment is removed for this element, we just remove that new style again from the chain of styles for the NTextElement.

One problem though: other components may have added yet more style-children. So we cannot just take the first style, remove it and use its parent again; we need to search through the style-chain upwards to find the correct style. For this the time-alignment style for the NTextElement should have a wel-defined name, e.g. a unique ID prefixed by TIME_ALIGNMENT_STYLENAME.

To keep track of the highlighted NTextElements we store them in a Set.

acceptTimeChange

public void acceptTimeChange(double t)

Accept a new time (generally from another registered TimeHandler) and highlight the appropriate elements.

Specified by:

acceptTimeChange in interface TimeHandler

acceptTimeSpanChange

public void acceptTimeSpanChange(double start,
                                 double end)

Accept a new time span from another registered time handler and highlight the appropriate elements.

Specified by:

acceptTimeSpanChange in interface TimeHandler

setTime

public void setTime(double t)

Broadcast a new time to any concurrent TimeHandlers

Specified by:

setTime in interface TimeHandler

setTimeSpan

public void setTimeSpan(double start,
                        double end)

Broadcast a new time span to any concurrent TimeHandlers

Specified by:

setTimeSpan in interface TimeHandler

getClock

public Clock getClock()

Return the Clock that is currently syncronising this TimeHandler

Specified by:

getClock in interface TimeHandler

setClock

public void setClock(Clock clock)

Set the Clock to which this TimeHandler is registered

Specified by:

setClock in interface TimeHandler

setTimeHighlightColor

public void setTimeHighlightColor(java.awt.Color color)

this method is NOT preferred: use setHighlightingStyle. This method is kept for backwards compatibility.

Specified by:

setTimeHighlightColor in interface TimeHandler

setHighlightingStyle

public void setHighlightingStyle(int type,
                                 javax.swing.text.Style newStyle)

THIS is the method that you call if you want to have your own special Style for showing highlighting. You are absolutely free in what the style looks like: colour, underline, strikethrough, font....

clearHighlights

public void clearHighlights(int type)

Clears all highlights of the given type. Type is one of xx, xx or xx. Afterwards, the visual highlighting is removed and the set of highlighted elements for the given type is empty.

setHighlighted

public void setHighlighted(int type,
                           NTextElement el)

TO DOCUYMENT: SETHIGHLIGHTED WILL MOVE THE CARET!!!!!!!!! this means that you should be careful with setting highlights from your own caretlisteners, because they would get a loop-callback! Highlight the given element as 'highlighted' for the given type of highlighting. Sets the visual highlighting for the given element. This element will also be returned subsequently by a call to getHighlighted. Type is ONE of xx,xx or xx. PRE: element was NOT yet highlighted for that type!

following documetnation should be rewritten highlighted is reimplemented in this class using a highlighted style.

Note the following: If we highlighted using a style, and the highlighted should be removed again, we do want to remove the style, but we do NOT want to remove possible styles that were present on the text before highlighting. So we cannot just set an attribute such as ITALIC to true, and set it to false again afterwards. So what we do is the following. Internally we create a Style object used as "rubber stamp template". When a certain NTextElement should be highlighted, we copy this style giving it a unique name, give it as parent the current style of that NTextElement, and set this style as the new style of the NTextElement. When the highlight is removed for this element, we just remove that new style again from the chain of styles for the NTextElement.

One problem though: other components may have added yet more style-children. So we cannot just take the first style, remove it and use its parent again; we need to search through the style-chain upwards to find the correct style. For this the highlighted style for the NTextElement should have a wel-defined name, e.g. a unique ID prefixed by some constant string prefix.

To keep track of the highlighted NTextElements we store them in Sets.

Note that the SelectionListeners are not notified.

setHighlighted

public void setHighlighted(int type,
                           NTextElement el,
                           javax.swing.text.Style templatestyle)

removeHighlighted

public void removeHighlighted(int type,
                              NTextElement el)

Remove the highlights from the given element for the given highlighting type.

setHighlighted

public void setHighlighted(int type,
                           ObjectModelElement el)

Highlight the given ObjectModelElement(typically corresponding to a NOMElement) with a given highlight type and default style

setHighlighted

public void setHighlighted(int type,
                           ObjectModelElement el,
                           javax.swing.text.Style templateStyle)

Highlight the given ObjectModelElement(typically corresponding to a NOMElement) with a given highlight type, using the specified style

setHighlighted

public void setHighlighted(int type,
                           java.util.Set elements)

Passes on to setHighlighted(int type, NTextElement el)

setHighlighted

public void setHighlighted(int type,
                           java.util.Iterator elements)

Passes on to setHighlighted(int type, NTextElement el)

setSelected

public void setSelected(ObjectModelElement el)

A convenience method to highlight a given object model element as if it was selected by the user. After call to this method, X will also be returned by getHighlightedTextElements(SELECTION_HIGHLIGHTS). Does NOT adjust dot/mark position of the actual selection. Equivalent to a call to setHighlighted(SELECTION_HIGHLIGHTS, X)" except that the selection listeners are notified.

clearSelection

public void clearSelection()

A convenience method to clear all selection highlights. After a call tot his method getHighlightedTextElements(SELECTION_HIGHLIGHTS) will return an empty set. However, the default dot and mark position for the cursor will not be affected

getHighlightedTextElements

public java.util.SortedSet getHighlightedTextElements(int type)

Returns a (shared) set of highlighted NTextElements for the given type. DO NOT MODIFY THE RETURNED SET! The set is not guaranteed to be sorted in any particular order. The method getHighlightedTextElements[TIME_HIGHLIGHTS] renders the method getSelectedTextElements obsolete!

getHighlightedModelElements

public java.util.List getHighlightedModelElements(int type)

Returns a set of ObjectModelElements associated with a highlight for a given type. The elements are ordered by the appearance of the corresponding NTextElements in the transcript, but there is no duplication. If there are several NTextElements associated with the same ObjectModelElement, then the corresponding NOMElement will appear only once, at the earliest possible point in the list ordering. No null elements will be included. This is a convenience wrapper around getHighlightedTextElements to return the NOMElements associated with the text elements it returns. See documentation for getHighlightedTextElements(int).

getHighlightedNOMElements

public java.util.List getHighlightedNOMElements(int type)

Returns a set of NOMElements associated with a highlight for a given type. The elements are ordered by the appearance of the corresponding NTextElements in the transcript, but there is no duplication. If there are several NTextElements associated with the same NOMElement, then the corresponding NOMElement will appear only once, at the earliest possible point in the list ordering. No null elements will be included. This is a convenience wrapper around getHighlightedTextElements to return the NOMElements associated with the text elements it returns. See documentation for getHighlightedTextElements(int).

getSelectedNOMElements

public java.util.List getSelectedNOMElements()

Returns a list of currently selected NOMElements, that is, those highlighted with SELECTION_HIGHLIGHTS. A convenience method equivalent to getHighlightedNOMElements(SELECTION_HIGHLIGHTS);

getSelectedTextElements

public java.util.Set getSelectedTextElements()

Deprecated. Use getHighlightedTextElements(NTextArea.SELECTION_HIGHLIGHTS)

returns a list of the NTextElements currently selected by the user. Shared set, so don't modify it!

getSelectedElements

public java.util.Set getSelectedElements()

Deprecated. This method will be renamed to achieve more consistent naming.

returns a list of the NOMObjectModelElements currently selected by the user.

getSelectedElementsOrdered

public java.util.List getSelectedElementsOrdered()

Deprecated. This method will be renamed to achieve more consistent naming.

returns a list of the NOMObjectModeElements currently selected by the user, guaranteeing to maintain screen order

getSelectedNOMElementsOrdered

public java.util.Set getSelectedNOMElementsOrdered()

Deprecated. This method will be renamed to achieve more consistent naming.

returns a list of the NOMElements currently selected by the user, guaranteeing to maintain screen order

getObjectModelElementAtPosition

public ObjectModelElement getObjectModelElementAtPosition(int position)

Given a position in a document (probably because of trying to move the cursor), return the ObjectModelElement at it, or null

getObjectModelElementAtPoint

public ObjectModelElement getObjectModelElementAtPoint(java.awt.Point clickpoint)

given a Point (most likely a mouseEvent.getPoint() intercepted by a MouseListener), return the ObjctModelElement beneath it (or return null).

getNTextElementAtPosition

public NTextElement getNTextElementAtPosition(int position)

Given a position in a document (probably because of trying to move the cursor), return the NTextElement at it, or null

getNTextElementAtPoint

public NTextElement getNTextElementAtPoint(java.awt.Point clickpoint)

given a Point (most likely a mouseEvent.getPoint() intercepted by a MouseListener), return the NTextElement beneath it (or return null).

getTextElements

public java.util.Set getTextElements(ObjectModelElement ome)

return the set of screen elements (NTextElements) represented by the given object model element. The set is not sorted - the programmer is expected to provide their own sort.

See Also:

NTextElementPositionComparator

getSelectionStartPosition

public int getSelectionStartPosition()

Returns the position of the selection start, or -1 if nothing is selected. The selection start is determined by the contents of getHighlightedTextElements(SELECTION_HIGHLIGHTS) rather than the actual java selection, which is a subset of selection highlights. See newSelection(int, int)

getSelectionEndPosition

public int getSelectionEndPosition()

Returns the position of the selection end, or -1 if nothing is selected. The selection end is determined by the contents of getHighlightedTextElements(SELECTION_HIGHLIGHTS) rather than the actual java selection, which is a subset of selection highlights. See newSelection(int, int)

addElement

public void addElement(NTextElement te)

Inserts the content specified in the text element argument at the end of the current document. The content is displayed with the style attributes

Parameters:

te - The element to be inserted into the document

getMaxTime

public double getMaxTime()

get the largest end time of any NTextElement so far added to this NTextArea. Returns UNTIMED if no timed elements

Specified by:

getMaxTime in interface TimeHandler

addElement

public void addElement(NTextElement newEl,
                       NTextElement oldEl)

Insert a new NTextElement into the document after the given existing element. The new element must be the first arg! DR: this method seems to add the text BEFORE the given element?

redisplayElement

public void redisplayElement(ObjectModelElement element)

Method redisplayElement. This is used to update the display after a change has been made to the xml. This version assumes the text element is displaying the value of its 'displayedAttribute' attribute or PCDATA, but nothing else: if the NTextElement's text has been updated manually, nothing will happen!

redisplayTextElement

public void redisplayTextElement(NTextElement oldEl,
                                 NTextElement newEl)

swap one NTextElement for another

redisplayElement

public void redisplayElement(ObjectModelElement element,
                             java.lang.String oldstring,
                             java.lang.String newstring)

Method redisplayElement. This is used to update the display after a change has been made to the xml, however we make no assumption here about what is displayed - we find all the on-screen representations and only replace the one(s) that match the first string argument. The second string argument is the new text.

redisplayElement

public void redisplayElement(NTextElement element,
                             java.lang.String newstring)

This version of redisplay takes the actual text element that needs to be replaced as an argument along with the new text.

removeDisplayComponent

public void removeDisplayComponent(ObjectModelElement element)

Remove all representations of the ObjectModelElement from the NTextArea.

insertDisplayElement

public void insertDisplayElement(ObjectModelElement newElement,
                                 ObjectModelElement parent,
                                 int position)

Insert a new text element into the parent at the given position

removeStyleFromChain

public javax.swing.text.Style removeStyleFromChain(NTextElement element,
                                                   Predicate isAlignStyle)

Searches the style hierarchy on the text element and removes the first style that satisfies the predicate. Also remove the style from the As an example of combining the predicate with the name used in insertCopyOfStyle method, see showTimeSpan(double start, double end) Returns the removed style

TODO: improve documentation here with a picture of this style hierarchy, highlightinh what will be removed

insertElement

public void insertElement(NTextElement te,
                          int pos)

This method inserts NTextElement e in the NTA at the certain position Positions of the elements in the NTA are refreshed.

insertCopyOfStyle

public javax.swing.text.Style insertCopyOfStyle(NTextElement element,
                                                javax.swing.text.Style templateStyle,
                                                java.lang.String name)

Inserts a copy of the given style for the style hierarchy of the NTEXTelement, using the given name (which should be unique).

setReplayEnabled

public void setReplayEnabled(boolean value)

turn off media / time playing ability for this text area. The control-key listener is removed from NITEStyledDocument so media can't be played