Class BasicTextUI
- All Implemented Interfaces:
- ViewFactory
- Direct Known Subclasses:
- BasicEditorPaneUI,- BasicTextAreaUI,- BasicTextFieldUI,- DefaultTextUI
 Basis of a text components look-and-feel.  This provides the
 basic editor view and controller services that may be useful
 when creating a look-and-feel for an extension of
 JTextComponent.
 
 Most state is held in the associated JTextComponent
 as bound properties, and the UI installs default values for the
 various properties.  This default will install something for
 all of the properties.  Typically, a LAF implementation will
 do more however.  At a minimum, a LAF would generally install
 key bindings.
 
 This class also provides some concurrency support if the
 Document associated with the JTextComponent is a subclass of
 AbstractDocument.  Access to the View (or View hierarchy) is
 serialized between any thread mutating the model and the Swing
 event thread (which is expected to render, do model/view coordinate
 translation, etc).  Any access to the root view should first
 acquire a read-lock on the AbstractDocument and release that lock
 in a finally block.
 
 An important method to define is the getPropertyPrefix() method
 which is used as the basis of the keys used to fetch defaults
 from the UIManager.  The string should reflect the type of
 TextUI (eg. TextField, TextArea, etc) without the particular
 LAF part of the name (eg Metal, Motif, etc).
 
To build a view of the model, one of the following strategies can be employed.
- 
 One strategy is to simply redefine the
 ViewFactory interface in the UI.  By default, this UI itself acts
 as the factory for View implementations.  This is useful
 for simple factories.  To do this reimplement the
 create(javax.swing.text.Element)method.
- A common strategy for creating more complex types of documents is to have the EditorKit implementation return a factory. Since the EditorKit ties all of the pieces necessary to maintain a type of document, the factory is typically an important part of that and should be produced by the EditorKit implementation.
 Warning:
 Serialized objects of this class will not be compatible with
 future Swing releases. The current serialization support is
 appropriate for short term storage or RMI between applications running
 the same version of Swing.  As of 1.4, support for long term storage
 of all JavaBeans
 has been added to the java.beans package.
 Please see XMLEncoder.
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic classDefault implementation of the interfaceCaret.static classDefault implementation of the interfaceHighlighter.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionCreates a view for an element.Creates a view for an element.protected CaretCreates the object to use for a caret.protected HighlighterCreates the object to use for adding highlights.protected KeymapCreates the keymap to use for the text component, and installs any necessary bindings into it.voiddamageRange(JTextComponent tc, int p0, int p1) Causes the portion of the view responsible for the given part of the model to be repainted.voiddamageRange(JTextComponent t, int p0, int p1, Position.Bias p0Bias, Position.Bias p1Bias) Causes the portion of the view responsible for the given part of the model to be repainted.protected final JTextComponentFetches the text component associated with this UI implementation.Fetches the EditorKit for the UI.protected StringFetches the name of the keymap that will be installed/used by default for this UI.Gets the maximum size for the editor component.Gets the minimum size for the editor component.intgetNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.Gets the preferred size for the editor component.protected abstract StringGets the name used as a key to look up properties through the UIManager.Fetches a View with the allocation of the associated text component (i.e. the root of the hierarchy) that can be traversed to determine how the model is being represented spatially.getToolTipText(JTextComponent t, Point pt) Returns the string to be used as the tooltip at the passed in location.protected RectangleGets the allocation to give the root View.protected voidInitializes component properties, such as font, foreground, background, caret color, selection color, selected text color, disabled text color, border, and margin.protected voidRegisters keyboard actions.protected voidInstalls listeners for the UI.voidInstalls the UI for a component.protected voidFlags model changes.modelToView(JTextComponent tc, int pos) Deprecated.modelToView(JTextComponent tc, int pos, Position.Bias bias) Deprecated.final voidpaint(Graphics g, JComponent c) Paints the interface.protected voidPaints a background for the view.protected voidPaints the interface safely with a guarantee that the model won't change from the view of this thread.protected voidThis method gets called when a bound property is changed on the associated JTextComponent.protected final voidSets the current root of the view hierarchy and calls invalidate().protected voidSets the component properties that have not been explicitly overridden tonull.protected voidUnregisters keyboard actions.protected voidUninstalls listeners for the UI.voidDeinstalls the UI for a component.voidupdate(Graphics g, JComponent c) Superclass paints background in an uncontrollable way (i.e. one might want an image tiled into the background).intviewToModel(JTextComponent tc, Point pt) Deprecated.intviewToModel(JTextComponent tc, Point pt, Position.Bias[] biasReturn) Deprecated.Methods declared in class javax.swing.plaf.TextUIgetToolTipText2D, modelToView2D, viewToModel2DMethods declared in class javax.swing.plaf.ComponentUIcontains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
- 
Constructor Details- 
BasicTextUIpublic BasicTextUI()Creates a new UI.
 
