DMDirc-Plugins/src/com/dmdirc/addons/ui_swing/components/LockedLayer.java

/**
 * Copyright (c) 2006-2009, Alexander Potochkin All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted
 * provided that the following conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright notice, this list of conditions
 * and the following disclaimer. * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the documentation and/or other
 * materials provided with the distribution. * Neither the name of the JXLayer project nor the names
 * of its contributors may be used to endorse or promote products derived from this software without
 * specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.dmdirc.addons.ui_swing.components;

import java.awt.Component;
import java.awt.Cursor;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.KeyboardFocusManager;
import java.awt.event.FocusEvent;
import java.awt.event.FocusListener;

import javax.swing.JComponent;
import javax.swing.SwingUtilities;

import org.jdesktop.jxlayer.JXLayer;
import org.jdesktop.jxlayer.plaf.AbstractBufferedLayerUI;
import org.jdesktop.jxlayer.plaf.effect.LayerEffect;

/**
 * An implementation of the {@code BufferedLayerUI} which provides a lightweight disabling for the
 * content of its {@link JXLayer}. This allows temporarily blocking a part of the interface with all
 * it subcomponents, it is also useful when some kind of action is in progress, e.g. reading data
 * from a database.
 * <p>
 * When {@code true} is passed to the {@link #setLocked(boolean)}, the {@code JXLayer} of this
 * {@code LockableLayerUI} becomes "locked". It sets the "wait" mouse cursor and stops reacting on
 * mouse, keyboard and focus events.
 * <p>
 * If {@code setLocked(boolean)} is called with {@code false} parameter after that, the
 * {@code JXLayer}, together with all its subcomponents, gets back to live.
 * <p>
 * Subclasses usually override {@link #paintLayer(Graphics2D,JXLayer)} or
 * {@link #getLayerEffects(JXLayer)} to implement some visual effects when {@code JXLayer} is in
 * locked state.
 * <p>
 * Here is an example of using {@code LockableLayerUI}:
 * <pre>
 * JComponent myComponent = getMyComponent(); // just any component
 *
 * LockableLayerUI lockableUI = new LockableLayerUI();
 * JXLayer&lt;JComponent&gt; layer = new JXLayer&lt;JComponent&gt;(myComponent,
 * lockableUI);
 *
 * // locking the layer, use lockableUI.setLocked(false) to unlock
 * lockableUI.setLocked(true);
 *
 * // add the layer to a frame or a panel, like any other component
 * frame.add(layer);
 * </pre>
 *
 * @param <T> Generic type
 */
public class LockedLayer<T extends JComponent> extends AbstractBufferedLayerUI<T> {

    /**
     * A version number for this class. It should be changed whenever the class structure is changed
     * (or anything else that would prevent serialized objects being unserialized with the new
     * class).
     */
    private static final long serialVersionUID = 1;
    /** Are we locked. */
    private boolean locked;
    /** Most recent focus owner? */
    private Component recentFocusOwner;
    /** Cursor to show when locked. */
    private Cursor lockedCursor = Cursor.getPredefinedCursor(
            Cursor.DEFAULT_CURSOR);
    /** Effect to apply when locked. */
    private LayerEffect[] lockedEffects = new LayerEffect[0];
    /** Focus listener. */
    private final transient FocusListener focusListener = new FocusListener() {
        /** {@inheritDoc} */
        @Override
        public void focusGained(final FocusEvent e) {
            // we don't want extra repaintings
            // when focus comes from another window
            if (e.getOppositeComponent() != null) {
                setDirty(true);
            }
        }

        /** {@inheritDoc} */
        @Override
        public void focusLost(final FocusEvent e) {
            //Ignore
        }
    };

    /**
     * Creates a new instance of LockableUI.
     */
    public LockedLayer() {
        this((LayerEffect[]) null);
    }

