/**
 *    DisplayIO.java
 *    Copyright (C) 2010 New Zealand Digital Library, http://expeditee.org
 *
 *    This program is free software: you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation, either version 3 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.expeditee.gui;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Stack;
import java.util.function.BooleanSupplier;

import org.expeditee.auth.mail.gui.MailBay;
import org.expeditee.core.Clip;
import org.expeditee.core.Colour;
import org.expeditee.core.Cursor;
import org.expeditee.core.DamageAreas;
import org.expeditee.core.Dimension;
import org.expeditee.core.EnforcedClipStack.EnforcedClipKey;
import org.expeditee.core.Image;
import org.expeditee.core.InOutReference;
import org.expeditee.core.Line;
import org.expeditee.core.Point;
import org.expeditee.core.Stroke;
import org.expeditee.core.bounds.AxisAlignedBoxBounds;
import org.expeditee.core.bounds.Bounds;
import org.expeditee.encryption.items.surrogates.Label;
import org.expeditee.gio.EcosystemManager;
import org.expeditee.gio.GraphicsManager;
import org.expeditee.gio.gesture.StandardGestureActions;
import org.expeditee.items.Item;
import org.expeditee.items.ItemParentStateChangedEvent;
import org.expeditee.items.ItemUtils;
import org.expeditee.items.Picture;
import org.expeditee.items.Text;
import org.expeditee.items.MagneticConstraint.MagneticConstraints;
import org.expeditee.settings.UserSettings;
import org.expeditee.stats.SessionStats;
import org.expeditee.taskmanagement.EntitySaveManager;

/**
 * Controls the layout of the frames inside the display. 
 * 
 * @author jdm18
 * @author cts16
 */
public final class DisplayController {
	
	/** Enumeration of the two sides of twin-frames mode. */
	public static enum TwinFramesSide {
		LEFT,
		RIGHT
	}
	
	// To help title calculations on frame
	public static final int MINIMUM_FRAME_WIDTH  = 512;
	public static final int MINIMUM_FRAME_HEIGHT = 512;
	
	public static boolean DISPLAYED_ABOVE_MINIMUM_FRAME_WIDTH = false;
	
	/** Convenience definition of TwinFramesSide.LEFT. */
	public static final TwinFramesSide LEFT = TwinFramesSide.LEFT;
	/** Convenience definition of TwinFramesSide.RIGHT. */
	public static final TwinFramesSide RIGHT = TwinFramesSide.RIGHT;

	/** The side-length of a small cursor (in pixels). */
	public static final int SMALL_CURSOR_SIZE = 16;
	/** The side-length of a medium cursor (in pixels). */
	public static final int MEDIUM_CURSOR_SIZE = 32;
	/** The side-length of a large cursor (in pixels). */
	public static final int LARGE_CURSOR_SIZE = 64;

	/** The height of the message bay at program start. */
	public static final int INITIAL_MESSAGE_BAY_HEIGHT = 105;

	/** The colour to be used to highlight the linked parent item, when the user navigates backwards. */
	public static final Colour BACK_HIGHLIGHT_COLOR = Colour.MAGENTA;
	
	/** The stroke used to draw the separating lines between the display areas. */
	protected static final Stroke SEPARATOR_STROKE = new Stroke(1);
	/** The colour used to draw the separating lines between the display areas. */
	protected static final Colour SEPARATOR_COLOUR = Colour.BLACK;
    
	/** The title to display in the Title bar. */
	public static final String TITLE = "Expeditee";
	
	/** The image to use as the window icon. */
	public static final String ICON_IMAGE = "org/expeditee/assets/icons/expediteeicon128.png";

	/** The current frame being displayed on each side of the window. */
	private static Frame[] _currentFrames = new Frame[2];
	
	/** The transitions to use on each side when changing frame. */
	private static FrameTransition[] _transitions = new FrameTransition[2];

	/** Maintains the list of frames visited thus-far for back-tracking. */
	@SuppressWarnings("unchecked")
	private static Stack<String>[] _visitedFrames = new Stack[2];

	/** TODO: Comment. cts16 */
	@SuppressWarnings("unchecked")
	private static Stack<String>[] _backedUpFrames = new Stack[2];

	/** Whether we are currently in twin-frames mode. */
	private static boolean _twinFramesMode = false;
	
	/** Whether we are currently displaying in audience mode. */
	private static boolean _audienceMode = false;
	
	/** Whether we are currently displaying mail mode whilst not in audience mode */
	private static boolean _mailMode = false;
	
	/** Whether we are currently displaying in x-ray mode. */
	private static boolean _xrayMode = false;

	/** Notified whenever the frame changes. */
	private static HashSet<DisplayObserver> _displayObservers = new HashSet<DisplayObserver>();
	
	/** What type of cursor we are using. */
	private static Cursor.CursorType _cursorType = Item.DEFAULT_CURSOR;
	
	/** The size of the window which this class controls. */
	private static Dimension _windowSize = null;
	
	/** The area in the window where the left frame should be painted in twin-frames mode. */
	private static AxisAlignedBoxBounds _leftFramePaintArea = null;
	/** The area in the window where the right frame should be painted in twin-frames mode. */
	private static AxisAlignedBoxBounds _rightFramePaintArea = null;
	/** The area in the window where the frame should be painted in single-frame mode. */
	private static AxisAlignedBoxBounds _framePaintArea = null;
	/** The area in the window where the message bay should be painted. */
	private static AxisAlignedBoxBounds _messageBayPaintArea = null;
	
	/** The height of the message bay. */
	private static int _messageBayHeight = INITIAL_MESSAGE_BAY_HEIGHT;
	/** The percentage of the display width allocated to the left frame. */
	private static float _twinFramesLeftWidthProportion = 0.5f;
	
	
	/** The damage areas accumulated by item changes. */
	private static DamageAreas _damagedAreas = new DamageAreas();

	/** The buffered display image for preventing flickering during rendering. */
	private static Image _refreshBuffer = null;
	
	/** Static-only class. */
	private DisplayController()
	{
	}

	/** Initialises the display controller. */
	public static void Init()
	{
		_visitedFrames[0] = new Stack<String>();
		_visitedFrames[1] = new Stack<String>();
		_backedUpFrames[0] = new Stack<String>();
		_backedUpFrames[1] = new Stack<String>();
		
		refreshCursor();
		refreshWindowSize();
	}
	
	/** Notifies observers that the frame has changed. */
	private static void fireFrameChanged()
	{
		for (DisplayObserver observer : _displayObservers) {
			observer.frameChanged();
		}
	}

	/**
	 * Adds a DisplayObserver to the display controller. DisplayObserver's are
	 * notified when frame changes.
	 * 
	 * @see #removeDisplayObserver(DisplayObserver)
	 * 
	 * @param observer
	 *            The observer to add
	 * 
	 * @throws NullPointerException
	 *             If observer is null.
	 */
	public static void addDisplayObserver(DisplayObserver observer)
	{
		if (observer == null) {
			throw new NullPointerException("observer");
		}
		
		_displayObservers.add(observer);
	}

