org.jdesktop.jxlayer
Class JXLayer<V extends javax.swing.JComponent>

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              org.jdesktop.jxlayer.JXLayer<V>

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.beans.PropertyChangeListener, java.io.Serializable, java.util.EventListener, javax.swing.Scrollable, LayerItemListener

public final class JXLayer<V extends javax.swing.JComponent>
extends javax.swing.JComponent
implements javax.swing.Scrollable, LayerItemListener, java.beans.PropertyChangeListener

The universal decorator for Swing components with which you can implement various advanced painting effects as well as receive notification of all MouseEvents, KeyEvents and FocusEvents which generated within its borders.

JXLayer delegates its painting and input events handling to its LayerUI object which performs the actual decoration.

The custom painting and events notification automatically work for JXLayer itself and all its subcomponents. This powerful combination makes it possible to enrich existing components with new advanced functionality such as temporary locking of a hierarchy, data tips for compound components, enhanced mouse scrolling etc...

JXLayer is a great solution if you just need to do custom painting over compound component or catch input events of its subcomponents.

         // create a component to be decorated with the layer
        JPanel panel = new JPanel();
        panel.add(new JButton("JButton"));
 

        // This custom layerUI will fill the layer with translucent green
        // and print out all mouseMotion events generated within its borders
        AbstractLayerUI<JPanel> layerUI = new AbstractLayerUI<JPanel>() {
 

            protected void paintLayer(Graphics2D g2, JXLayer<JPanel> l) {
                // this paints the layer as is
                super.paintLayer(g2, l);
                // fill it with the translucent green
                g2.setColor(new Color(0, 128, 0, 128));
                g2.fillRect(0, 0, l.getWidth(), l.getHeight());
            }
 

            // overridden method which catches MouseMotion events
            protected void processMouseMotionEvent(MouseEvent e) {
                System.out.println("MouseMotionEvent detected: "
                        + e.getX() + " " + e.getY());
            }
        };
 

        // create the layer for the panel using our custom layerUI
        JXLayer<JPanel> layer = new JXLayer<JPanel>(panel, layerUI);
 

        // work with the layer as with any other Swing component
        frame.add(layer);
 

Note: When a LayerUI instance is disabled or not set, its JXLayers temporary lose all their decorations. Note: JXLayer is very friendly to your application, it uses only public Swing API and doesn't rely on any global settings like custom RepaintManager or AWTEventListener. It neither change the opaque state of its subcomponents nor use the glassPane of its parent frame.

JXLayer can be used under restricted environment (e.g. unsigned applets)

See Also:

setUI(LayerUI), LayerUI, AbstractLayerUI, Serialized Form

Nested Class Summary

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

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

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

Constructor Summary

JXLayer()
Creates a new JXLayer object with empty view component and empty LayerUI.

JXLayer(V view)
Creates a new JXLayer object with empty LayerUI.

JXLayer(V view, LayerUI<V> ui)
Creates a new JXLayer object with provided view component and LayerUI object.

Method Summary