- 
- 
Method Details- 
createCaretCreates the object to use for a caret. By default an instance of BasicCaret is created. This method can be redefined to provide something else that implements the InputPosition interface or a subclass of JCaret.- Returns:
- the caret object
 
- 
createHighlighterCreates the object to use for adding highlights. By default an instance of BasicHighlighter is created. This method can be redefined to provide something else that implements the Highlighter interface or a subclass of DefaultHighlighter.- Returns:
- the highlighter
 
- 
getKeymapNameFetches the name of the keymap that will be installed/used by default for this UI. This is implemented to create a name based upon the classname. The name is the name of the class with the package prefix removed.- Returns:
- the name
 
- 
createKeymapCreates the keymap to use for the text component, and installs any necessary bindings into it. By default, the keymap is shared between all instances of this type of TextUI. The keymap has the name defined by the getKeymapName method. If the keymap is not found, then DEFAULT_KEYMAP from JTextComponent is used.The set of bindings used to create the keymap is fetched from the UIManager using a key formed by combining the getPropertyPrefix()method and the string.keyBindings. The type is expected to beJTextComponent.KeyBinding[].- Returns:
- the keymap
- See Also:
 
- 
propertyChangeThis method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses. This is implemented to do nothing (i.e. the response to properties in JTextComponent itself are handled prior to calling this method). This implementation updates the background of the text component if the editable and/or enabled state changes.- Parameters:
- evt- the property change event
 
- 
getPropertyPrefixGets the name used as a key to look up properties through the UIManager. This is used as a prefix to all the standard text properties.- Returns:
- the name
 
- 
installDefaultsprotected void installDefaults()Initializes component properties, such as font, foreground, background, caret color, selection color, selected text color, disabled text color, border, and margin. Each property is set if its current value is either null or a UIResource.- See Also:
 
- 
uninstallDefaultsprotected void uninstallDefaults()Sets the component properties that have not been explicitly overridden tonull. A property is considered overridden if its current value is not aUIResource.- See Also:
 
- 
installListenersprotected void installListeners()Installs listeners for the UI.
- 
uninstallListenersprotected void uninstallListeners()Uninstalls listeners for the UI.
- 
installKeyboardActionsprotected void installKeyboardActions()Registers keyboard actions.
- 
uninstallKeyboardActionsprotected void uninstallKeyboardActions()Unregisters keyboard actions.
- 
paintBackgroundPaints a background for the view. This will only be called if isOpaque() on the associated component is true. The default is to paint the background color of the component.- Parameters:
- g- the graphics context
 
- 
getComponentFetches the text component associated with this UI implementation. This will be null until the ui has been installed.- Returns:
- the editor component
 
- 
modelChangedprotected void modelChanged()Flags model changes. This is called whenever the model has changed. It is implemented to rebuild the view hierarchy to represent the default root element of the associated model.
- 
setViewSets the current root of the view hierarchy and calls invalidate(). If there were any child components, they will be removed (i.e. there are assumed to have come from components embedded in views).- Parameters:
- v- the root view
 