	/**
	 * Removes a DisplayObserver from the display controller.
	 * 
	 * @see #addDisplayObserver(DisplayObserver)
	 * 
	 * @param observer
	 *            The observer to add
	 * 
	 * @throws NullPointerException
	 *             If observer is null.
	 */
	public static void removeDisplayObserver(DisplayObserver observer)
	{
		if (observer == null) {
			throw new NullPointerException("observer");
		}
		
		_displayObservers.remove(observer);
	}

	/**
	 * TODO: Comment. cts16
	 * TODO: Move. Doesn't belong here. cts16
	 */
	public static void setTextCursor(Text text, int cursorMovement)
	{
		setTextCursor(text, cursorMovement, false, false, false, false);
	}

	/**
	 * TODO: Comment. cts16
	 * TODO: Refactor. Too monolithic. cts16
	 * TODO: Move. Doesn't belong here. cts16
	 */
	public static void setTextCursor(Text text, int cursorMovement,
			boolean newSize, boolean isShiftDown, boolean isCtrlDown,
			boolean allowClearSelection) {

		int size = Math.round(text.getSize());
		
		if (allowClearSelection && !isShiftDown && text.hasSelection()) {
			text.clearSelection();
		}

		Point newMouse = text.moveCursor(cursorMovement, DisplayController.getFloatMouseX(), EcosystemManager.getInputManager().getCursorPosition().getY(), isShiftDown, isCtrlDown);
						
		if( isCtrlDown ||
			(DisplayController.getFloatMouseX() <= newMouse.getX() && newMouse.getX() <= DisplayController.getFloatMouseX() + 1) ||
			(DisplayController.getFloatMouseX() > newMouse.getX() && cursorMovement == Text.RIGHT))
		{
			if(cursorMovement == Text.RIGHT && !MagneticConstraints.getInstance().rightBorderHit(text)) {
				MagneticConstraints.getInstance().endOfLineHit(text);
			} else {
				if(cursorMovement == Text.LEFT && !MagneticConstraints.getInstance().leftBorderHit(text)) {
					MagneticConstraints.getInstance().startOfLineHit(text);
				}
			}
			newMouse.setX((int) DisplayController.getFloatMouseX());
			newMouse.setY((int) DisplayController.getFloatMouseY());
		} else if(cursorMovement == Text.UP && MagneticConstraints.getInstance().topBorderHit(text)) {
			newMouse.setX((int) DisplayController.getFloatMouseX());
			newMouse.setY((int) DisplayController.getFloatMouseY());
		} else if(cursorMovement == Text.DOWN && MagneticConstraints.getInstance().bottomBorderHit(text)) {
			newMouse.setX((int) DisplayController.getFloatMouseX());
			newMouse.setY((int) DisplayController.getFloatMouseY());
		}

		if (!newSize && _cursorType == Item.TEXT_CURSOR) {
			if (cursorMovement != 0) {
				DisplayController.setCursorPosition(newMouse, false);
			}
			return;
		}

		_cursorType = Item.TEXT_CURSOR;

		// Do some stuff to adjust the cursor size based on the font size
		final int MEDIUM_CURSOR_CUTOFF = 31;
		final int LARGE_CURSOR_CUTOFF = 62;

		int cursorSize = LARGE_CURSOR_SIZE;
		int hotspotPos = 0;
		int start = 0;

		Dimension best_cursor_dim = EcosystemManager.getGraphicsManager().getBestCursorSize(new Dimension(cursorSize,cursorSize));
		int best_cursor_height = best_cursor_dim.height;
		
		if (best_cursor_height < cursorSize) {
			// not able to provide the size of cursor Expeditee wants to
			// => lock on to 'best_cursor_height' and use this to generate dependent values
			cursorSize = best_cursor_height; // OS + Java version dependent: most likely MEDIUM_CURSOR_SIZE
			if (size < best_cursor_height) {
				start = cursorSize - size - 1;
				hotspotPos = cursorSize - (size + 1) / 4;
			}
			else {
				start = size - best_cursor_height;
				hotspotPos = cursorSize -1;
			}
			
		}
		else if (size < MEDIUM_CURSOR_CUTOFF) {
			cursorSize = MEDIUM_CURSOR_SIZE;
			start = cursorSize - size - 1;
			hotspotPos = cursorSize - (size + 1) / 4;
		} else if (size < LARGE_CURSOR_CUTOFF) {
			hotspotPos = cursorSize - (size - 5) / 4;
			start = cursorSize - size - 2;
		} else {
			int FIXED_CURSOR_MIN = 77;
			if (size >= FIXED_CURSOR_MIN) {
				hotspotPos = cursorSize - 2;
			} else {
				hotspotPos = size - (FIXED_CURSOR_MIN - cursorSize);
			}
		}
		
		int[] pixels = new int[cursorSize * cursorSize];

		for (int i = start; i < cursorSize; i++) {
			pixels[i * cursorSize] = pixels[i * cursorSize + 1] = 0xFF000000;
		}

		Image image = Image.createImage(cursorSize, cursorSize, pixels);
		
		EcosystemManager.getGraphicsManager().setCursor(new Cursor(image, new Point(0, hotspotPos), "textcursor"));
		
		if (cursorMovement != Text.NONE) {
			DisplayController.setCursorPosition(newMouse, false);
		}
	}

	/**
	 * Sets the type of cursor the display should be using
	 * 
	 * @param type
	 *            The type of cursor to display, using constants defined in the
	 *            Cursor class.
	 */
	public static void setCursor(Cursor.CursorType type)
	{
		// Avoid flicker when not changing
		if (type == _cursorType) {
			return;
		}

		_cursorType = type;
		
		refreshCursor();
	}

	/** Gets the type of cursor the display is currently using. */
	public static Cursor.CursorType getCursor()
	{
		return _cursorType;
	}
	
	/** Updates the cursor with the graphics manager. */
	private static void refreshCursor()
	{
		if (_cursorType == Item.HIDDEN_CURSOR || (FreeItems.hasCursor() && _cursorType == Item.DEFAULT_CURSOR)) {
			Cursor invisibleCursor = Cursor.createInvisibleCursor();
			EcosystemManager.getGraphicsManager().setCursor(invisibleCursor);
		} else {
			EcosystemManager.getGraphicsManager().setCursor(new Cursor(_cursorType));
		}
	}

	/**
	 * Moves the mouse cursor to the given x,y coordinates on the screen
	 * 
	 * @param x
	 *            The x coordinate
	 * @param y
	 *            The y coordinate
	 */
	public static void setCursorPosition(float x, float y)
	{
		setCursorPosition(x, y, true);
	}

