| /******************************************************************************* |
| * Copyright (c) 2007, 2009 Wind River Systems, Inc. and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Michael Scharf (Wind River) - initial API and implementation |
| * Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend |
| *******************************************************************************/ |
| package com.google.eclipse.elt.emulator.model; |
| |
| /** |
| * Maintains a snapshot of an instance of {@link ITerminalTextData}. While the {@link ITerminalTextData} continues |
| * changing, the snapshot remains unchanged until the next snapshot is taken by calling |
| * {@link #updateSnapshot(boolean)}. This is important, because the {@link ITerminalTextData} might get modified by |
| * another thread. |
| */ |
| public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly { |
| /** |
| * This listener gets called when the current snapshot is out of date. Calling |
| * {@link ITerminalTextDataSnapshot#updateSnapshot(boolean)} will have an effect. Once the |
| * {@link #snapshotOutOfDate(ITerminalTextDataSnapshot)} method is called, it will not be called until |
| * {@link ITerminalTextDataSnapshot#updateSnapshot(boolean)} is called and a new snapshot needs to be updated again. |
| */ |
| interface SnapshotOutOfDateListener { |
| /** |
| * Gets called when the snapshot is out of date. To get the snapshot up to date, call |
| * {@link ITerminalTextDataSnapshot#updateSnapshot(boolean)}. |
| * |
| * @param snapshot The snapshot that is out of date. |
| */ |
| void snapshotOutOfDate(ITerminalTextDataSnapshot snapshot); |
| } |
| |
| void addListener(SnapshotOutOfDateListener listener); |
| |
| void removeListener(SnapshotOutOfDateListener listener); |
| |
| /** |
| * Ends the listening to the {@link ITerminalTextData}. After this has been called no new snapshot data is collected. |
| */ |
| void detach(); |
| |
| boolean isOutOfDate(); |
| |
| /** |
| * The window of interest is the region the snapshot should track. Changes outside this region are ignored. The change |
| * takes effect after an update. |
| * @param startLine -1 means track the end of the data. |
| * @param size number of lines to track. A size of -1 means track all. |
| */ |
| void setInterestWindow(int startLine, int size); |
| |
| int getInterestWindowStartLine(); |
| |
| int getInterestWindowSize(); |
| |
| /** |
| * Create a new snapshot of the {@link ITerminalTextData}. It will efficiently copy the data of the |
| * {@link ITerminalTextData} into an internal representation. The snapshot also keeps track of the changes since the |
| * previous snapshot. |
| * <p> |
| * With the methods {@link #getFirstChangedLine()}, {@link #getLastChangedLine()} and {@link #hasLineChanged(int)} you |
| * can find out what has changed in the current snapshot since the previous snapshot. |
| * </p> |
| * <p> |
| * If {@code detectScrolling} is {@code true} the information about scrolling can be retrieved using the following methods: |
| * {@link #getScrollWindowStartLine()}, {@link #getScrollWindowSize()} and {@link #getScrollWindowShift()}. |
| * </p> |
| * <p> |
| * <b>Note:</b> The method {@link #hasLineChanged(int)} returns changes <b>after</b> the scrolling has been applied. |
| * </p> |
| * |
| * @param detectScrolling indicates whether the snapshot should try to identify scroll changes since the last |
| * snapshot. |
| */ |
| void updateSnapshot(boolean detectScrolling); |
| |
| /** |
| * Returns the first line changed in this snapshot compared to the previous snapshot. |
| * <p> |
| * <b>Note:</b> If no line has changed, this returns {@link Integer#MAX_VALUE}. |
| * <p> |
| * <b>Note:</b> if {@link #updateSnapshot(boolean)} has been called with <code>true</code>, then this does not include |
| * lines that only have been scrolled. This is the first line that has changed <b>after</b> the scroll has been |
| * applied. |
| * |
| * @return the first line changed in this snapshot compared to the previous snapshot. |
| */ |
| int getFirstChangedLine(); |
| |
| /** |
| * Returns the last line changed in this snapshot compared to the previous snapshot. If the height has changed since |
| * the last update of the snapshot, then the returned value is within the new dimensions. |
| * <p> |
| * <b>Note:</b> If no line has changed, this returns <code>-1</code> |
| * <p> |
| * <b>Note:</b> if {@link #updateSnapshot(boolean)} has been called with <code>true</code>, then this does not include |
| * lines that only have been scrolled. This is the last line that has changed <b>after</b> the scroll has been |
| * applied. |
| * <p> |
| * A typical for loop using this method would look like this (note the <code><=</code> in the for loop): |
| * <pre> |
| * for (int line = snap.{@link #getFirstChangedLine()}; line <b><=</b> snap.getLastChangedLine(); line++) |
| * if(snap.{@link #hasLineChanged(int) hasLineChanged(line)}) |
| * doSomething(line); |
| * </pre> |
| * @return the last line changed in this snapshot compared to the previous snapshot. |
| */ |
| int getLastChangedLine(); |
| |
| boolean hasLineChanged(int line); |
| |
| boolean hasDimensionsChanged(); |
| |
| boolean hasTerminalChanged(); |
| |
| /** |
| * If {@link #updateSnapshot(boolean)} was called with {@code true}, then this method returns the top of the scroll |
| * region. |
| * |
| * @return The first line scrolled in this snapshot compared to the previous snapshot. |
| * |
| * @see ITerminalTextData#scroll(int, int, int) |
| */ |
| int getScrollWindowStartLine(); |
| |
| /** |
| * If {@link #updateSnapshot(boolean)} was called with {@code true}, then this method returns the size of the scroll |
| * region. If nothing has changed, 0 is returned. |
| * |
| * @return The number of lines scrolled in this snapshot compared to the previous snapshot. |
| * |
| * @see ITerminalTextData#scroll(int, int, int) |
| */ |
| int getScrollWindowSize(); |
| |
| /** |
| * If {@link #updateSnapshot(boolean)} was called with {@code true}, then this method returns number of lines moved by |
| * the scroll region. |
| * |
| * @return The the scroll shift of this snapshot compared to the previous snapshot. |
| * |
| * @see ITerminalTextData#scroll(int, int, int) |
| */ |
| int getScrollWindowShift(); |
| |
| ITerminalTextData getTerminalTextData(); |
| } |