net.sourceforge.nite.gui.textviewer
Class NTextArea

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.text.JTextComponent
                  extended by javax.swing.JEditorPane
                      extended by javax.swing.JTextPane
                          extended by 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:
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