	/** TODO: Comment. cts16 */
	public static void setCursorPosition(float x, float y, boolean forceArrow)
	{
		// Adjust the position to move the mouse to to account for being in
		// TwinFramesMode
		if (isTwinFramesOn()) {
			if (getCurrentSide() == RIGHT) {
				int middle = getTwinFramesSeparatorX();
				x += middle;
			}
		}

		if (FreeItems.hasItemsAttachedToCursor()) {
			Point mousePos = EcosystemManager.getInputManager().getCursorPosition();
			float deltax = x - mousePos.getX();
			float deltay = y - mousePos.getY();
			List<Item> toMove = FreeItems.getInstance();
			for (Item move : toMove) {
				move.setPosition(move.getX() + deltax, move.getY() + deltay);
			}
		}

		// cheat
		StandardGestureActions.setForceArrow(forceArrow);
		EcosystemManager.getInputManager().setCursorPosition(new Point(x, y));
	}

	public static void resetCursorOffset()
	{
		StandardGestureActions.resetOffset();
	}

	/**
	 * Sets the current cursor position in the current frame
	 * 
	 * @param pos
	 */
	public static void setCursorPosition(Point pos)
	{
		setCursorPosition(pos.getX(), pos.getY());
	}

	public static void setCursorPosition(Point pos, boolean forceArrow)
	{
		setCursorPosition(pos.getX(), pos.getY(), forceArrow);
	}

	/**
	 * Returns the top item (last added) of the Back-Stack (which is popped off)
	 * 
	 * @return The name of the last Frame added to the back-stack
	 */
	public static String getLastFrame()
	{
		TwinFramesSide side = getCurrentSide();
		Stack<String> visitedFrames = getVisitedFrames(side);

		if (visitedFrames.size() > 0) {
			return visitedFrames.pop();
		} else {
			return null;
		}
	}

	/**
	 * Adds the given Frame to the back-stack
	 * 
	 * @param frame
	 *            The Frame to add
	 */
	public static void addToBack(Frame toAdd)
	{
		TwinFramesSide side = getCurrentSide();
		Stack<String> visitedFrames = getVisitedFrames(side);

		visitedFrames.push(toAdd.getName());
	}

	public static String removeFromBack()
	{
		return getLastFrame();
	}

	/**
	 * Returns a 'peek' at the end element on the back-stack of the current
	 * side. If the back-stack is empty, null is returned.
	 * 
	 * @return The name of the most recent Frame added to the back-stack, or
	 *         null if the back-stack is empty.
	 */
	public static String peekFromBackUpStack()
	{
		TwinFramesSide side = getCurrentSide();
		Stack<String> visitedFrames = getVisitedFrames(side);

		// check that the stack is not empty
		if (visitedFrames.size() > 0) {
			return visitedFrames.peek();
		}

		// if the stack is empty, return null
		return null;
	}
	
	/** Sets the transition to use when leaving the given frame. */
	public static void setTransition(Frame frame, FrameTransition transition)
	{
		if (frame == null) {
			return;
		}
		TwinFramesSide side = getSideFrameIsOn(frame);
		setTransition(side, transition);
	}
	
	/** Sets the transition to use when changing frame on the given side. */
	private static void setTransition(TwinFramesSide side, FrameTransition transition)
	{
		if (side == null) {
			return;
		}
		
		_transitions[side.ordinal()] = transition;
	}
	
	/** Gets the transition to use when changing frame on the given side. */
	private static FrameTransition getTransition(TwinFramesSide side)
	{
		if (side == null) {
			return null;
		}
		
		return _transitions[side.ordinal()];
	}

	/**
	 * TODO: Comment. cts16
	 * TODO: Refactor. Too monolithic. cts16
	 */
	public static void setCurrentFrame(Frame frame, boolean incrementStats)
	{
		if (frame == null) {
			return;
		}

		// If one of the sides doesn't have a frame yet, give it this one
		if (isTwinFramesOn()) {
			for (TwinFramesSide side : TwinFramesSide.values()) {
				if (!sideHasFrame(side)) {
					setFrameOnSide(frame, side);
					fireFrameChanged();
					return;
				}
			}
		}

		// if this is already the current frame
		if (frame == getCurrentFrame()) {
			requestRefresh(false);
			MessageBay.displayMessage(frame.getName() + " is already the current frame.");
			return;
		}
		
		// Update stats
		if (incrementStats) {
			SessionStats.AccessedFrame();
		}

		// Invalidate free items
		if (!FreeItems.getInstance().isEmpty() && getCurrentFrame() != null) {

			// Empty free items temporarily so that the old frames buffer is repainted without the free items.
			ArrayList<Item> tmp = FreeItems.getInstance().clone();
			FreeItems.getInstance().clear(); // NOTE: This will invalidate all the cleared free items
			requestRefresh(true);
			FreeItems.getInstance().addAll(tmp);

		}

		// Changing frames is a Save point for saveable entities:
		EntitySaveManager.getInstance().saveAll();

		if (_twinFramesMode) {
			// if the same frame is being shown in both sides, load a fresh
			// copy from disk
			if (getOppositeFrame() == frame || getOppositeFrame().hasOverlay(frame)) {
				FrameIO.SuspendCache();
				frame = FrameIO.LoadFrame(frame.getName());
				FrameIO.ResumeCache();
			}

			// If the frames are the same then the items for the
			// frame that is just about to hide will still be in view
			// so only notify items that they are hidden if the
			// frames differ.
			if (getCurrentFrame() != null && !bothSidesHaveSameFrame()) {
				for (Item i : getCurrentFrame().getSortedItems()) {
					i.onParentStateChanged(new ItemParentStateChangedEvent(getCurrentFrame(), ItemParentStateChangedEvent.EVENT_TYPE_HIDDEN));
				}
			}
			setFrameOnSide(frame, getCurrentSide());

			// BROOK : TODO... overlays and loadable widgets
			for (Item i : getCurrentFrame().getSortedItems()) {
				i.onParentStateChanged(new ItemParentStateChangedEvent(getCurrentFrame(), ItemParentStateChangedEvent.EVENT_TYPE_SHOWN));
			}
		} else {

			// Notifying items on the frame being hidden that they
			// are about to be hidden.
			// ie. Widgets use this method to remove themselves from the JPanel
			List<Frame> currentOnlyOverlays = new LinkedList<Frame>();
			List<Frame> nextOnlyOverlays = new LinkedList<Frame>();
			List<Frame> sharedOverlays = new LinkedList<Frame>();

			// Get all overlayed frames seen by the next frame
			for (Overlay o : frame.getOverlays()) {
				if (!nextOnlyOverlays.contains(o.Frame)) {
					nextOnlyOverlays.add(o.Frame);
				}
			}

			// Get all overlayed frames seen by the current frame
			if (getCurrentFrame() != null) {
				for (Overlay o : getCurrentFrame().getOverlays()) {
					if (!currentOnlyOverlays.contains(o.Frame)) {
						currentOnlyOverlays.add(o.Frame);
					}
				}
			}

			// Extract shared overlays between the current and next frame
			for (Frame of : currentOnlyOverlays) {
				if (nextOnlyOverlays.contains(of)) {
					sharedOverlays.add(of);
				}
			}

			// The first set, currentOnlyOverlays, must be notified that they
			// are hidden
			Collection<Item> items = new LinkedList<Item>();

			// Notify items that will not be in view any more
			if (getCurrentFrame() != null) {
				List<Frame> seen = new LinkedList<Frame>();
				seen.addAll(sharedOverlays); // Signify that seen all shared
				// overlays
				seen.remove(getCurrentFrame()); // must ensure
				// excluded

				// Get all items seen from the current frame - including all
				// possible non-shared overlays
				items = getCurrentFrame().getAllItems();
				for (Frame f : seen) {
					items.removeAll(f.getAllItems());
				}

				// Notify items that they are hidden
				for (Item i : items) {
					i.onParentStateChanged(new ItemParentStateChangedEvent(getCurrentFrame(), ItemParentStateChangedEvent.EVENT_TYPE_HIDDEN));
				}
			}

			// Set the new frame
			setFrameOnSide(frame, getCurrentSide());
			frame.refreshSize();
			
			// Notify items on the frame being displayed that they are in view
			// ie. widgets use this method to add themselves to the content pane
			items.clear();

			// Notify overlay items that they are shown
			for (Item i : frame.getOverlayItems()) {
				Overlay owner = frame.getOverlayOwner(i);
				// if (owner == null) i.onParentFameShown(false, 0);
				// else ...
				assert (owner != null);
				i
						.onParentStateChanged(new ItemParentStateChangedEvent(
								frame,
								ItemParentStateChangedEvent.EVENT_TYPE_SHOWN_VIA_OVERLAY,
								owner.permission));
			}

			for (Item i : frame.getSortedItems()) {
				i.onParentStateChanged(new ItemParentStateChangedEvent(frame,
						ItemParentStateChangedEvent.EVENT_TYPE_SHOWN));
			}
		}
		
		frame.reset();
		
		// fix text items
		ItemUtils.Justify(frame);
		
		StandardGestureActions.refreshHighlights();
		requestRefresh(false);
		fireFrameChanged();
	}

