- Type Parameters:
V
- the type ofJLayer
's view component
- All Implemented Interfaces:
ImageObserver
,MenuContainer
,PropertyChangeListener
,Serializable
,EventListener
,Accessible
,Scrollable
JLayer
is a universal decorator for Swing components
which enables you to implement various advanced painting effects as well as
receive notifications of all AWTEvent
s generated within its borders.
JLayer
delegates the handling of painting and input events to a
LayerUI
object, which performs the actual decoration.
The custom painting implemented in the LayerUI
and events notification
work for the JLayer itself and all its subcomponents.
This combination enables you to enrich existing components
by adding new advanced functionality such as temporary locking of a hierarchy,
data tips for compound components, enhanced mouse scrolling etc and so on.
JLayer
is a good solution if you only need to do custom painting
over compound component or catch input events from its subcomponents.
import javax.swing.*; import javax.swing.plaf.LayerUI; import java.awt.*; public class JLayerSample { private static JLayer<JComponent> createLayer() { // This custom layerUI will fill the layer with translucent green // and print out all mouseMotion events generated within its borders LayerUI<JComponent> layerUI = new LayerUI<JComponent>() { public void paint(Graphics g, JComponent c) { // paint the layer as is super.paint(g, c); // fill it with the translucent green g.setColor(new Color(0, 128, 0, 128)); g.fillRect(0, 0, c.getWidth(), c.getHeight()); } public void installUI(JComponent c) { super.installUI(c); // enable mouse motion events for the layer's subcomponents ((JLayer) c).setLayerEventMask(AWTEvent.MOUSE_MOTION_EVENT_MASK); } public void uninstallUI(JComponent c) { super.uninstallUI(c); // reset the layer event mask ((JLayer) c).setLayerEventMask(0); } // overridden method which catches MouseMotion events public void eventDispatched(AWTEvent e, JLayer<? extends JComponent> l) { System.out.println("AWTEvent detected: " + e); } }; // create a component to be decorated with the layer JPanel panel = new JPanel(); panel.add(new JButton("JButton")); // create the layer for the panel using our custom layerUI return new JLayer<JComponent>(panel, layerUI); } private static void createAndShowGUI() { final JFrame frame = new JFrame(); frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE); // work with the layer as with any other Swing component frame.add(createLayer()); frame.setSize(200, 200); frame.setLocationRelativeTo(null); frame.setVisible(true); } public static void main(String[] args) throws Exception { SwingUtilities.invokeAndWait(new Runnable() { public void run() { createAndShowGUI(); } }); } }Note:
JLayer
doesn't support the following methods:
Container.add(java.awt.Component)
Container.add(String, java.awt.Component)
Container.add(java.awt.Component, int)
Container.add(java.awt.Component, Object)
Container.add(java.awt.Component, Object, int)
UnsupportedOperationException
to be thrown,
to add a component to JLayer
use setView(Component)
or setGlassPane(JPanel)
.- Since:
- 1.7
- See Also:
-
Nested Class Summary
Nested classes/interfaces declared in class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces declared in class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces declared in class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
-
Field Summary
Fields declared in class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields declared in class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields declared in interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected void
This method is not supported byJLayer
and always throwsUnsupportedOperationException
Called by the constructor methods to create a defaultglassPane
.void
doLayout()
Delegates its functionality to theLayerUI.doLayout(JLayer)
method, ifLayerUI
is set.Gets the AccessibleContext associated with thisJLayer
.Delegates its functionality to thegetView().getBorder()
method, if the view component is an instance ofjavax.swing.JComponent
, otherwise returnsnull
.Returns theJLayer
's glassPane component ornull
.long
Returns the bitmap of event mask to receive by thisJLayer
and itsLayerUI
.Returns the preferred size of the viewport for a view component.int
getScrollableBlockIncrement
(Rectangle visibleRect, int orientation, int direction) Returns a scroll increment, which is required for components that display logical rows or columns in order to completely expose one block of rows or columns, depending on the value of orientation.boolean
Returnsfalse
to indicate that the height of the viewport does not determine the height of the layer, unless the preferred height of the layer is smaller than the height of the viewport.boolean
Returnsfalse
to indicate that the width of the viewport does not determine the width of the layer, unless the preferred width of the layer is smaller than the width of the viewport.int
getScrollableUnitIncrement
(Rectangle visibleRect, int orientation, int direction) Returns a scroll increment, which is required for components that display logical rows or columns in order to completely expose one new row or column, depending on the value of orientation.getUI()
Returns theLayerUI
for thisJLayer
.getView()
Returns theJLayer
's view component ornull
.boolean
imageUpdate
(Image img, int infoflags, int x, int y, int w, int h) Delegates its functionality to theLayerUI.imageUpdate(java.awt.Image, int, int, int, int, int, JLayer)
method, if theLayerUI
is set.boolean
TheJLayer
overrides the default implementation of this method (inJComponent
) to returnfalse
.protected boolean
Always returnstrue
to cause painting to originate fromJLayer
, or one of its ancestors.void
Delegates all painting to theLayerUI
object.protected void
This method is empty, because all painting is done bypaint(Graphics)
andComponentUI.update(Graphics, JComponent)
methodsvoid
paintImmediately
(int x, int y, int w, int h) Delegates its functionality to theLayerUI.paintImmediately(int, int, int, int, JLayer)
method, ifLayerUI
is set.void
This method gets called when a bound property is changed.void
Delegates its functionality to thegetView().setBorder(Border)
method, if the view component is an instance ofjavax.swing.JComponent
, otherwise this method is a no-op.void
setGlassPane
(JPanel glassPane) Sets theJLayer
's glassPane component, which can benull
.void
setLayerEventMask
(long layerEventMask) Enables the events from JLayer and all its descendants defined by the specified event mask parameter to be delivered to theLayerUI.eventDispatched(AWTEvent, JLayer)
method.void
setLayout
(LayoutManager mgr) Sets the layout manager for this container.void
Sets theLayerUI
which will perform painting and receive input events for thisJLayer
.void
Sets theJLayer
's view component, which can benull
.void
updateUI()
Delegates its functionality to theLayerUI.updateUI(JLayer)
method, ifLayerUI
is set.Methods declared in class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods declared in class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, 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, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusDownCycle, validate, validateTree
Methods declared in class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, 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, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Constructor Details
-
JLayer
public JLayer()- See Also:
-
JLayer
Creates a newJLayer
object with defaultLayerUI
.- Parameters:
view
- the component to be decorated by thisJLayer
- See Also:
-
JLayer
Creates a newJLayer
object with the specified view component andLayerUI
object.- Parameters:
view
- the component to be decoratedui
- theLayerUI
delegate to be used by thisJLayer
-
-
Method Details
-
getView
Returns theJLayer
's view component ornull
.
This is a bound property.- Returns:
- the
JLayer
's view component ornull
if none exists - See Also:
-
setView
Sets theJLayer
's view component, which can benull
.
This is a bound property.- Parameters:
view
- the view component for thisJLayer
- See Also:
-
setUI
Sets theLayerUI
which will perform painting and receive input events for thisJLayer
.- Parameters:
ui
- theLayerUI
for thisJLayer
-
getUI
Returns theLayerUI
for thisJLayer
.- Overrides:
getUI
in classJComponent
- Returns:
- the
LayerUI
for thisJLayer
-
getGlassPane
Returns theJLayer
's glassPane component ornull
.
This is a bound property.- Returns:
- the
JLayer
's glassPane component ornull
if none exists - See Also:
-
setGlassPane
Sets theJLayer
's glassPane component, which can benull
.
This is a bound property.- Parameters:
glassPane
- the glassPane component of thisJLayer
- See Also:
-
createGlassPane
Called by the constructor methods to create a defaultglassPane
. By default this method creates a new JPanel with visibility set to true and opacity set to false.- Returns:
- the default
glassPane
-
setLayout
Sets the layout manager for this container. This method is overridden to prevent the layout manager from being set.Note: If
mgr
is non-null
, this method will throw an exception as layout managers are not supported on aJLayer
.- Overrides:
setLayout
in classContainer
- Parameters:
mgr
- the specified layout manager- Throws:
IllegalArgumentException
- this method is not supported- See Also:
-
setBorder
Delegates its functionality to thegetView().setBorder(Border)
method, if the view component is an instance ofjavax.swing.JComponent
, otherwise this method is a no-op.- Overrides:
setBorder
in classJComponent
- Parameters:
border
- the border to be rendered for theview
component- See Also:
-
getBorder
Delegates its functionality to thegetView().getBorder()
method, if the view component is an instance ofjavax.swing.JComponent
, otherwise returnsnull
.- Overrides:
getBorder
in classJComponent
- Returns:
- the border object for the
view
component - See Also:
-
addImpl
This method is not supported byJLayer
and always throwsUnsupportedOperationException
- Overrides:
addImpl
in classContainer
- Parameters:
comp
- the component to be addedconstraints
- an object expressing layout constraints for this componentindex
- the position in the container's list at which to insert the component, where-1
means append to the end- Throws:
UnsupportedOperationException
- this method is not supported- See Also:
-
isPaintingOrigin
protected boolean isPaintingOrigin()Always returnstrue
to cause painting to originate fromJLayer
, or one of its ancestors.- Overrides:
isPaintingOrigin
in classJComponent
- Returns:
- true
- See Also:
-
paintImmediately
public void paintImmediately(int x, int y, int w, int h) Delegates its functionality to theLayerUI.paintImmediately(int, int, int, int, JLayer)
method, ifLayerUI
is set.- Overrides:
paintImmediately
in classJComponent
- Parameters:
x
- the x value of the region to be paintedy
- the y value of the region to be paintedw
- the width of the region to be paintedh
- the height of the region to be painted- See Also:
-
imageUpdate
Delegates its functionality to theLayerUI.imageUpdate(java.awt.Image, int, int, int, int, int, JLayer)
method, if theLayerUI
is set.- Specified by:
imageUpdate
in interfaceImageObserver
- Overrides:
imageUpdate
in classComponent
- Parameters:
img
- the image being observedinfoflags
- seeimageUpdate
for more informationx
- the x coordinatey
- the y coordinatew
- the widthh
- the height- Returns:
false
if the infoflags indicate that the image is completely loaded;true
otherwise.- See Also:
-
paint
Delegates all painting to theLayerUI
object.- Overrides:
paint
in classJComponent
- Parameters:
g
- theGraphics
to render to- See Also:
-
paintComponent
This method is empty, because all painting is done bypaint(Graphics)
andComponentUI.update(Graphics, JComponent)
methods- Overrides:
paintComponent
in classJComponent
- Parameters:
g
- theGraphics
object to protect- See Also:
-
isOptimizedDrawingEnabled
public boolean isOptimizedDrawingEnabled()TheJLayer
overrides the default implementation of this method (inJComponent
) to returnfalse
. This ensures that the drawing machinery will call theJLayer
'spaint
implementation rather than messaging theJLayer
's children directly.- Overrides:
isOptimizedDrawingEnabled
in classJComponent
- Returns:
- false
-
propertyChange
This method gets called when a bound property is changed.- Specified by:
propertyChange
in interfacePropertyChangeListener
- Parameters:
evt
- A PropertyChangeEvent object describing the event source and the property that has changed.
-
setLayerEventMask
public void setLayerEventMask(long layerEventMask) Enables the events from JLayer and all its descendants defined by the specified event mask parameter to be delivered to theLayerUI.eventDispatched(AWTEvent, JLayer)
method.Events are delivered provided that
LayerUI
is set for thisJLayer
and theJLayer
is displayable.The following example shows how to correctly use this method in the
LayerUI
implementations:public void installUI(JComponent c) { super.installUI(c); JLayer l = (JLayer) c; // this LayerUI will receive only key and focus events l.setLayerEventMask(AWTEvent.KEY_EVENT_MASK | AWTEvent.FOCUS_EVENT_MASK); } public void uninstallUI(JComponent c) { super.uninstallUI(c); JLayer l = (JLayer) c; // JLayer must be returned to its initial state l.setLayerEventMask(0); }
By defaultJLayer
receives no events and its event mask is0
.- Parameters:
layerEventMask
- the bitmask of event types to receive- See Also:
-
getLayerEventMask
public long getLayerEventMask()Returns the bitmap of event mask to receive by thisJLayer
and itsLayerUI
.It means that
LayerUI.eventDispatched(AWTEvent, JLayer)
method will only receive events that match the event mask.By default
JLayer
receives no events.- Returns:
- the bitmask of event types to receive for this
JLayer
-
updateUI
public void updateUI()Delegates its functionality to theLayerUI.updateUI(JLayer)
method, ifLayerUI
is set.- Overrides:
updateUI
in classJComponent
- See Also:
-
getPreferredScrollableViewportSize
Returns the preferred size of the viewport for a view component.If the view component of this layer implements
Scrollable
, this method delegates its implementation to the view component.- Specified by:
getPreferredScrollableViewportSize
in interfaceScrollable
- Returns:
- the preferred size of the viewport for a view component
- See Also:
-
getScrollableBlockIncrement
Returns a scroll increment, which is required for components that display logical rows or columns in order to completely expose one block of rows or columns, depending on the value of orientation.If the view component of this layer implements
Scrollable
, this method delegates its implementation to the view component.- Specified by:
getScrollableBlockIncrement
in interfaceScrollable
- Parameters:
visibleRect
- The view area visible within the viewportorientation
- Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.direction
- Less than zero to scroll up/left, greater than zero for down/right.- Returns:
- the "block" increment for scrolling in the specified direction
- See Also:
-
getScrollableTracksViewportHeight
public boolean getScrollableTracksViewportHeight()Returnsfalse
to indicate that the height of the viewport does not determine the height of the layer, unless the preferred height of the layer is smaller than the height of the viewport.If the view component of this layer implements
Scrollable
, this method delegates its implementation to the view component.- Specified by:
getScrollableTracksViewportHeight
in interfaceScrollable
- Returns:
- whether the layer should track the height of the viewport
- See Also:
-
getScrollableTracksViewportWidth
public boolean getScrollableTracksViewportWidth()Returnsfalse
to indicate that the width of the viewport does not determine the width of the layer, unless the preferred width of the layer is smaller than the width of the viewport.If the view component of this layer implements
Scrollable
, this method delegates its implementation to the view component.- Specified by:
getScrollableTracksViewportWidth
in interfaceScrollable
- Returns:
- whether the layer should track the width of the viewport
- See Also:
-
getScrollableUnitIncrement
Returns a scroll increment, which is required for components that display logical rows or columns in order to completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.Scrolling containers, like
JScrollPane
, will use this method each time the user requests a unit scroll.If the view component of this layer implements
Scrollable
, this method delegates its implementation to the view component.- Specified by:
getScrollableUnitIncrement
in interfaceScrollable
- Parameters:
visibleRect
- The view area visible within the viewportorientation
- Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.direction
- Less than zero to scroll up/left, greater than zero for down/right.- Returns:
- The "unit" increment for scrolling in the specified direction. This value should always be positive.
- See Also:
-
doLayout
public void doLayout()Delegates its functionality to theLayerUI.doLayout(JLayer)
method, ifLayerUI
is set. -
getAccessibleContext
Gets the AccessibleContext associated with thisJLayer
.- Specified by:
getAccessibleContext
in interfaceAccessible
- Overrides:
getAccessibleContext
in classComponent
- Returns:
- the AccessibleContext associated with this
JLayer
.
-