- 
paintSafelyPaints the interface safely with a guarantee that the model won't change from the view of this thread. This does the following things, rendering from back to front.- If the component is marked as opaque, the background is painted in the current background color of the component.
- The highlights (if any) are painted.
- The view hierarchy is painted.
- The caret is painted.
 - Parameters:
- g- the graphics context
 
- 
installUIInstalls the UI for a component. This does the following things.- Sets the associated component to opaque if the opaque property has not already been set by the client program. This will cause the component's background color to be painted.
- 
 Installs the default caret and highlighter into the
 associated component. These properties are only set if their
 current value is either nullor an instance ofUIResource.
- Attaches to the editor and model. If there is no model, a default one is created.
- Creates the view factory and the view hierarchy used to represent the model.
 - Overrides:
- installUIin class- ComponentUI
- Parameters:
- c- the editor component
- See Also:
 
- 
uninstallUIDeinstalls the UI for a component. This removes the listeners, uninstalls the highlighter, removes views, and nulls out the keymap.- Overrides:
- uninstallUIin class- ComponentUI
- Parameters:
- c- the editor component
- See Also:
 
- 
updateSuperclass paints background in an uncontrollable way (i.e. one might want an image tiled into the background). To prevent this from happening twice, this method is reimplemented to simply paint.NOTE: Superclass is also not thread-safe in its rendering of the background, although that is not an issue with the default rendering. - Overrides:
- updatein class- ComponentUI
- Parameters:
- g- the- Graphicscontext in which to paint
- c- the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
- See Also:
 
- 
paintPaints the interface. This is routed to the paintSafely method under the guarantee that the model won't change from the view of this thread while it's rendering (if the associated model is derived from AbstractDocument). This enables the model to potentially be updated asynchronously.- Overrides:
- paintin class- ComponentUI
- Parameters:
- g- the graphics context
- c- the editor component
- See Also:
 
- 
getPreferredSizeGets the preferred size for the editor component. If the component has been given a size prior to receiving this request, it will set the size of the view hierarchy to reflect the size of the component before requesting the preferred size of the view hierarchy. This allows formatted views to format to the current component size before answering the request. Other views don't care about currently formatted size and give the same answer either way.- Overrides:
- getPreferredSizein class- ComponentUI
- Parameters:
- c- the editor component
- Returns:
- the size
- See Also:
 
- 
getMinimumSizeGets the minimum size for the editor component.- Overrides:
- getMinimumSizein class- ComponentUI
- Parameters:
- c- the editor component
- Returns:
- the size
- See Also:
 
- 
getMaximumSizeGets the maximum size for the editor component.- Overrides:
- getMaximumSizein class- ComponentUI
- Parameters:
- c- the editor component
- Returns:
- the size
- See Also:
 
- 
getVisibleEditorRectGets the allocation to give the root View. Due to an unfortunate set of historical events this method is inappropriately named. The Rectangle returned has nothing to do with visibility. The component must have a non-zero positive size for this translation to be computed.- Returns:
- the bounding box for the root view
 
- 
modelToView@Deprecated(since="9") public Rectangle modelToView(JTextComponent tc, int pos) throws BadLocationException Deprecated.Converts the given location in the model to a place in the view coordinate system. The component must have a non-zero positive size for this translation to be computed.- Specified by:
- modelToViewin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- pos- the local location in the model to translate >= 0
- Returns:
- the coordinates as a rectangle, null if the model is not painted
- Throws:
- BadLocationException- if the given position does not represent a valid location in the associated document
- See Also:
 
- 
modelToView@Deprecated(since="9") public Rectangle modelToView(JTextComponent tc, int pos, Position.Bias bias) throws BadLocationException Deprecated.Converts the given location in the model to a place in the view coordinate system. The component must have a non-zero positive size for this translation to be computed.- Specified by:
- modelToViewin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- pos- the local location in the model to translate >= 0
- bias- the bias for the position
- Returns:
- the coordinates as a rectangle, null if the model is not painted
- Throws:
- BadLocationException- if the given position does not represent a valid location in the associated document
- See Also:
 