	/** Updates the window title bar to show which mode Expeditee is in. */
	public static void updateTitle()
	{
		StringBuffer title = new StringBuffer(TITLE);

		if (isAudienceMode()) {
			title.append(" - Audience Mode");
		} else if (isXRayMode()) {
			title.append(" - X-Ray Mode");
		} else {
			title.append(" [").append(SessionStats.getShortStats()).append(']');
		}
		
		EcosystemManager.getGraphicsManager().setWindowTitle(title.toString());
	}
	
	/** Whether the given side has a frame. */
	public static boolean sideHasFrame(TwinFramesSide side)
	{
		return getFrameOnSide(side) != null;
	}

	/** Gets the side of the twin-frames display that the mouse is over. */
	public static TwinFramesSide getCurrentSide()
	{
		
		// If the mouse is over the right side of the window and there's a valid frame,
		// we are on the right side.
		if(isTwinFramesOn()) {
			int mouseX = EcosystemManager.getInputManager().getCursorPosition().getX();
			if(mouseX >= getTwinFramesSeparatorX() && sideHasFrame(RIGHT)) {
				return RIGHT;
			}
		}
		
		// If there's only a right frame, that's the current side
		if (!sideHasFrame(LEFT) && sideHasFrame(RIGHT)) {
			return RIGHT;
		}

		// In any other case the left side is the current side
		return LEFT;
	}

	/** Gets the opposite side to the current side of the twin-frames. */
	private static TwinFramesSide getOppositeSide()
	{
		if (getCurrentSide() == LEFT) {
			return RIGHT;
		}

		return LEFT;
	}

	/** Returns the side that the given frame is on, or null if it's not on either side. */
	public static TwinFramesSide getSideFrameIsOn(Frame frame)
	{
		// Loop through both sides
		for (TwinFramesSide side : TwinFramesSide.values()) {
			if (getFrameOnSide(side) == frame) {
				return side;
			}
		}

		return null;
	}

	/** Gets the frame that is on the given side of the display. */
	public static Frame getFrameOnSide(TwinFramesSide side)
	{
		if (side == null) {
			return null;
		}
		
		return _currentFrames[side.ordinal()];
	}
	
	/** Returns the frame on the current side of the display. */
	public static Frame getCurrentFrame()
	{
		return getFrameOnSide(getCurrentSide());
	}

	/** Returns the frame on the opposite side of the display. */
	public static Frame getOppositeFrame()
	{
		return getFrameOnSide(getOppositeSide());
	}

	/** Gets the two frames being displayed. */
	public static Frame[] getFrames()
	{
		return _currentFrames;
	}

	/** Gets the x-coordinate of the division between the left and right sides. */
	public static int getTwinFramesSeparatorX()
	{
		return getLeftFramePaintArea().getWidth() + (int) (SEPARATOR_STROKE.thickness / 2);
	}
	
	/** Gets the line that separates the two sides of the twin-frames display. */
	public static Line getTwinFramesSeparatorLine()
	{
		if (!isTwinFramesOn()) {
			return null;
		}
		
		int x = getTwinFramesSeparatorX();
		int bottom = getFramePaintArea().getMaxY();
		
		return new Line(x, 0, x, bottom);
		
	}

	/** Gets the line that separates the message bay from the frame area. */
	public static Line getMessageBaySeparatorLine()
	{
		// No message bay in audience mode
		if (isAudienceMode()) {
			return null;
		}
		
		int separatorThickness = (int) SEPARATOR_STROKE.thickness;
		int y = getFramePaintArea().getMaxY() + separatorThickness / 2 + separatorThickness % 2;
		int right = getMessageBayPaintArea().getMaxX();
		
		return new Line(0, y, right, y);
	}

	/**
	 * Returns the current mouse X coordinate. This coordinate is relative to
	 * the left edge of the frame the mouse is in. It takes into account the
	 * user being in twin frames mode.
	 * 
	 * @return The X coordinate of the mouse.
	 */
	public static float getFloatMouseX()
	{
		return getMouseX();
	}


	/**
	 * Returns the current mouse X coordinate. This coordinate is relative to
	 * the left edge of the frame the mouse is in. It takes into account the
	 * user being in twin frames mode.
	 * 
	 * @return The X coordinate of the mouse.
	 */
	public static int getMouseX()
	{
		return getMousePosition().getX();
	}