    /**
     * Creates a new instance of LockableUI, passed lockedEffects will be used for when this UI in
     * the locked state.
     *
     * @param effects effects to be used when this UI is locked
     *
     * @see #setLocked(boolean)
     * @see #setLockedEffects(LayerEffect...)
     */
    public LockedLayer(final LayerEffect... effects) {
        super();

        setLockedEffects(effects);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void installUI(final JComponent c) {
        super.installUI(c);
        // we need to repaint the layer when it receives the focus
        // otherwise the focused component will have it on the buffer image
        c.addFocusListener(focusListener);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void uninstallUI(final JComponent c) {
        super.uninstallUI(c);
        c.removeFocusListener(focusListener);
    }

    /**
     * Returns {@code true} if this {@code LockableLayerUI} is in locked state and all
     * {@link JXLayer}'s mouse, keyboard and focus events are temporarily blocked, otherwise returns
     * {@code false}.
     *
     * @return {@code true} if this {@code LockableLayerUI} is in locked state and all
     *         {@code JXLayer}'s mouse, keyboard and focus events are temporarily blocked, otherwise
     *         returns {@code false}
     */
    public boolean isLocked() {
        return locked;
    }

    /**
     * If {@code isLocked} is {@code true} then all mouse, keyboard and focus events from the
     * {@link JXLayer} of this {@code LockableLayerUI} will be temporarily blocked.
     *
     * @param isLocked if {@code true} then all mouse, keyboard and focus events from the
     *                 {@code JXLayer} of this {@code LockableLayerUI} will be temporarily blocked
     */
    public void setLocked(final boolean isLocked) {
        if (isLocked != isLocked()) {
            if (getLayer() != null) {
                final KeyboardFocusManager kfm = KeyboardFocusManager.
                        getCurrentKeyboardFocusManager();
                final Component focusOwner = kfm.getPermanentFocusOwner();
                final boolean focusInLayer = focusOwner != null
                        && SwingUtilities.isDescendingFrom(focusOwner,
                        getLayer());
                if (isLocked) {
                    if (focusInLayer && kfm.getFocusedWindow()
                            == SwingUtilities.getWindowAncestor(getLayer())) {
                        recentFocusOwner = focusOwner;
                        // setDirty() will be called from the layer's
                        //focusListener when focus already left layer's view
                        //and hiding it in the paintLayer() won't mess the
                        //focus up getLayer().requestFocusInWindow();
                    } else {
                        setDirty(true);
                    }
                    // the mouse cursor is set to the glassPane
                    getLayer().getGlassPane().setCursor(getLockedCursor());
                } else {
                    // show the view again
                    getLayer().getView().setVisible(true);
                    // restore the focus if it is still in the layer
                    if (focusInLayer && recentFocusOwner != null) {
                        recentFocusOwner.requestFocusInWindow();
                    }
                    recentFocusOwner = null;
                    getLayer().getGlassPane().setCursor(null);
                }
            }
            this.locked = isLocked;
            firePropertyChange("locked", !isLocked, isLocked);
        }
    }

    // If it is locked, the buffer image will be updated
    // only if the layer changes its size or setDirty(true) was called
    /** {@inheritDoc} */
    @Override
    protected boolean isIncrementalUpdate(
            final JXLayer<? extends T> l) {
        return !isLocked();
    }

    /** {@inheritDoc} */
    @Override
    protected void paintLayer(final Graphics2D g2,
            final JXLayer<? extends T> l) {
        if (isLocked()) {
            // Note: this code will be called only if layer changes its size,
            // or setDirty(true) was called,
            // otherwise the previously created buffer is used
            l.getView().setVisible(true);
            l.paint(g2);
            // hide the layer's view component
            // this is the only way to disable key shortcuts
            // installed on its subcomponents
            l.getView().setVisible(false);
        }
    }

    /** {@inheritDoc} */
    @Override
    public void paint(final Graphics g, final JComponent c) {
        super.paint(g, c);
        // if it is not locked, we need to paint the layer as is
        // otherwise we also need to paint it again;
        // if there are any glassPane's children
        // they should be shown unfiltered
        c.paint(g);
    }

    /**
     * Returns the mouse cursor to be used by this {@code LockableLayerUI} when it locked state.
     *
     * @return the mouse cursor to be used by this {@code LockableLayerUI} when it locked state
     *
     * @see #getLockedCursor()
     * @see #setLocked(boolean)
     */
    public Cursor getLockedCursor() {
        return lockedCursor;
    }

    /**
     * Sets the mouse cursor to be used by this {@code LockableLayerUI} when it locked state.
     *
     * @param newCursor the mouse cursor to be used by this {@code LockableLayerUI} when it locked
     *                  state
     */
    public void setLockedCursor(final Cursor newCursor) {
        final Cursor oldCursor = getLockedCursor();
        this.lockedCursor = newCursor;
        firePropertyChange("lockedCursor", oldCursor, newCursor);
        if (isLocked()) {
            getLayer().getGlassPane().setCursor(newCursor);
        }
    }

    /**
     * Returns the effects to be used when this UI is locked.
     *
     * @return the effects to be used when this UI is locked
     *
     * @see #setLocked(boolean)
     */
    public LayerEffect[] getLockedEffects() {
        final LayerEffect[] result = new LayerEffect[lockedEffects.length];
        System.arraycopy(lockedEffects, 0, result, 0, result.length);
        return result;
    }

    /**
     * This method returns the array of {@code LayerEffect}s set using
     * {@link #setLockedEffects(LayerEffect...)}
     * <p>
     * If a {@code LockableUI} provides more extensive API to support different {@code Effect}s
     * depending on its state or on the state of the passed {@code JXLayer}, this method should be
     * overridden.
     *
     * @param l Layer to get effects from
     *
     * @return Locked layer effect
     *
     * @see #setLockedEffects (LayerEffect...)
     * @see #getLockedEffects()
     */
    protected LayerEffect[] getLockedEffects(
            final JXLayer<? extends JComponent> l) {
        return getLockedEffects();
    }

    /**
     * Sets the effects to be used when this UI is locked.
     *
     * @param effects the effects to be used when this UI is locked
     *
     * @see #setLocked(boolean)
     */
    public void setLockedEffects(final LayerEffect... effects) {
        final LayerEffect[] layerEffect;
        final LayerEffect[] oldEffects = getLockedEffects();
        if (effects == null) {
            layerEffect = new LayerEffect[0];
        } else {
            layerEffect = effects;
        }
        for (LayerEffect effect : getLockedEffects()) {
            effect.removePropertyChangeListener(this);
        }
        this.lockedEffects = new LayerEffect[layerEffect.length];
        System.arraycopy(layerEffect, 0, this.lockedEffects, 0,
                layerEffect.length);
        for (LayerEffect lockedEffect : layerEffect) {
            lockedEffect.addPropertyChangeListener(this);
        }
        firePropertyChange("lockedEffects", oldEffects, layerEffect);
    }

    /**
     * {@inheritDoc}
     *
     * @param l Layer
     *
     * @return Layer effects
     */
    @Override
    protected LayerEffect[] getLayerEffects(final JXLayer<? extends T> l) {
        if (isLocked()) {
            return getLockedEffects(l);
        } else {
            return super.getLayerEffects(l);
        }
    }

}