protected void	addImpl(java.awt.Component comp, java.lang.Object constraints, int index) JXLayer can have only two direct children: the view component and the glassPane, so this method throws UnsupportedOperationException.
boolean	contains(int x, int y) Delegates its functionality to the ComponentUI.contains(JComponent, int, int) method, if LayerUI is set and enabled.
javax.swing.JComponent	getGlassPane() Returns the glassPane component of this JXLayer.
java.awt.im.InputContext	getInputContext() Returns the proxy input context which is used to catch all input events and focus events from the subcomponents of this JXLayer.
java.awt.Dimension	getPreferredScrollableViewportSize() Returns the preferred size of the viewport for a view component.
int	getScrollableBlockIncrement(java.awt.Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.
boolean	getScrollableTracksViewportHeight() Returns false 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 viewports height.
boolean	getScrollableTracksViewportWidth() Returns false 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 viewports width.
int	getScrollableUnitIncrement(java.awt.Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.
LayerUI<V>	getUI() Returns the LayerUI for this JXLayer.
V	getView() Returns the view component for this JXLayer.
boolean	isOptimizedDrawingEnabled() To enable the correct painting of the glassPane and view component, the JXLayer overrides the default implementation of this method to return false when the glassPane is visible.
boolean	isProxyInputContextEnabled() Returns true is the proxy InputContext is enabled for this JXLayer.
void	layerItemChanged(LayerItemChangeEvent e) This method is public as an implementation side effect.
void	paint(java.awt.Graphics g) Delegates all painting to the LayerUI object.
void	propertyChange(java.beans.PropertyChangeEvent evt)
void	remove(java.awt.Component comp) Removes the JXLayer's view component.
void	removeAll() Removes the JXLayer's view component.
void	setGlassPane(javax.swing.JComponent glassPane) Sets the glassPane component of this JXLayer.
void	setProxyInputContextEnabled(boolean isEnabled) Sets if the the proxy InputContext is enabled for this JXLayer If the proxy InputContext is enabled, the JXLayer will notify its LayerUI about keyboard, mouse & focus events that are generated for this JXLayer or any of its subcomponent A LayerUI subclass may implement a different way of catching events, via ordinary listeners or global AWTEventListener The default value for this property is true For more informaiton please see JXLayer 3.0 - Event handling
void	setUI(LayerUI<V> ui) Sets the LayerUI which will perform painting and receive input events for this JXLayer.
void	setView(V view) Sets the view component (the component to be decorated) for this JXLayer.
void	updateUI() Delegates its functionality to the LayerUI.updateUI(JXLayer) method, if LayerUI is set and enabled.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, 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, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, 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, setBorder, 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 inherited from class java.awt.Container

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

Methods inherited from 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, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JXLayer

public JXLayer()

Creates a new JXLayer object with empty view component and empty LayerUI.

See Also:

setView(V), setUI(org.jdesktop.jxlayer.plaf.LayerUI)

JXLayer

public JXLayer(V view)

Creates a new JXLayer object with empty LayerUI.

Parameters:

view - the component to be decorated with this JXLayer

See Also:

setUI(org.jdesktop.jxlayer.plaf.LayerUI)

JXLayer

public JXLayer(V view,
               LayerUI<V> ui)

Creates a new JXLayer object with provided view component and LayerUI object.

Parameters:

view - the component to be decorated

ui - the LayerUI deleagate to be used by this JXLayer

Method Detail

getView

public V getView()

Returns the view component for this JXLayer.
This is a bound property.

Returns:

the view component for this JXLayer

setView

public void setView(V view)

Sets the view component (the component to be decorated) for this JXLayer.
This is a bound property.

Parameters:

view - the view component for this JXLayer

setUI

public void setUI(LayerUI<V> ui)

Sets the LayerUI which will perform painting and receive input events for this JXLayer.

Parameters:

ui - the LayerUI for this JXLayer

getUI

public LayerUI<V> getUI()

Returns the LayerUI for this JXLayer.

Returns:

the LayerUI for this JXLayer

getGlassPane

public javax.swing.JComponent getGlassPane()

Returns the glassPane component of this JXLayer.
This is a bound property.

Returns:

the glassPane component of this JXLayer

setGlassPane

public void setGlassPane(javax.swing.JComponent glassPane)

Sets the glassPane component of this JXLayer.
This is a bound property.

Parameters:

glassPane - the glassPane component of this JXLayer

addImpl

protected void addImpl(java.awt.Component comp,
                       java.lang.Object constraints,
                       int index)

JXLayer can have only two direct children: the view component and the glassPane, so this method throws UnsupportedOperationException.

Overrides:

addImpl in class java.awt.Container

See Also:

setView(V), setGlassPane(javax.swing.JComponent)

remove

public void remove(java.awt.Component comp)

Removes the JXLayer's view component.

Overrides:

remove in class java.awt.Container

Parameters:

comp - the component to be removed

removeAll

public void removeAll()

Removes the JXLayer's view component.

Overrides:

removeAll in class java.awt.Container

paint

public void paint(java.awt.Graphics g)

Delegates all painting to the LayerUI object.

If no view component or LayerUI object is provided, LayerItem.isEnabled() returns false, any of JXLayer's size is less than 1 or g is not instance of Graphics2D then the super implementation of paint method is called.

Overrides:

paint in class javax.swing.JComponent

Parameters:

g - the Graphics to render to

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()

To enable the correct painting of the glassPane and view component, the JXLayer overrides the default implementation of this method to return false when the glassPane is visible.

Overrides:

isOptimizedDrawingEnabled in class javax.swing.JComponent

Returns:

false

layerItemChanged

public void layerItemChanged(LayerItemChangeEvent e)

This method is public as an implementation side effect. JXLayer can be registered as a LayerItemListener and usually receives the LayerItemChangeEvents from its LayerUI.

Specified by:

layerItemChanged in interface LayerItemListener

Parameters:

e - the LayerItemChangeEvent

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent evt)

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

updateUI

public void updateUI()

Delegates its functionality to the LayerUI.updateUI(JXLayer) method, if LayerUI is set and enabled.

Overrides:

updateUI in class javax.swing.JComponent

contains

public boolean contains(int x,
                        int y)

Delegates its functionality to the ComponentUI.contains(JComponent, int, int) method, if LayerUI is set and enabled.

Overrides:

contains in class javax.swing.JComponent

getPreferredScrollableViewportSize

public java.awt.Dimension getPreferredScrollableViewportSize()

Returns the preferred size of the viewport for a view component.

If the ui delegate of this layer is not null, this method delegates its implementation to the LayerUI.getPreferredScrollableViewportSize(JXLayer)

Specified by:

getPreferredScrollableViewportSize in interface javax.swing.Scrollable

Returns:

the preferred size of the viewport for a view component

See Also:

Scrollable, LayerUI.getPreferredScrollableViewportSize(JXLayer)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(java.awt.Rectangle visibleRect,
                                       int orientation,
                                       int direction)

Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

If the ui delegate of this layer is not null, this method delegates its implementation to the LayerUI.getScrollableBlockIncrement(JXLayer,Rectangle,int,int)

Specified by:

getScrollableBlockIncrement in interface javax.swing.Scrollable

Returns:

the "block" increment for scrolling in the specified direction

See Also:

Scrollable, LayerUI.getScrollableBlockIncrement(JXLayer, Rectangle, int, int)

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()

Returns false 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 viewports height.

If the ui delegate of this layer is not null, this method delegates its implementation to the LayerUI.getScrollableTracksViewportHeight(JXLayer)

Specified by:

getScrollableTracksViewportHeight in interface javax.swing.Scrollable

Returns:

whether the layer should track the height of the viewport

See Also:

Scrollable, LayerUI.getScrollableTracksViewportHeight(JXLayer)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

Returns false 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 viewports width.

If the ui delegate of this layer is not null, this method delegates its implementation to the LayerUI.getScrollableTracksViewportWidth(JXLayer)

Specified by:

getScrollableTracksViewportWidth in interface javax.swing.Scrollable

Returns:

whether the layer should track the width of the viewport

See Also:

Scrollable, LayerUI.getScrollableTracksViewportWidth(JXLayer)

getScrollableUnitIncrement

public int getScrollableUnitIncrement(java.awt.Rectangle visibleRect,
                                      int orientation,
                                      int direction)

Components that display logical rows or columns should compute the scroll increment that will 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 ui delegate of this layer is not null, this method delegates its implementation to the LayerUI.getScrollableUnitIncrement(JXLayer,Rectangle,int,int)

Specified by:

getScrollableUnitIncrement in interface javax.swing.Scrollable

Returns:

The "unit" increment for scrolling in the specified direction. This value should always be positive.

See Also:

Scrollable, LayerUI.getScrollableUnitIncrement(JXLayer, Rectangle, int, int)

isProxyInputContextEnabled

public boolean isProxyInputContextEnabled()

Returns true is the proxy InputContext is enabled for this JXLayer.

When the proxy InputContext is enabled, the JXLayer will notify its LayerUI about keyboard, mouse & focus events that are generated for this JXLayer or any of its subcomponent

The default value for this property is true

For more informaiton please see JXLayer 3.0 - Event handling

Returns:

true is the proxy InputContext is enabled for this JXLayer

See Also:

LayerUI.eventDispatched(AWTEvent, JXLayer)

setProxyInputContextEnabled

public void setProxyInputContextEnabled(boolean isEnabled)

Sets if the the proxy InputContext is enabled for this JXLayer

If the proxy InputContext is enabled, the JXLayer will notify its LayerUI about keyboard, mouse & focus events that are generated for this JXLayer or any of its subcomponent

A LayerUI subclass may implement a different way of catching events, via ordinary listeners or global AWTEventListener

The default value for this property is true

For more informaiton please see JXLayer 3.0 - Event handling

Parameters:

isEnabled - true if the proxy InputContext is enabled, otherwise false

See Also:

LayerUI.eventDispatched(AWTEvent, JXLayer)

getInputContext

public java.awt.im.InputContext getInputContext()

Returns the proxy input context which is used to catch all input events and focus events from the subcomponents of this JXLayer.

When input event is happened and LayerUI is set and enabled then this proxy input context notifies the LayerUI.eventDispatched(AWTEvent, JXLayer) method and then calls the super implementation.

Overrides:

getInputContext in class java.awt.Component

Returns:

the private proxy InputContext instance