	/**
	 * Returns the current mouse position. This coordinate is relative to
	 * the upper-left edge of the frame the mouse is in. It takes into account the
	 * user being in twin frames mode.
	 * 
	 * @return The position of the mouse.
	 */
	public static Point getMousePosition()
	{
		Point mousePos = EcosystemManager.getInputManager().getCursorPosition();
		
		if (isTwinFramesOn() && getRightFramePaintArea().contains(mousePos)) {
			mousePos.setX(mousePos.getX() - getRightFramePaintArea().getMinX());
		}

		return mousePos;
	}
	
	/**
	 * Returns the current mouse Y coordinate. This coordinate is relative to
	 * the top edge of the frame the mouse is in. 
	 * 
	 * @return The Y coordinate of the mouse.
	 */
	public static float getFloatMouseY()
	{
		return getMouseY();
	}
	
	/**
	 * Returns the current mouse Y coordinate. This coordinate is relative to
	 * the top edge of the frame the mouse is in. 
	 * 
	 * @return The Y coordinate of the mouse.
	 */
	public static int getMouseY()
	{
		return getMousePosition().getY();
	}
	
	/**
	 * TODO: Comment. cts16
	 * @return
	 */
	public static boolean Back()
	{
		TwinFramesSide side = getCurrentSide();
		Stack<String> visitedFrames = getVisitedFrames(side);

		// there must be a frame to go back to
		if (visitedFrames.size() < 1) {
			MessageBay.displayMessageOnce("You are already on the home frame");
			return false;
		}

		if (!FrameUtils.LeavingFrame(getCurrentFrame())) {
			MessageBay.displayMessage("Error navigating back");
			return false;
		}

		String oldFrame = getCurrentFrame().getName().toLowerCase();

		// do not get a cached version (in case it is in the other window)
		if (isTwinFramesOn()) {
			FrameIO.SuspendCache();
		}
		
		Frame frame = FrameIO.LoadFrame(removeFromBack());
		// If the top frame on the backup stack is the current frame go back
		// again... or if it has been deleted
		// Recursively backup the stack
		if (frame == null || frame.equals(getCurrentFrame())) {
			Back();
			return false;
		}

		if (isTwinFramesOn()) {
			FrameIO.ResumeCache();
		}
		getBackedUpFrames(side).push(oldFrame);
		FrameUtils.DisplayFrame(frame, false, true);
		StandardGestureActions.setHighlightHold(true);

		for (Item i : frame.getSortedItems()) {
			if (i.getLink() != null && i.getAbsoluteLink().toLowerCase().equals(oldFrame)) {
				if (i.getHighlightMode() != Item.HighlightMode.Normal) {
					i.setHighlightModeAndColour(Item.HighlightMode.Normal,
							BACK_HIGHLIGHT_COLOR);
				}
				// check if its an @f item and if so update the buffer
				if (i instanceof Picture) {
					Picture p = (Picture) i;
					p.refresh();
				}
			}
		}
		requestRefresh(true);
		return true;
	}

	/**
	 * TODO: Comment. cts16
	 * @return
	 */
	public static boolean Forward()
	{
		TwinFramesSide side = getCurrentSide();

		// there must be a frame to go back to
		if (getBackedUpFrames(side).size() == 0) {
			return false;
		}

		if (!FrameUtils.LeavingFrame(getCurrentFrame())) {
			MessageBay.displayMessage("Error navigating forward");
			return false;
		}

		String oldFrame = getCurrentFrame().getName().toLowerCase();

		// do not get a cached version (in case it is in the other window)
		if (isTwinFramesOn()) {
			FrameIO.SuspendCache();
		}
		Frame frame = FrameIO.LoadFrame(getBackedUpFrames(side).pop());
		// If the top frame on the backup stack is the current frame go back
		// again... or if it has been deleted
		// Recursively backup the stack
		if (frame == null || frame.equals(getCurrentFrame())) {
			Forward();
			return false;
		}

		if (isTwinFramesOn()) {
			FrameIO.ResumeCache();
		}
		getVisitedFrames(side).push(oldFrame);
		FrameUtils.DisplayFrame(frame, false, true);
		requestRefresh(true);
		return true;
	}

	/** Toggles the display of frames between TwinFrames mode and Single frame mode. */
	public static void toggleTwinFrames()
	{
		// determine which side is the active side
		TwinFramesSide opposite = getOppositeSide();
		_twinFramesMode = !_twinFramesMode;

		// if TwinFrames is being turned on
		if (_twinFramesMode) {
			// if this is the first time TwinFrames has been toggled on,
			// load the user's first frame
			if (getVisitedFrames(opposite).size() == 0) {
				FrameIO.SuspendCache();
				setCurrentFrame(FrameIO.LoadFrame(UserSettings.HomeFrame.get()), true);
				FrameIO.ResumeCache();
			} else {
				// otherwise, restore the frame from the side's back-stack
				setCurrentFrame(FrameIO.LoadFrame(getVisitedFrames(opposite).pop()), true);
			}

			// else, TwinFrames is being turned off
		} else {
			// add the frame to the back-stack
			Frame hiding = getOppositeFrame();
			FrameUtils.LeavingFrame(hiding);
			getVisitedFrames(opposite).add(hiding.getName());
			setFrameOnSide(null, opposite);
			getCurrentFrame().refreshSize();
		}
		
		// Update the sizes of the displayed frames
		if (getCurrentFrame() != null) {
			getCurrentFrame().refreshSize();
		}
		if (getOppositeFrame() != null) {
			getOppositeFrame().refreshSize();
		}

		requestRefresh(false);
	}

	/** Whether the display is currently in twin-frames mode. */
	public static boolean isTwinFramesOn()
	{
		return _twinFramesMode;
	}

	/** TODO: Comment. cts16 */
	public static void Reload(TwinFramesSide side)
	{
		if (side == null) {
			return;
		}

		FrameIO.SuspendCache();
		Frame frame = FrameIO.LoadFrame(getFrameOnSide(side).getName());
		setFrameOnSide(frame, side);
		FrameIO.ResumeCache();
	}
	
	/**
	 * Moves the cursor the end of this item.
	 * 
	 * @param i
	 */
	public static void MoveCursorToEndOfItem(Item i)
	{
		setTextCursor((Text) i, Text.END, true, false, false, false);
	}
	
	public static void clearBackedUpFrames()
	{
		getBackedUpFrames(getCurrentSide()).clear();
	}

	/**
	 * @param secondsDelay
	 * @param s
	 * @throws InterruptedException
	 */
	public static void typeStringDirect(double secondsDelay, String s) throws InterruptedException
	{
		for (int i = 0; i < s.length(); i++) {
			StandardGestureActions.processChar(s.charAt(i), false);
			Thread.sleep((int) (secondsDelay * 1000));
		}
	}

	public static List<String> getUnmodifiableVisitedList()
	{
		return Collections.unmodifiableList(getVisitedFrames(getCurrentSide()));
	}
	