- 
viewToModelDeprecated.Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a non-zero positive size for this translation to be computed.- Specified by:
- viewToModelin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- pt- the location in the view to translate. This should be in the same coordinate system as the mouse events.
- Returns:
- the offset from the start of the document >= 0, -1 if not painted
- See Also:
 
- 
viewToModel@Deprecated(since="9") public int viewToModel(JTextComponent tc, Point pt, Position.Bias[] biasReturn) Deprecated.Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a non-zero positive size for this translation to be computed.- Specified by:
- viewToModelin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- pt- the location in the view to translate. This should be in the same coordinate system as the mouse events.
- biasReturn- filled in by this method to indicate whether the point given is closer to the previous or the next character in the model
- Returns:
- the offset from the start of the document >= 0, -1 if the component doesn't yet have a positive size.
- See Also:
 
- 
getNextVisualPositionFrompublic int getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) throws BadLocationException Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.- Specified by:
- getNextVisualPositionFromin class- TextUI
- Parameters:
- t- the text component for which this UI is installed
- pos- the position to convert >= 0
- b- the bias for the position
- direction- the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH
- biasRet- an array to contain the bias for the returned position
- Returns:
- the location within the model that best represents the next location visual position
- Throws:
- BadLocationException- for a bad location within a document model
 
- 
damageRangeCauses the portion of the view responsible for the given part of the model to be repainted. Does nothing if the view is not currently painted.- Specified by:
- damageRangein class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- p0- the beginning of the range >= 0
- p1- the end of the range >= p0
- See Also:
 
- 
damageRangepublic void damageRange(JTextComponent t, int p0, int p1, Position.Bias p0Bias, Position.Bias p1Bias) Causes the portion of the view responsible for the given part of the model to be repainted.- Specified by:
- damageRangein class- TextUI
- Parameters:
- t- the text component for which this UI is installed
- p0- the beginning of the range >= 0
- p1- the end of the range >= p0
- p0Bias- the bias of the first character position, toward the previous character or the next character
- p1Bias- the bias of the second character position, toward the previous character or the next character
 
- 
getEditorKitFetches the EditorKit for the UI.- Specified by:
- getEditorKitin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- Returns:
- the editor capabilities
- See Also:
 
- 
getRootViewFetches a View with the allocation of the associated text component (i.e. the root of the hierarchy) that can be traversed to determine how the model is being represented spatially.Warning: The View hierarchy can be traversed from the root view, and other things can be done as well. Things done in this way cannot be protected like simple method calls through the TextUI. Therefore, proper operation in the presence of concurrency must be arranged by any logic that calls this method! - Specified by:
- getRootViewin class- TextUI
- Parameters:
- tc- the text component for which this UI is installed
- Returns:
- the view
- See Also:
 
- 
getToolTipTextReturns the string to be used as the tooltip at the passed in location. This forwards the method onto the root View.- Overrides:
- getToolTipTextin class- TextUI
- Parameters:
- t- the text component for which this UI is installed
- pt- a- Pointspecifying location for which to get a tooltip
- Returns:
- a Stringcontaining the tooltip
- Since:
- 1.4
- See Also:
 
- 
createCreates a view for an element. If a subclass wishes to directly implement the factory producing the view(s), it should reimplement this method. By default it simply returns null indicating it is unable to represent the element.- Specified by:
- createin interface- ViewFactory
- Parameters:
- elem- the element
- Returns:
- the view
- See Also:
 
- 
createCreates a view for an element. If a subclass wishes to directly implement the factory producing the view(s), it should reimplement this method. By default it simply returns null indicating it is unable to represent the part of the element.- Parameters:
- elem- the element
- p0- the starting offset >= 0
- p1- the ending offset >= p0
- Returns:
- the view
 
 
- 
TextUI.modelToView2D(JTextComponent, int, Position.Bias)