JTextComponent
is the base class for swing text
components. It tries to be compatible with the
java.awt.TextComponent
class
where it can reasonably do so. Also provided are other services
for additional flexibility (beyond the pluggable UI and bean
support).
You can find information on how to use the functionality
this class provides in
General Rules for Using Text Components,
a section in The Java Tutorial.
CaretListener
interface that have been registered with the text component.
The UI will install a default caret unless a customized caret
has been set. DefaultCaret
tries to make itself visible which may lead to scrolling
of a text component within JScrollPane
. The default caret
behavior can be changed by the DefaultCaret#setUpdatePolicy
method.
Action
interface,
using the TextAction
implementation.
The set of commands supported by the text component can be
found with the #getActions
method. These actions
can be bound to key events, fired from buttons, etc.
A javax.swing.text.Keymap
lets an application bind key
strokes to actions.
In order to allow keymaps to be shared across multiple text components, they
can use actions that extend TextAction
.
TextAction
can determine which JTextComponent
most recently has or had focus and therefore is the subject of
the action (In the case that the ActionEvent
sent to the action doesn't contain the target text component as its source).
The input method framework
lets text components interact with input methods, separate software
components that preprocess events to let users enter thousands of
different characters using keyboards with far fewer keys.
JTextComponent
is an active client of
the framework, so it implements the preferred user interface for interacting
with input methods. As a consequence, some key events do not reach the text
component because they are handled by an input method, and some text input
reaches the text component as committed text within an java.awt.event.InputMethodEvent
instead of as a key event.
The complete text input is the combination of the characters in
keyTyped
key events and committed text in input method events.
The AWT listener model lets applications attach event listeners to components in order to bind events to actions. Swing encourages the use of keymaps instead of listeners, but maintains compatibility with listeners by giving the listeners a chance to steal an event by consuming it.
Keyboard event and input method events are handled in the following stages, with each stage capable of consuming the event:
Stage |
KeyEvent |
InputMethodEvent |
---|---|---|
1. | input methods | (generated here) |
2. | focus manager | |
3. | registered key listeners | registered input method listeners |
4. | input method handling in JTextComponent | |
5. | keymap handling using the current keymap | |
6. | keyboard handling in JComponent (e.g. accelerators, component navigation, etc.) |
To maintain compatibility with applications that listen to key events but are not aware of input method events, the input method handling in stage 4 provides a compatibility mode for components that do not process input method events. For these components, the committed text is converted to keyTyped key events and processed in the key event pipeline starting at stage 3 instead of in the input method event pipeline.
By default the component will create a keymap (named DEFAULT_KEYMAP) that is shared by all JTextComponent instances as the default keymap. Typically a look-and-feel implementation will install a different keymap that resolves to the default keymap for those bindings not found in the different keymap. The minimal bindings include:
The model is defined by the Document interface. This is intended to provide a flexible text storage mechanism that tracks change during edits and can be extended to more sophisticated models. The model interfaces are meant to capture the capabilities of expression given by SGML, a system used to express a wide variety of content. Each modification to the document causes notification of the details of the change to be sent to all observers in the form of a DocumentEvent which allows the views to stay up to date with the model. This event is sent to observers that have implemented the DocumentListener interface and registered interest with the model being observed.
UndoableEdit
records that can be used in conjunction
with a history buffer to provide the undo/redo support.
The support is provided by the Document model, which allows
one to attach UndoableEditListener implementations.
AbstractDocument
describes the assumptions of the protection provided.
The methods that are safe to call asynchronously are marked
with comments.
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 JavaBeansTM
has been added to the java.beans
package.
Please see java.beans.XMLEncoder
.
JTextComponent
.
Listeners for caret events are established, and the pluggable
UI installed. The component is marked as editable. No layout manager
is used, because layout is managed by the view subsystem of text.
The document model is set to null
.getAlignmentY
.
Specifies an alignment to the bottom of the component.getAlignmentY
and
getAlignmentX
. Specifies an alignment to
the center of the componentJTextComponent
instances unless they
have had a different keymap set.getAlignmentX
.
Specifies an alignment to the left side of the component.getAlignmentX
.
Specifies an alignment to the right side of the component.getAlignmentY()
.
Specifies an alignment to the top of the component.registerKeyboardAction
that
means that the command should be invoked when the receiving
component is an ancestor of the focused component or is
itself the focused component.registerKeyboardAction
that
means that the command should be invoked when
the component has the focus.registerKeyboardAction
that
means that the command should be invoked when
the receiving component is in the window that has the focus
or is itself the focused component.
Note: If a component has been added to a container that
has been displayed, validate
must be
called on that container to display the new component.
If multiple components are being added, you can improve
efficiency by calling validate
only once,
after all the components have been added.
Note: If a component has been added to a container that
has been displayed, validate
must be
called on that container to display the new component.
If multiple components are being added, you can improve
efficiency by calling validate
only once,
after all the components have been added.
Note: If a component has been added to a container that
has been displayed, validate
must be
called on that container to display the new component.
If multiple components are being added, you can improve
efficiency by calling validate
only once,
after all the components have been added.
Note: If a component has been added to a container that
has been displayed, validate
must be
called on that container to display the new component.
If multiple components are being added, you can improve
efficiency by calling validate
only once,
after all the components have been added.
This method is obsolete as of 1.1. Please use the
method add(Component, Object)
instead.
listener
so that it will receive
AncestorEvents
when it or any of its ancestors
move or are made visible or invisible.
Events are also sent when the component or its ancestors are added
or removed from the containment hierarchy.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.For information on how mouse wheel events are dispatched, see the class description for MouseWheelEvent .
If l is null
, no exception is thrown and no
action is performed.
KeyboardAction
event listeners.If listener is null, no exception is thrown and no action is performed.
If listener is null, no exception is thrown and no action is performed.
VetoableChangeListener
to the listener list.
The listener is registered for all properties.ComponentOrientation
property of this container
and all components contained within it.false
, this Container is inheriting the
Set from an ancestor, or from the current KeyboardFocusManager.
This method does not cause the image to begin loading. An
application must use the prepareImage
method
to force the loading of an image.
Information on the flags returned by this method can be found
with the discussion of the ImageObserver
interface.
This method does not cause the image to begin loading. An
application must use the prepareImage
method
to force the loading of an image.
The checkImage
method of Component
calls its peer's checkImage
method to calculate
the flags. If this component does not yet have a peer, the
component's toolkit's checkImage
method is called
instead.
Information on the flags returned by this method can be found
with the discussion of the ImageObserver
interface.
Component
's "visible rect rectangle" - the
intersection of the visible rectangles for this component
and all of its ancestors. The return value is stored in
visibleRect
.null
selections.JToolTip
that should be used
to display the tooltip.
Components typically would not override this method,
but it can be used to
cause different tooltips to be displayed differently.VolatileImage
interface.null
selections.processEvent
before returning for 1.1-style
events which have been enabled for the Component
.validate
method instead.
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y) consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
The findComponentAt method is different from getComponentAt in that getComponentAt only searches the Container's immediate children; if the containing component is a Container, findComponentAt will search that child to find a nested component.
The findComponentAt method is different from getComponentAt in that getComponentAt only searches the Container's immediate children; if the containing component is a Container, findComponentAt will search that child to find a nested component.
AccessibleContext
associated with this
JTextComponent
. For text components,
the AccessibleContext
takes the form of an
AccessibleJTextComponent
.
A new AccessibleJTextComponent
instance
is created if necessary.ActionMap
used to determine what
Action
to fire for particular KeyStroke
binding. The returned ActionMap
, unless otherwise
set, will have the ActionMap
from the UI set as the parent.Container.getAlignmentX
to return
the vertical alignment.Container.getAlignmentY
to return
the horizontal alignment.autoscrolls
property.null
if no
border is currently set.Rectangle
object. The bounds specify this
component's width, height, and location relative to
its parent.rv
and returns rv
.
If rv
is null
a new Rectangle
is allocated. This version of getBounds
is useful
if the caller wants to avoid allocating a new Rectangle
object on the heap.putClientProperty
will return
a non-null
value.ColorModel
used to display
the component on the output device.LayoutManager
and Component
subclasses that wish to respect orientation should call this method to
get the component's orientation before performing layout or drawing.JPopupMenu
that assigned for this component.
If this component does not have a JPopupMenu
assigned
to it and getInheritsPopupMenu
is true, this
will return getParent().getComponentPopupMenu()
(assuming
the parent is valid.)
For Java 2 platform v1.3, a KeyStroke
can be associated
with more than one condition.
For example, 'a' could be bound for the two
conditions WHEN_FOCUSED
and
WHEN_IN_FOCUSED_WINDOW
condition.
Cursor.DEFAULT_CURSOR
is returned.dragEnabled
property.DropTarget
associated with this
Component
.setFocusTraversalKeys
for a full description of each key.)
If a Set of traversal keys has not been explicitly defined for this Container, then this Container's parent's Set is returned. If no Set has been explicitly defined for any of this Container's ancestors, then the current KeyboardFocusManager's default Set is returned.
FontMetrics
for the specified Font
.Graphics
object and
then invoke operations on that object to draw on the component.GraphicsConfiguration
associated with this
Component
.
If the Component
has not been assigned a specific
GraphicsConfiguration
,
the GraphicsConfiguration
of the
Component
object's top-level container is
returned.
If the Component
has been created, but not yet added
to a Container
, this method returns null
.component.getBounds().height
, or
component.getSize().height
because it doesn't cause any
heap allocations.InputMap
that is used when the
component has focus.
This is convenience method for getInputMap(WHEN_FOCUSED)
.InputMap
that is used during
condition
.super.getInsets
.Insets
object containing this component's inset
values. The passed-in Insets
object will be reused
if possible.
Calling methods cannot assume that the same object will be returned,
however. All existing values within this object are overwritten.
If insets
is null, this will allocate a new one.null
-named keymaps.FooListener
s
upon this JComponent
.
FooListener
s are registered using the
addFooListener
method.
You can specify the listenerType
argument
with a class literal,
such as
FooListener.class
.
For example, you can query a
JComponent
c
for its mouse listeners with the following code:
MouseListener[] mls = (MouseListener[])(c.getListeners(MouseListener.class));If no such listeners exist, this method returns an empty array.
Due to the asynchronous nature of native event handling, this
method can return outdated values (for instance, after several calls
of setLocation()
in rapid succession). For this
reason, the recommended method of obtaining a component's position is
within java.awt.event.ComponentListener.componentMoved()
,
which is called after the operating system has finished moving the
component.
rv
and returns rv
.
If rv
is null
a new Point
is allocated. This version of getLocation
is useful
if the caller wants to avoid allocating a new Point
object on the heap.null
value
just returns it. If the UI delegate's getMaximumSize
method returns a non-null
value then return that;
otherwise defer to the component's layout manager.null
value
just returns it. If the UI delegate's getMinimumSize
method returns a non-null
value then return that; otherwise
defer to the component's layout manager.Component
's
coordinate space if the Component
is directly under the mouse
pointer, otherwise returns null
.
If the Component
is not showing on the screen, this method
returns null
even if the mouse pointer is above the area
where the Component
would be displayed.
If the Component
is partially or fully obscured by other
Component
s or native windows, this method returns a non-null
value only if the mouse pointer is located above the unobscured part of the
Component
.
For Container
s it returns a non-null value if the mouse is
above the Container
itself or above any of its descendants.
Use
if you need to exclude children.
Sometimes the exact mouse coordinates are not important, and the only thing
that matters is whether a specific Component
is under the mouse
pointer. If the return value of this method is null
, mouse
pointer is not directly above the Component
.
Container
's
coordinate space if the Container
is under the mouse pointer,
otherwise returns null
.
This method is similar to
with the exception
that it can take the Container
's children into account.
If allowChildren
is false
, this method will return
a non-null value only if the mouse pointer is above the Container
directly, not above the part obscured by children.
If allowChildren
is true
, this method returns
a non-null value if the mouse pointer is above Container
or any
of its descendants.NavigationFilter
. NavigationFilter
is used by DefaultCaret
and the default cursor movement
actions as a way to restrict the cursor movement. A null return value
implies the cursor movement and selection should not be restricted.
Returns the Component
set by a prior call to
setNextFocusableComponent(Component)
on this
JComponent
.
null
is truend the look and feel will choose a suitable location.JList
component
is the size required to accommodate all of the cells in its list.
However, the value of preferredScrollableViewportSize
is the size required for JList.getVisibleRowCount
rows.
A component without any properties that would affect the viewport
size should just return getPreferredSize
here.preferredSize
has been set to a
non-null
value just returns it.
If the UI delegate's getPreferredSize
method returns a non null
value then return that;
otherwise defer to the component's layout manager.KeyStrokes
that will initiate
registered actions.JRootPane
ancestor for this component.Scrolling containers, like JScrollPane, will use this method each time the user requests a block scroll.
Scrolling containers, like JViewport, will use this method each time they are validated.
Scrollable
to match the width of the viewport.
For example a normal
text view that supported line wrapping would return true here, since it
would be undesirable for wrapped lines to disappear beyond the right
edge of the viewport. Note that returning true for a Scrollable
whose ancestor is a JScrollPane effectively disables horizontal
scrolling.
Scrolling containers, like JViewport, will use this method each time they are validated.
Scrolling containers, like JScrollPane, will use this method each time the user requests a unit scroll.
TextComponent
. If the selection is
null
or the document empty, returns null
.Dimension
object. The height
field of the Dimension
object contains
this component's height, and the width
field of the Dimension
object contains
this component's width.rv
and returns rv
.
If rv
is null
a new Dimension
object is allocated. This version of getSize
is useful if the caller wants to avoid allocating a new
Dimension
object on the heap.TextComponent
.
If the underlying document is null
,
will give a NullPointerException
.
Note that text is not a bound property, so no PropertyChangeEvent
is fired when it changes. To listen for changes to the text,
use DocumentListener
.null
is returned, Swing will choose a location.
The default implementation returns null
.setToolTipText
.event
.
This will return one of:
setToolTipText
has been invoked with a
non-null
value, it will be returned, otherwise
getToolTipText
on
the UI will be returned.
JTextComponent
does not register
itself with the ToolTipManager
.
This means that tooltips will NOT be shown from the
TextUI
unless registerComponent
has
been invoked on the ToolTipManager
.Window
or Applet
),
or null
if this component has not
been added to any container.transferHandler
property.UIDefaults
key used to
look up the name of the swing.plaf.ComponentUI
class that defines the look and feel
for this component. Most applications will never need to
call this method. Subclasses of JComponent
that support
pluggable look and feel should override this method to
return a UIDefaults
key that maps to the
ComponentUI
subclass that defines their look and feel.Component
's "visible rectangle" - the
intersection of this component's visible rectangle,
new Rectangle(0, 0, getWidth(), getHeight())
,
and all of its ancestors' visible rectangles.component.getBounds().width
, or
component.getSize().width
because it doesn't cause any
heap allocations.component.getBounds().x
, or
component.getLocation().x
because it doesn't cause any
heap allocations.component.getBounds().y
, or
component.getLocation().y
because it doesn't cause any
heap allocations.
This method is intended for use by focus implementations. Client code
should not use this method; instead, it should use
requestFocusInWindow()
.
true
if this Component
is the
focus owner. This method is obsolete, and has been replaced by
isFocusOwner()
.java.util.Hashtable
.
The general contract of hashCode
is:
hashCode
method on each of
the two objects must produce the same integer result.
As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
imageUpdate
method of an ImageObserver
is called when more information about an
image which had been previously requested using an asynchronous
routine such as the drawImage
method of
Graphics
becomes available.
See the definition of imageUpdate
for
more information on this method and its arguments.
The imageUpdate
method of Component
incrementally draws an image on the component as more of the bits
of the image are available.
If the system property awt.image.incrementaldraw
is missing or has the value true
, the image is
incrementally drawn. If the system property has any other value,
then the image is not drawn until it has been completely loaded.
Also, if incremental drawing is in effect, the value of the
system property awt.image.redrawrate
is interpreted
as an integer to give the maximum redraw rate, in milliseconds. If
the system property is missing or cannot be interpreted as an
integer, the redraw rate is once every 100ms.
The interpretation of the x
, y
,
width
, and height
arguments depends on
the value of the infoflags
argument.
false
, this Component is
inheriting its background color from an ancestor.false
, this Component is inheriting
its cursor from an ancestor.A component is made displayable either when it is added to a displayable containment hierarchy or when its containment hierarchy is made displayable. A containment hierarchy is made displayable when its ancestor window is either packed or made visible.
A component is made undisplayable either when it is removed from a displayable containment hierarchy or when its containment hierarchy is made undisplayable. A containment hierarchy is made undisplayable when its ancestor window is disposed.
TextComponent
is editable or not.setEnabled
method.true
for both such
Containers in this case.true
if this Component
is the
focus owner.Component
can become the focus
owner.true
then when
keyboard focus manager searches container hierarchy for focus
traversal policy and encounters this container before any other
container with this property as true or focus cycle roots then
its focus traversal policy will be used instead of focus cycle
root's policy.false
, this
Container will inherit its focus traversal policy from an ancestor.false
, this Component is inheriting its
font from an ancestor.false
, this Component is
inheriting its foreground color from an ancestor.Component
and Container
,
other than the ones defined in this package like Button
or Scrollbar
, are lightweight.
All of the Swing components are lightweights.
This method will always return false
if this component
is not displayable because it is impossible to determine the
weight of an undisplayable component.
Changes this JComponent
's focus traversal keys to
CTRL+TAB and CTRL+SHIFT+TAB. Also prevents
SortingFocusTraversalPolicy
from considering descendants
of this JComponent when computing a focus traversal cycle.
null
value otherwise returns false.setMinimumSize
has been
invoked with a non-null value.An opaque component paints every pixel within its rectangular bounds. A non-opaque component paints only a subset of its pixels or none at all, allowing the pixels underneath it to "show through". Therefore, a component that does not fully paint its pixels provides a degree of transparency.
Subclasses that guarantee to always completely paint their contents should override this method and return true.
JComponent
subclasses that can't make this
guarantee, such as JLayeredPane
,
should override this method to return false.null
value otherwise returns false.true
if this JComponent
should
get focus; otherwise returns false
.
Please see How to Use the Focus Subsystem, a section in The Java Tutorial, for more information.
revalidate
calls by
descendants of this component will cause the entire tree
beginning with this root to be validated.
Returns false by default. JScrollPane
overrides
this method and returns true.Frame
objects.System.out
.
The immediate children of the container are printed with
an indentation of indent+1
. The children
of those children are printed at indent+2
and so on.
The immediate children of the container are printed with
an indentation of indent+1
. The children
of those children are printed at indent+2
and so on.
Loads a keymap with a bunch of bindings. This can be used to take a static table of definitions and load them into some keymap. The following example illustrates an example of binding some keys to the cut, copy, and paste actions associated with a JTextComponent. A code fragment to accomplish this might look as follows:
static final JTextComponent.KeyBinding[] defaultBindings = {
new JTextComponent.KeyBinding(
KeyStroke.getKeyStroke(KeyEvent.VK_C, InputEvent.CTRL_MASK),
DefaultEditorKit.copyAction),
new JTextComponent.KeyBinding(
KeyStroke.getKeyStroke(KeyEvent.VK_V, InputEvent.CTRL_MASK),
DefaultEditorKit.pasteAction),
new JTextComponent.KeyBinding(
KeyStroke.getKeyStroke(KeyEvent.VK_X, InputEvent.CTRL_MASK),
DefaultEditorKit.cutAction),
};
JTextComponent c = new JTextPane();
Keymap k = c.getKeymap();
JTextComponent.loadKeymap(k, defaultBindings, c.getActions());
The sets of bindings and actions may be empty but must be
non-null
.setCaretPosition
was
called. This forms a selection.
If the document is null
, does nothing. The position
must be between 0 and the length of the component's text or else
an exception is thrown.wait
methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized
statement
that synchronizes on the object.
Class,
by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait
methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify
method for a
description of the ways in which a thread can become the owner of
a monitor.
paint
directly,
but should instead use the repaint
method to
schedule the component for redrawing.
This method actually delegates the work of painting to three
protected methods: paintComponent
,
paintBorder
,
and paintChildren
. They're called in the order
listed to ensure that children appear on top of component itself.
Generally speaking, the component and its children should not
paint in the insets area allocated to the border. Subclasses can
just override this method, as always. A subclass that just
wants to specialize the UI (look and feel) delegate's
paint
method should just override
paintComponent
.
The origin of the graphics context, its
(0
, 0
) coordinate point, is the
top-left corner of this component. The clipping region of the
graphics context is the bounding rectangle of this component.
It's rarely necessary to call this method. In most cases it's more efficient to call repaint, which defers the actual painting and can collapse redundant requests into a single paint call. This method is useful if one needs to update the display while the current event is being dispatched.
The image data is downloaded asynchronously in another thread, and an appropriately scaled screen representation of the image is generated.
printComponent
,
printBorder
and printChildren
. It is
not recommended that you override this method, instead override
one of the previously mentioned methods. This method sets the
component's state such that the double buffer will not be used, eg
painting will be done directly on the passed in Graphics
.print
on the component.
The get/putClientProperty
methods provide access to
a small per-instance hashtable. Callers can use get/putClientProperty
to annotate components that were created by another module.
For example, a
layout manager might store per child constraints this way. For example:
componentA.putClientProperty("to the left of", componentB);If value is
null
this method will remove the property.
Changes to client properties are reported with
PropertyChange
events.
The name of the property (for the sake of PropertyChange
events) is key.toString()
.
The clientProperty
dictionary is not intended to
support large
scale extensions to JComponent nor should be it considered an
alternative to subclassing when designing a new component.
getActionMap()
and getInputMap()
for
similiar behavior.getActionMap()
and getInputMap()
for
similiar behavior. For example, to bind the KeyStroke
aKeyStroke
to the Action
anAction
now use:
component.getInputMap().put(aKeyStroke, aCommand); component.getActionMap().put(aCommmand, anAction);The above assumes you want the binding to be applicable for
WHEN_FOCUSED
. To register bindings for other focus
states use the getInputMap
method that takes an integer.
Register a new keyboard action.
anAction
will be invoked if a key event matching
aKeyStroke
occurs and aCondition
is verified.
The KeyStroke
object defines a
particular combination of a keyboard key and one or more modifiers
(alt, shift, ctrl, meta).
The aCommand
will be set in the delivered event if
specified.
The aCondition
can be one of:
- WHEN_FOCUSED
- The action will be invoked only when the keystroke occurs while the component has the focus.
- WHEN_IN_FOCUSED_WINDOW
- The action will be invoked when the keystroke occurs while the component has the focus or if the component is in the window that has the focus. Note that the component need not be an immediate descendent of the window -- it can be anywhere in the window's containment hierarchy. In other words, whenever any component in the window has the focus, the action registered with this component is invoked.
- WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
- The action will be invoked when the keystroke occurs while the component has the focus or if the component is an ancestor of the component that has the focus.
The combination of keystrokes and conditions lets you define high level (semantic) action events for a specified keystroke+modifier combination (using the KeyStroke class) and direct to a parent or child of a component that has the focus, or to the component itself. In other words, in any hierarchical structure of components, an arbitrary key-combination can be immediately directed to the appropriate component in the hierarchy, and cause a specific method to be invoked (usually by way of adapter objects).
If an action has already been registered for the receiving
container, with the same charCode and the same modifiers,
anAction
will replace the action.
removeLayoutComponent
method.index
,
from this container.
This method also notifies the layout manager to remove the
component from this container's layout via the
removeLayoutComponent
method.removeLayoutComponent
method.listener
so that it will no longer receive
AncestorEvents
.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.null
names may not be removed in this way.l
is null
,
no exception is thrown and no action is performed.l
is null
,
no exception is thrown and no action is performed.If listener is null, no exception is thrown and no action is performed.
PropertyChangeListener
from the listener
list for a specific property. This method should be used to remove
PropertyChangeListener
s
that were registered for a specific bound property.
If propertyName
or listener
is null
,
no exception is thrown and no action is taken.
VetoableChangeListener
from the listener list.
This removes a VetoableChangeListener
that was registered
for all properties.
If this component is a lightweight component, this method
causes a call to this component's paint
method as soon as possible. Otherwise, this method causes
a call to this component's update
method as soon
as possible.
Note: For more information on the paint mechanisms utilitized by AWT and Swing, including information on how to write the most efficient painting code, see Painting in AWT and Swing.
If this component is a lightweight component, this method
causes a call to this component's paint
method
as soon as possible. Otherwise, this method causes a call to
this component's update
method as soon as possible.
Note: For more information on the paint mechanisms utilitized by AWT and Swing, including information on how to write the most efficient painting code, see Painting in AWT and Swing.
paint
within tm
milliseconds.
Note: For more information on the paint mechanisms utilitized by AWT and Swing, including information on how to write the most efficient painting code, see Painting in AWT and Swing.
This is the method that is used by the default implementation of the action for inserting content that gets bound to the keymap actions.
This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.
Requests focus on this JComponent
's
FocusTraversalPolicy
's default Component
.
If this JComponent
is a focus cycle root, then its
FocusTraversalPolicy
is used. Otherwise, the
FocusTraversalPolicy
of this JComponent
's
focus-cycle-root ancestor is used.
Component
gets the input focus.
Refer to Component.requestFocus()
for a complete description of
this method.
Note that the use of this method is discouraged because its behavior is platform dependent. Instead we recommend the use of requestFocusInWindow() . If you would like more information on focus, see
Component
gets the input focus.
Refer to Component.requestFocus(boolean)
for a complete description of
this method.
Note that the use of this method is discouraged because its behavior is platform dependent. Instead we recommend the use of requestFocusInWindow(boolean) . If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.
Component
gets the input focus.
Refer to Component.requestFocusInWindow()
for a complete description of
this method.
If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.
InputMaps
and ActionMap
. This has the effect of removing any
local bindings, and allowing the bindings defined in parent
InputMap/ActionMaps
(the UI is usually defined in the second tier) to persist.
Calls invalidate
and then adds this component's
validateRoot
to a list of components that need to be
validated. Validation will occur after all currently pending
events have been dispatched. In other words after this method
is called, the first validateRoot (if any) found when walking
up the containment hierarchy of this component will be validated.
By default, JRootPane
, JScrollPane
,
and JTextField
return true
from isValidateRoot
.
This method will automatically be called on this component
when a property value changes such that size, location, or
internal layout of this component has been affected. This automatic
updating differs from the AWT because programs generally no
longer need to invoke validate
to get the contents of the
GUI to update.
scrollRectToVisible()
message to the
JComponent
's parent. Components that can service
the request, such as JViewport
,
override this method and perform the scrolling.This method sets the start and end positions of the selected text, enforcing the restriction that the start position must be greater than or equal to zero. The end position must be greater than or equal to the start position, and less than or equal to the length of the text component's text.
If the caller supplies values that are inconsistent or out of bounds, the method enforces these constraints silently, and without failure. Specifically, if the start position or end position is greater than the length of the text, it is reset to equal the text length. If the start position is less than zero, it is reset to zero, and if the end position is less than the start position, it is reset to the start position.
This call is provided for backward compatibility.
It is routed to a call to setCaretPosition
followed by a call to moveCaretPosition
.
The preferred way to manage selection is by calling
those methods directly.
TextComponent
.
Does nothing on a null
or empty document.ActionMap
to am
. This does not set
the parent of the am
to be the ActionMap
from the UI (if there was one), it is up to the caller to have done this.autoscrolls
property.
If true
mouse dragged events will be
synthetically generated when the mouse is dragged
outside of the component's bounds and mouse motion
has paused (while the button continues to be held
down). The synthetic events make it appear that the
drag gesture has resumed in the direction established when
the component's boundary was crossed. Components that
support autoscrolling must handle mouseDragged
events by calling scrollRectToVisible
with a
rectangle that contains the mouse event's location. All of
the Swing components that support item selection and are
typically displayed in a JScrollPane
(JTable
, JList
, JTree
,
JTextArea
, and JEditorPane
)
already handle mouse dragged events in this way. To enable
autoscrolling in any other component, add a mouse motion
listener that calls scrollRectToVisible
.
For example, given a JPanel
, myPanel
:
MouseMotionListener doScrollRectToVisible = new MouseMotionAdapter() { public void mouseDragged(MouseEvent e) { Rectangle r = new Rectangle(e.getX(), e.getY(), 1, 1); ((JPanel)e.getSource()).scrollRectToVisible(r); } }; myPanel.addMouseMotionListener(doScrollRectToVisible);The default value of the
autoScrolls
property is false
.Border
object is
responsible for defining the insets for the component
(overriding any insets set directly on the component) and
for optionally rendering any border decorations within the
bounds of those insets. Borders should be used (rather
than insets) for creating both decorative and non-decorative
(such as margins and padding) regions for a swing component.
Compound borders can be used to nest multiple borders within a
single component.
Although technically you can set the border on any object
that inherits from
This is a bound property.JComponent, the look and
feel implementation of many standard Swing components
doesn't work well with user-set borders. In general,
when you want to set a border on a standard Swing
component other than
JPanel
or JLabel
,
we recommend that you put the component in a JPanel
and set the border on the JPanel
.
x
and y
, and the
new size is specified by width
and height
.r
. This component's new
position is specified by r.x
and r.y
,
and its new size is specified by r.width
and
r.height
null
effectively restores the default color.
Setting the color results in a PropertyChange event ("caretColor")
being fired.TextComponent
. Note that the caret tracks change,
so this may move if the underlying text of the component is changed.
If the document is null
, does nothing. The position
must be between 0 and the length of the component's text or else
an exception is thrown.JPopupMenu
for this JComponent
.
The UI is responsible for registering bindings and adding the necessary
listeners such that the JPopupMenu
will be shown at
the appropriate time. When the JPopupMenu
is shown
depends upon the look and feel: some may show it on a mouse event,
some may enable a key binding.
If popup
is null, and getInheritsPopupMenu
returns true, then getComponentPopupMenu
will be delegated
to the parent. This provides for a way to make all child components
inherit the popupmenu of the parent.
This is a bound property.
If the component is a child of some other container, it is
removed from that container before being added to this container.
The important difference between this method and
java.awt.Container.add(Component, int)
is that this method
doesn't call removeNotify
on the component while
removing it from its previous container unless necessary and when
allowed by the underlying native windowing system. This way, if the
component has the keyboard focus, it maintains the focus when
moved to the new position.
This property is guaranteed to apply only to lightweight
non-Container
components.
Note: Not all platforms support changing the z-order of
heavyweight components from one container into another without
the call to removeNotify
. There is no way to detect
whether a platform supports this, so developers shouldn't make
any assumptions.
contains
method for
this component returns true for the current cursor location, and
this Component is visible, displayable, and enabled. Setting the
cursor of a Container
causes that cursor to be displayed
within all of the container's subcomponents, except for those
that have a non-null
cursor.Component
is buffered and one of its ancestor
is also buffered, the ancestor buffer will be used.dragEnabled
property,
which must be true
to enable
automatic drag handling (the first part of drag and drop)
on this component.
The transferHandler
property needs to be set
to a non-null
value for the drag to do
anything. The default value of the dragEnabled
property
is false
.
When automatic drag handling is enabled,
most look and feels begin a drag-and-drop operation
whenever the user presses the mouse button over a selection
and then moves the mouse a few pixels.
Setting this property to true
can therefore have a subtle effect on
how selections behave.
Some look and feels might not support automatic drag and drop;
they will ignore this property. You can work around such
look and feels by modifying the component
to directly call the exportAsDrag
method of a
TransferHandler
.
DropTarget
with this component.
The Component
will receive drops only if it
is enabled.TextComponent
should be editable.
A PropertyChange event ("editable") is fired when the
state is changed.Note: Disabling a component does not disable it's children.
Note: Disabling a lightweight component does not prevent it from receiving MouseEvents.
The alternative way to specify the traversal order of this Container's children is to make this Container a focus traversal policy provider.
If this Container is not a focus cycle root, the policy will be remembered, but will not be used or inherited by this or any other Containers until this Container is made a focus cycle root.
true
will be used to acquire focus traversal policy
instead of closest focus cycle root ancestor.null
to disable it.
A PropertyChange event ("highlighter") is fired
when a new highlighter is installed.This is useful, for example, if running under full-screen mode and better performance is desired, or if page-flipping is used as the buffer strategy.
getComponentPopupMenu
should delegate
to the parent if this component does not have a JPopupMenu
assigned to it.
The default value for this is false, but some JComponent
subclasses that are implemented as a number of JComponent
s
may set this to true.
This is a bound property.
InputMap
to use under the condition
condition
to
map
. A null
value implies you
do not want any bindings to be used, even from the UI. This will
not reinstall the UI InputMap
(if there was one).
condition
has one of the following values:
WHEN_IN_FOCUSED_WINDOW
WHEN_FOCUSED
WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
condition
is WHEN_IN_FOCUSED_WINDOW
and map
is not a ComponentInputMap
, an
IllegalArgumentException
will be thrown.
Similarly, if condition
is not one of the values
listed, an IllegalArgumentException
will be thrown.null
effectively disables
keyboard input.
A PropertyChange event ("keymap") is fired when a new keymap
is installed.x
and y
parameters in the coordinate space of this component's parent.p
. Point
p
is given in the parent's coordinate space.Border
object will use this value to create the proper margin.
However, if a non-default border is set on the text component,
it is that Border
object's responsibility to create the
appropriate margin space (else this property will effectively
be ignored). This causes a redraw of the component.
A PropertyChange event ("margin") is sent to all listeners.getMaximumSize
will always
return this value; the component's UI will not be asked
to compute it. Setting the maximum size to null
restores the default behavior.getMinimumSize
will always
return this value; the component's UI will not be asked
to compute it. Setting the minimum size to null
restores the default behavior.NavigationFilter
. NavigationFilter
is used by DefaultCaret
and the default cursor movement
actions as a way to restrict the cursor movement.
Overrides the default FocusTraversalPolicy
for this
JComponent
's focus traversal cycle by unconditionally
setting the specified Component
as the next
Component
in the cycle, and this JComponent
as the specified Component
's previous
Component
in the cycle.
The default value of this property is false for JComponent
.
However, the default value for this property on most standard
JComponent
subclasses (such as JButton
and
JTree
) is look-and-feel dependent.
preferredSize
is null
, the UI will
be asked for the preferred size.JComponent
should get focus. This is only a hint, and it is up to consumers that
are requesting focus to honor this property. This is typically honored
for mouse operations, but not keyboard operations. For example, look
and feels could verify this property is true before requesting focus
during a mouse operation. This would often times be used if you did
not want a mouse press on a JComponent
to steal focus,
but did want the JComponent
to be traversable via the
keyboard. If you do not want this JComponent
focusable at
all, use the setFocusable
method instead.
Please see How to Use the Focus Subsystem, a section in The Java Tutorial, for more information.
null
is the same as
Color.black
. Setting the color results in a
PropertyChange event ("selectedTextColor") being fired.null
is the same as setting
Color.white
. Setting the color results in a
PropertyChange event ("selectionColor").
This is available for backward compatibility to code
that called this method on java.awt.TextComponent
.
This is implemented to forward to the Caret
implementation which is where the actual selection is maintained.
This is available for backward compatibility to code
that called this method on java.awt.TextComponent
.
This is implemented to forward to the Caret
implementation which is where the actual selection is maintained.
d.width
and height d.height
.width
and height height
.TextComponent
to the specified text. If the text is null
or empty, has the effect of simply deleting the old text.
When text has been inserted, the resulting caret location
is determined by the implementation of the caret class.
This method is thread safe, although most Swing methods
are not. Please see
Threads
and Swing for more information.
Note that text is not a bound property, so no PropertyChangeEvent
is fired when it changes. To listen for changes to the text,
use DocumentListener
.
See How to Use Tool Tips in The Java Tutorial for further documentation.
transferHandler
property,
which is null
if the component does
not support data transfer operations.
If newHandler
is not null
,
and the system property
suppressSwingDropSupport
is not true, this will
install a DropTarget
on the JComponent
.
The default for the system property is false, so that a
DropTarget
will be added.
Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.
Component.setVisible
.ActionMap/InputMap
, or place a dummy binding the
InputMap
. Removing the binding from the
InputMap
allows bindings in parent InputMap
s
to be active, whereas putting a dummy binding in the
InputMap
effectively disables
the binding from ever happening.
Unregisters a keyboard action.
This will remove the binding from the ActionMap
(if it exists) as well as the InputMap
s.
paint
. Doesn't clear the background but see
ComponentUI.update
, which is called by
paintComponent
.getUIClassID()
. The type of
the UI is TextUI
. invalidate
is called after setting the UI.
The validate
method is used to cause a container
to lay out its subcomponents again. It should be invoked when
this container's subcomponents are modified (added to or
removed from the container, or layout-related information
changed) after the container has been displayed.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify
method or the
notifyAll
method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) { while (<condition does not hold>) obj.wait(); ... // Perform action appropriate to condition }This method should only be called by a thread that is the owner of this object's monitor. See the
notify
method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) { while (<condition does not hold>) obj.wait(timeout); ... // Perform action appropriate to condition }(For more information on this topic, see Section 3.2.3 in Doug Lea's "Concurrent Programming in Java (Second Edition)" (Addison-Wesley, 2000), or Item 50 in Joshua Bloch's "Effective Java Programming Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify
method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait
method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify
method
or the notifyAll
method.
timeout
milliseconds plus nanos
nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) { while (<condition does not hold>) obj.wait(timeout, nanos); ... // Perform action appropriate to condition }This method should only be called by a thread that is the owner of this object's monitor. See the
notify
method for a
description of the ways in which a thread can become the owner of
a monitor.