	/** If both sides have the same frame (returns false if both sides have no frame). */
	public static boolean bothSidesHaveSameFrame()
	{
		return (getCurrentFrame() != null && getCurrentFrame() == getOppositeFrame());
	}
	
	/** Sets the given side to the given frame. */
	private static void setFrameOnSide(Frame frame, TwinFramesSide side)
	{
		if (side == null) {
			return;
		}
		
		_currentFrames[side.ordinal()] = frame;
	}
	
	/** Gets the stack of visited frames for the given side. */
	private static Stack<String> getVisitedFrames(TwinFramesSide side)
	{
		if (side == null) {
			return null;
		}
		
		return _visitedFrames[side.ordinal()];
	}

	/** Gets the stack of backed-up frames for the given side. */
	private static Stack<String> getBackedUpFrames(TwinFramesSide side)
	{
		if (side == null) {
			return null;
		}
		
		return _backedUpFrames[side.ordinal()];
	}

	/**
	 * Rotates through normal -> audience -> audience + fullscreen modes and back again.
	 */
	public static void rotateAudienceModes()
	{
		Frame current = DisplayController.getCurrentFrame();
		GraphicsManager g = EcosystemManager.getGraphicsManager();
		if (_audienceMode && g.isFullscreen()) {
			ToggleAudienceMode();
			g.exitFullscreen();
		} else if (_audienceMode) {
			if (g.canGoFullscreen()) {
				g.goFullscreen();
			} else {
				ToggleAudienceMode();
			}
		} else {
			ToggleAudienceMode();
			ItemUtils.UpdateConnectedToAnnotations(current.getSortedItems());
			for (Overlay o : current.getOverlays()) {
				ItemUtils.UpdateConnectedToAnnotations(o.Frame.getSortedItems());
			}
			for (Vector v : current.getVectorsDeep()) {
				ItemUtils.UpdateConnectedToAnnotations(v.Frame.getSortedItems());
			}
		}
	}
	
	/**
	 * If Audience Mode is on this method will toggle it to be off, or
	 * vice-versa. This results in the Frame being re-parsed and repainted.
	 */
	public static void ToggleAudienceMode()
	{
		Frame current = DisplayController.getCurrentFrame();
		
		// Turn off x-ray mode if it's on
		if (_xrayMode) {
			ToggleXRayMode();
		}
	
		// Toggle audience mode
		_audienceMode = !_audienceMode;

		refreshPaintAreas();
		FrameUtils.Parse(current);
		updateTitle();
		requestRefresh(false);
	}
	
	/**
	 * If Mail Mode is on, this method will toggle it to be off, or vice-versa.
	 * This results in the Frame being re-parsed and repainted.
	 */
	public static void ToggleMailMode() {
		Frame current = DisplayController.getCurrentFrame();
		
		// Turn off x-ray mode if it's on
		if (_xrayMode) {
			ToggleXRayMode();
		}
		
		_mailMode = !_mailMode;
		
		refreshPaintAreas();
		FrameUtils.Parse(current);
		updateTitle();
		requestRefresh(false);
	}
	
	/**
	 * Turns Mail Mode off.
	 * This results in the Frame being re-parsed and repainted.
	 */
	public static void DisableMailMode() {
		Frame current = DisplayController.getCurrentFrame();
		
		// Turn off x-ray mode if it's on
		if (_xrayMode) {
			ToggleXRayMode();
		}
		
		_mailMode = false;
		
		refreshPaintAreas();
		FrameUtils.Parse(current);
		updateTitle();
		requestRefresh(false);
	}

	/**
	 * If X-Ray Mode is on this method will toggle it to be off, or vice-versa.
	 * This results in the Frame being re-parsed and repainted.
	 */
	public static void ToggleXRayMode()	{
		// Turn off x-ray mode if it is on
		if (_audienceMode) {
			ToggleAudienceMode();
		}

		_xrayMode = !_xrayMode;
		
		if(_xrayMode) {
			//Entering XRay Mode is a Save point for saveable entities
			EntitySaveManager.getInstance().saveAll();
		}
		
		getCurrentFrame().parse();
		getCurrentFrame().refreshSize();
		updateTitle();
		StandardGestureActions.refreshHighlights();
		StandardGestureActions.updateCursor();
		requestRefresh(false);
	}
	
	public static void ToggleSurrogateMode() {
		// Turn off x-ray mode if it is on
		if (_audienceMode) {
			ToggleAudienceMode();
		}
		
		Label.progressSurrogateMode();
		
		getCurrentFrame().parse();
		getCurrentFrame().refreshSize();
		updateTitle();
		StandardGestureActions.refreshHighlights();
		StandardGestureActions.updateCursor();
		requestRefresh(false);
	}
	
	public static void ResetSurrogateMode() {
		// Turn off x-ray mode if it is on
		if (_audienceMode) {
			ToggleAudienceMode();
		}
		
		Label.resetSurrogateMode();
		
		getCurrentFrame().parse();
		getCurrentFrame().refreshSize();
		updateTitle();
		StandardGestureActions.refreshHighlights();
		StandardGestureActions.updateCursor();
		requestRefresh(false);
	}
	
	/** Whether audience mode is currently on. */
	public static boolean isAudienceMode()
	{
		return _audienceMode;
	}
		
	/** Whether mail mode is currently on. */
	public static boolean isMailMode() {
		return _mailMode;
	}

	/** Whether x-ray mode is currently on. */
	public static boolean isXRayMode()
	{
		return _xrayMode;
	}
	
	public static Dimension getSizeEnforceMinimumXXXX() { // **** DB
		Dimension actual_dim = getFramePaintAreaSize(); 
		
		int enforced_width  = Math.max(actual_dim.width, MINIMUM_FRAME_WIDTH);
		int enforced_height = Math.max(actual_dim.height,MINIMUM_FRAME_HEIGHT);
		
		Dimension enforced_dim = new Dimension(enforced_width,enforced_height);
		
		return enforced_dim;
	}
	
	/** Tells the display controller to get the current window size. */
	public static void refreshWindowSize()
	{
		_windowSize = EcosystemManager.getGraphicsManager().getWindowSize();
		_refreshBuffer = Image.createImage(_windowSize, true);
		if (_windowSize.getWidth() > MINIMUM_FRAME_WIDTH) {
			DISPLAYED_ABOVE_MINIMUM_FRAME_WIDTH = true;
		}
		refreshPaintAreas();
	}
	
	/** Recalculates the paint areas for the frames and message bay. */
	public static void refreshPaintAreas()
	{
		// Calculate the width of each frame in twin-frames mode
		int availableWindowWidth = _windowSize.width - (int) SEPARATOR_STROKE.thickness;
		int leftFrameWidth = (int) (availableWindowWidth * _twinFramesLeftWidthProportion);
		int rightFrameWidth = availableWindowWidth - leftFrameWidth;
		
		// The height of each frame is the window height, minus the message bay if visible
		int frameHeight = _windowSize.height;
		if (!isAudienceMode()) {
			frameHeight -= _messageBayHeight + (int) SEPARATOR_STROKE.thickness;
		}
		
		int rightFrameX = _windowSize.width - rightFrameWidth;
		int messageBayY = _windowSize.height - _messageBayHeight;
		
		_leftFramePaintArea = new AxisAlignedBoxBounds(0, 0, leftFrameWidth, frameHeight);
		_rightFramePaintArea = new AxisAlignedBoxBounds(rightFrameX, 0, rightFrameWidth, frameHeight);
		_framePaintArea = new AxisAlignedBoxBounds(0, 0, _windowSize.width, frameHeight);
		_messageBayPaintArea = new AxisAlignedBoxBounds(0, messageBayY, _windowSize.width, _messageBayHeight);
	}
	
	public static AxisAlignedBoxBounds getLeftFramePaintArea()
	{
		return _leftFramePaintArea;
	}
	
	public static AxisAlignedBoxBounds getRightFramePaintArea()
	{
		return _rightFramePaintArea;
	}
	
	public static AxisAlignedBoxBounds getFramePaintArea()
	{
		return _framePaintArea;
	}
	
	public static int getFramePaintAreaWidth()
	{
		if (!DISPLAYED_ABOVE_MINIMUM_FRAME_WIDTH) {
			return  MINIMUM_FRAME_WIDTH;
		}
		
		return _framePaintArea.getWidth();
	}
	
	public static int getFramePaintAreaHeight()
	{
		if (!DISPLAYED_ABOVE_MINIMUM_FRAME_WIDTH) {
			return  MINIMUM_FRAME_HEIGHT;
		}
		
		return _framePaintArea.getHeight();
	}
	
	public static Dimension getFramePaintAreaSize()
	{
		if (!DISPLAYED_ABOVE_MINIMUM_FRAME_WIDTH) {
			Dimension min_dim = new Dimension(MINIMUM_FRAME_WIDTH,MINIMUM_FRAME_HEIGHT);
			return min_dim;
		}
		
		return _framePaintArea.getSize();
	}
		
	public static AxisAlignedBoxBounds getMessageBayPaintArea()
	{
		return _messageBayPaintArea;
	}

	/**
	 * Checks that the item is visible (on current frame && overlays) - if
	 * visible then damaged area will be re-rendered on the next refresh.
	 * 
	 * @param damagedItem
	 * @param toRepaint
	 */
	public static void invalidateItem(Item damagedItem, Bounds toRepaint)
	{
		if (toRepaint == null) {
			return;
		}
		
		// Only add area to repaint if item is visible...
		if (ItemUtils.isVisible(damagedItem)) {
			invalidateArea(AxisAlignedBoxBounds.getEnclosing(toRepaint));
		} else if (!_mailMode && MessageBay.isMessageItem(damagedItem)) {
			invalidateArea(AxisAlignedBoxBounds.getEnclosing(toRepaint).translate(0, getMessageBayPaintArea().getMinY()));
		} else if (_mailMode && MailBay.isPreviewMailItem(damagedItem)) {
			invalidateArea(AxisAlignedBoxBounds.getEnclosing(toRepaint).translate(0, getMessageBayPaintArea().getMinY()));
		}
	}

	/**
	 * The given area will be re-rendered in the next refresh. This is the
	 * quicker version and is more useful for re-rendering animated areas.
	 */
	public static void invalidateArea(AxisAlignedBoxBounds toRepaint)
	{
		_damagedAreas.addArea(toRepaint);
	}

	public static void clearInvalidAreas()
	{
		_damagedAreas.clear();
	}
	
	public static void refreshBayArea() {
		// Always get the clip as it clears at the same time
		Clip clip = _damagedAreas.getClip();
		GraphicsManager g = EcosystemManager.getGraphicsManager();
		pushBayAreaUpdate(true, clip, g);
	}
	
	/**
	 * Redraws the entire window. Shouldn't be called directly, instead use
	 * requestRefresh(boolean) to ensure no infinite refresh call loops are created.
	 */
	private static boolean refresh(boolean useInvalidation)
	{
		Frame currentFrame = getCurrentFrame();
		if(currentFrame == null) {
			return false;
		}
		
		// Always get the clip as it clears at the same time
		Clip clip = _damagedAreas.getClip();
		
		// No damaged areas
		if (useInvalidation && clip.isFullyClipped()) {
			return true;
		}
				
		GraphicsManager g = EcosystemManager.getGraphicsManager();
		g.pushDrawingSurface(_refreshBuffer);
		
		if (isTwinFramesOn()) {
			Clip leftClip = null;
			Clip rightClip = null;
			
			if (useInvalidation) {
				leftClip = clip.clone().intersectWith(getLeftFramePaintArea());
				rightClip = clip.clone().intersectWith(getRightFramePaintArea());
				if (!rightClip.isFullyClipped()) {
					rightClip = new Clip(rightClip.getBounds().translate(-getRightFramePaintArea().getMinX(), 0));
				}
			}
			
			Image left = null;
			if (!useInvalidation || !leftClip.isFullyClipped()) {
				left = FrameGraphics.getFrameImage(getFrameOnSide(LEFT), leftClip, getLeftFramePaintArea().getSize());
			}
			
			Image right = null;
			if (!useInvalidation || !rightClip.isFullyClipped()) {
				right = FrameGraphics.getFrameImage(getFrameOnSide(RIGHT), rightClip, getRightFramePaintArea().getSize());
			}

			paintTwinFrames(left, right);
		} else {
			Clip frameClip = null;
			
			if (useInvalidation) {
				frameClip = clip.clone().intersectWith(getFramePaintArea());
			}
						
			Image image = null;
			if (currentFrame != null && (!useInvalidation || !frameClip.isFullyClipped())) {
				image = FrameGraphics.getFrameImage(currentFrame, frameClip, getFramePaintAreaSize());
			}

			paintSingleFrame(image);
		}

		pushBayAreaUpdate(useInvalidation, clip, g);
		
		// Draw any separator lines
		g.drawLine(getMessageBaySeparatorLine(), SEPARATOR_COLOUR, SEPARATOR_STROKE);
		g.drawLine(getTwinFramesSeparatorLine(), SEPARATOR_COLOUR, SEPARATOR_STROKE);
		
		// Paint any popups
		if (PopupManager.getInstance() != null) {
			PopupManager.getInstance().paint();
		}
		
		g.popDrawingSurface();
		g.drawImage(_refreshBuffer, Point.ORIGIN);
		return true;
	}

	private static void pushBayAreaUpdate(boolean useInvalidation, Clip clip, GraphicsManager g) {
		if (!isAudienceMode()) {
			if (!isMailMode()) {
				// Paint message bay
				paintMessageBay(useInvalidation, clip, g);
			} else {
				// Paint mail bay
				paintMailBay(useInvalidation, clip, g);
			}
		}
	}
	
	private static void paintMessageBay(boolean useInvalidation, Clip clip, GraphicsManager g) {
		Clip messageBayClip = null;
		
		AxisAlignedBoxBounds messageBayPaintArea = getMessageBayPaintArea();
		if (useInvalidation) {
			messageBayClip = clip.clone().intersectWith(messageBayPaintArea);
			if (!messageBayClip.isFullyClipped()) {
				messageBayClip = new Clip(messageBayClip.getBounds().translate(0, -messageBayPaintArea.getMinY()));
			}
		}
		
		Image image = null;
		if (!useInvalidation || !messageBayClip.isFullyClipped()) {
			image = MessageBay.getImage(messageBayClip, messageBayPaintArea.getSize());
		}
		
		if (image != null) {
			g.drawImage(image, messageBayPaintArea.getTopLeft(), messageBayPaintArea.getSize());
		}
	}
	
	private static void paintMailBay(boolean useInvalidation, Clip clip, GraphicsManager g) {
		Clip mailBayClip = null;
		
		AxisAlignedBoxBounds mailBayPaintArea = getMessageBayPaintArea();
		if (useInvalidation) {
			mailBayClip = clip.clone().intersectWith(mailBayPaintArea);
			if (!mailBayClip.isFullyClipped()) {
				mailBayClip = new Clip(mailBayClip.getBounds().translate(0, -mailBayPaintArea.getMinY()));
			}
		}
		
		Image image = null;
		if (!useInvalidation || !mailBayClip.isFullyClipped()) {
			image = MailBay.getImage(mailBayClip, mailBayPaintArea.getSize());
		}
		
		if (image != null) {
			g.drawImage(image, mailBayPaintArea.getTopLeft(), mailBayPaintArea.getSize());
		}
	}

	/** Draws the two frame images to the display and puts the separator line between them. */
	private static void paintTwinFrames(Image leftFrameImage, Image rightFrameImage)
	{
		if (leftFrameImage == null && rightFrameImage == null) {
			return;
		}
		
		InOutReference<FrameTransition> leftTransition = new InOutReference<FrameTransition>(getTransition(LEFT));
		InOutReference<FrameTransition> rightTransition = new InOutReference<FrameTransition>(getTransition(RIGHT));
		
		paintFrameIntoArea(leftFrameImage, getLeftFramePaintArea(), leftTransition);
		paintFrameIntoArea(rightFrameImage, getRightFramePaintArea(), rightTransition);
		
		setTransition(LEFT, leftTransition.get());
		setTransition(RIGHT, rightTransition.get());
	}
	
	/** Draws the single frame image to the screen. */
	private static void paintSingleFrame(Image frameImage)
	{
		if (frameImage == null) {
			return;
		}

		InOutReference<FrameTransition> transition = new InOutReference<FrameTransition>(getTransition(getCurrentSide()));
		
		paintFrameIntoArea(frameImage, getFramePaintArea(), transition);
		
		setTransition(getCurrentSide(), transition.get());
	}
	
	/** Draws the given frame image into the given area, using a transition if one is provided. */
	private static void paintFrameIntoArea(Image frameImage, AxisAlignedBoxBounds area, InOutReference<FrameTransition> transition)
	{
		if (frameImage == null || area == null) {
			return;
		}
		
		GraphicsManager g = EcosystemManager.getGraphicsManager();
		EnforcedClipKey key = g.pushClip(new Clip(area));
		
		FrameTransition t = null;
		if (transition != null) {
			t = transition.get();
		}
		
		// Attempt to draw the transition if there is one
		if (t != null) {
			if (!t.drawTransition(frameImage, area)) {
				// If drawing failed, throw the transition away
				t = null;
			} else {
				// Schedule the next frame to be drawn
				invalidateArea(area);
				requestRefresh(true);
			}
		}
		
		// If t == null at this stage, no transition has been drawn, so just draw the image
		if (t == null) {
			g.drawImage(frameImage, area.getTopLeft(), area.getSize());
		}
		
		// Discard the transition if drawing failed or it is finished
		if (t == null || t.isCompleted()) {
			transition.set(null);
		}
		
		g.popClip(key);
	}

	/** Runnable which ensures overlapping refresh requests are joined. */
	private static RenderRequestMarsheller _requestMarsheller = new RenderRequestMarsheller();
	
	/**
	 * If wanting to refresh from another thread - other than the main thread
	 * that handles the expeditee datamodel (modifying / accessing / rendering).
	 * Use this method for thread safety.
	 */
	public static synchronized void requestRefresh(boolean useInvalidation)	{
		requestRefresh(useInvalidation, null);
	}
	
	public static synchronized void requestRefresh(final boolean useInvalidation, final BooleanSupplier callback) {
		try {
			_requestMarsheller.enqueue(useInvalidation, callback);
		} catch (Throwable e) {
			e.printStackTrace();
		}
	}

	/**
	 * Used for marshelling render requests from foreign threads to the event
	 * dispatcher thread... (AWT)
	 * 
	 * @author Brook Novak
	 */
	private static class RenderRequestMarsheller implements Runnable {

		private boolean _useInvalidation = true;
		private boolean _enqueued = false;
		private Boolean _requeueWithInvalidation = null;
		private Object _lock = new Object();
		private List<BooleanSupplier> callbacks = new LinkedList<BooleanSupplier>();
		
		/** Enqueues a redraw on the GIO thread, or remembers to do so once the current redraw finishes. */
		public void enqueue(final boolean useInvalidation, final BooleanSupplier callback)
		{
			synchronized(callbacks) {
				if(callback != null) {
					callbacks.add(callback);
				}
			}
			synchronized (_lock) {
				if (!_enqueued) {
					_enqueued = true;
					_useInvalidation = useInvalidation;
					EcosystemManager.getMiscManager().runOnGIOThread(this);
				} else if (_requeueWithInvalidation == null || _requeueWithInvalidation == true) {
					_requeueWithInvalidation = useInvalidation;
				}
			}
		}

		@Override
		public void run()
		{
			try {
				if(refresh(_useInvalidation)) {
					synchronized (callbacks) {
						callbacks.forEach(cb -> cb.getAsBoolean());
						callbacks.clear();
					}
				}
			} catch (Throwable e) {
				e.printStackTrace();
			}

			// Do another redraw if we received a new request while doing this one.
			synchronized (_lock) {
				if (_requeueWithInvalidation != null) {
					_useInvalidation = _requeueWithInvalidation.booleanValue();
					_requeueWithInvalidation = null;
					EcosystemManager.getMiscManager().runOnGIOThread(this);
				} else {
					_enqueued = false;
				}
			}
		}
	}
}