From 0f05234334d8959ed30f1918f8742f2e22b4101c Mon Sep 17 00:00:00 2001 From: Martin Oberhuber Date: Fri, 28 Mar 2008 14:27:50 +0000 Subject: [PATCH] [cleanup] Add @noimplement and similar API Tools Javadoc Markup --- .../tm/internal/terminal/view/PageBook.java | 10 +- .../provisional/api/ITerminalControl.java | 31 ++-- .../tm/terminal/model/ITerminalTextData.java | 65 ++++---- .../model/ITerminalTextDataSnapshot.java | 143 ++++++++++-------- 4 files changed, 130 insertions(+), 119 deletions(-) diff --git a/org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java b/org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java index ffe91a38110..abb3283b825 100644 --- a/org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java +++ b/org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java @@ -15,12 +15,10 @@ import org.eclipse.swt.widgets.Composite; import org.eclipse.swt.widgets.Control; /** - * A pagebook is a composite control where only a single control is visible - * at a time. It is similar to a notebook, but without tabs. - *

- * This class may be instantiated; it is not intended to be subclassed. - *

- * + * A pagebook is a composite control where only a single control is visible at a + * time. It is similar to a notebook, but without tabs. + * + * @noextend This class is not intended to be subclassed by clients. */ public class PageBook extends Composite { private StackLayout fLayout; diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java index 47acc769119..86b009e259c 100644 --- a/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java +++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java @@ -1,11 +1,11 @@ /******************************************************************************* * Copyright (c) 2006, 2007 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 + * 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: + * Contributors: * Michael Scharf (Wind River) - initial API and implementation * Martin Oberhuber (Wind River) - fixed copyright headers and beautified *******************************************************************************/ @@ -17,18 +17,19 @@ import org.eclipse.swt.widgets.Shell; /** * Represents the terminal view as seen by a terminal connection. - * - *

Not to be implemented by clients. - * @author Michael Scharf *

* EXPERIMENTAL. This class or interface has been added as - * part of a work in progress. There is no guarantee that this API will - * work or that it will remain the same. Please do not use this API without - * consulting with the Target Management team. + * part of a work in progress. There is no guarantee that this API will work or + * that it will remain the same. Please do not use this API without consulting + * with the Target Management + * team. *

+ * + * @author Michael Scharf + * @noimplement This interface is not intended to be implemented by clients. */ public interface ITerminalControl { - + /** * @return the current state of the connection */ @@ -38,7 +39,7 @@ public interface ITerminalControl { * @param state */ void setState(TerminalState state); - + /** * A shell to show dialogs. * @return the shell in which the terminal is shown. @@ -48,7 +49,7 @@ public interface ITerminalControl { /** * Show a text in the terminal. If puts newlines at the beginning and the end. * @param text - * TODO: Michael Scharf: Is this really needed? + * TODO: Michael Scharf: Is this really needed? */ void displayTextInTerminal(String text); @@ -71,5 +72,5 @@ public interface ITerminalControl { * TODO: Michael Scharf: Should be replaced by a better error notification mechanism! */ void setMsg(String msg); - + } diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java index f3359e10fb4..23eeac5716f 100644 --- a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java +++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java @@ -1,23 +1,24 @@ /******************************************************************************* * Copyright (c) 2007 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 + * 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: + * Contributors: * Michael Scharf (Wind River) - initial API and implementation *******************************************************************************/ package org.eclipse.tm.terminal.model; /** - * A writable matrix of characters and {@link Style}. This is intended to be the - * low level representation of the text of a Terminal. Higher layers are responsible - * to fill the text and styles into this representation. - * - *

Note: Implementations of this interface has to be thread safe. - *

Note: This interface is not intended to be implemented by clients. + * A writable matrix of characters and {@link Style}. This is intended to be + * the low level representation of the text of a Terminal. Higher layers are + * responsible to fill the text and styles into this representation. + *

+ * Note: Implementations of this interface has to be thread safe. + *

+ * @noimplement This interface is not intended to be implemented by clients. */ public interface ITerminalTextData extends ITerminalTextDataReadOnly { @@ -61,30 +62,30 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly { * @param style the style or null */ void setChars(int line, int column, char[] chars, int start, int len, Style style); - + /** * Cleans the entire line. * @param line */ void cleanLine(int line); -// /** -// * @param line -// * @return true if this line belongs to the previous line but is simply -// * wrapped. -// */ -// boolean isWrappedLine(int line); -// -// /** -// * Makes this line an extension to the previous line. Wrapped lines get folded back -// * when the width of the terminal changes -// * @param line -// * @param extendsPreviousLine -// */ -// void setWrappedLine(int line, boolean extendsPreviousLine); - + // /** + // * @param line + // * @return true if this line belongs to the previous line but is simply + // * wrapped. + // */ + // boolean isWrappedLine(int line); + // + // /** + // * Makes this line an extension to the previous line. Wrapped lines get folded back + // * when the width of the terminal changes + // * @param line + // * @param extendsPreviousLine + // */ + // void setWrappedLine(int line, boolean extendsPreviousLine); + /** - * Shifts some lines up or down. The "empty" space is filled with '\000' chars + * Shifts some lines up or down. The "empty" space is filled with '\000' chars * and null {@link Style} *

To illustrate shift, here is some sample data: * 

@@ -100,7 +101,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
 	 * 0 aaaa
 	 * 1 cccc
 	 * 2 dddd
-	 * 3 
+	 * 3
 	 * 4 eeee
 	 *
* @@ -108,7 +109,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly { * Shift a region of 3 lines down by one line shift(1,3,1) * 
 	 * 0 aaaa
-	 * 1 
+	 * 1
 	 * 2 bbbb
 	 * 3 cccc
 	 * 4 eeee
@@ -119,7 +120,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
 	 * Negative number means scroll down, positive scroll up (see example above).
 	 */
 	void scroll(int startLine, int size, int shift);
-	
+
 	/**Adds a new line to the terminal. If maxHeigth is reached, the entire terminal
 	 * will be scrolled. Else a line will be added.
 	 */
@@ -145,7 +146,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
 	 * @param length
 	 */
 	void copyRange(ITerminalTextData source, int sourceStartLine, int destStartLine,int length);
-	
+
 	void setCursorLine(int line);
 	void setCursorColumn(int column);
 }
\ No newline at end of file
diff --git a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
index 7d4065e7581..652e1041407 100644
--- a/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
+++ b/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
@@ -1,11 +1,11 @@
 /*******************************************************************************
  * Copyright (c) 2007 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 
+ * 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: 
+ * Contributors:
  * Michael Scharf (Wind River) - initial API and implementation
  *******************************************************************************/
 package org.eclipse.tm.terminal.model;
@@ -13,62 +13,73 @@ package org.eclipse.tm.terminal.model;
 /**
  * This class 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. Suppose you would want to draw the content of
- * the {@link ITerminalTextData} using the following loop:
+ * 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. Suppose you
+ * would want to draw the content of the {@link ITerminalTextData} using the
+ * following loop:
+ * 
  * 
- * for(int line=0;line<term.getHeight();line++) 
- *     for(int column=0; column<term.getWidth();column++)
- *         drawCharacter(column,line,term.getChar(column,line),term.getStyle(column,line));
+ * for (int line = 0; line < term.getHeight(); line++)
+ * 	for (int column = 0; column < term.getWidth(); column++)
+ * 		drawCharacter(column, line, term.getChar(column, line), term.getStyle(column, line));
  * 

- * This might fail because the background thread could change the dimensions of the 
- * {@link ITerminalTextData} while you iterate the loop. One solution would be to
- * put a synchronized(term){} statement around the code. This has 
- * two problems: 1. you would have to know about the internals of the synchronisation
- * of {@link ITerminalTextData}. 2. The other thread that changes {@link ITerminalTextData}
- * is blocked while the potentially slow drawing is done.
+ * 
+ * This might fail because the background thread could change the dimensions of
+ * the {@link ITerminalTextData} while you iterate the loop. One solution would
+ * be to put a synchronized(term){} statement around the code.
+ * This has two problems: 1. you would have to know about the internals of the
+ * synchronisation of {@link ITerminalTextData}. 2. The other thread that
+ * changes {@link ITerminalTextData} is blocked while the potentially slow
+ * drawing is done.
  * 

- * Solution: Take a snapshot of the terminal and use the snapshot to draw
- * the content. There is no danger that the data structure get changed while
- * you draw. There are also methods to find out what has changed to minimize
- * the number of lines that get redrawn.

- * 
- * 
Drawing optimization: To optimize redrawing of changed lines, this class keeps
- * track of lines that have changed since the previous snapshot.

- * 
- * 
- * // iterate over the potentially changed lines
- * for(int line=snap.getFirstChangedLine();line<=snap.getLastChangedLine();line++) 
- *     // redraw only if the line has changed
- *     if(snap.hasLineChanged(line))
- *         for(int column=0; column<snap.getWidth();column++)
- *            drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
- * 

- * 
- * 
Scroll optimization: Often new lines are appended at the bottom of the
- * terminal and the rest of the lines are scrolled up. In this case all lines would be 
- * marked as changed. To optimize for this
- * case, {@link #updateSnapshot(boolean)} can be called with true for
- * the detectScrolling parameter. The object will keep track of scrolling. 
- * The UI must first handle the scrolling and then use the {@link #hasLineChanged(int)}
- * method to determine scrolling:
- * 
- * // scroll the visible region of the UI before drawing the changed lines.
- * doUIScrolling(snap.getScrollChangeY(),snap.getScrollChangeN(),snap.getScrollChangeShift());
- * // iterate over the potentially changed lines
- * for(int line=snap.getFirstChangedLine();line<=snap.getFirstChangedLine();line++) 
- *     // redraw only if the line has changed
- *     if(snap.hasLineChanged(line))
- *         for(int column=0; column<snap.getWidth();column++)
- *            drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
- * 

+ * Solution: Take a snapshot of the terminal and use the snapshot to
+ * draw the content. There is no danger that the data structure get changed
+ * while you draw. There are also methods to find out what has changed to
+ * minimize the number of lines that get redrawn.
  * 

  * 
- * 
Note: This interface is not intended to be implemented by clients.

- * 
Threading Note: This class is not thread save! All methods have to be called by 
- * the a same thread, that created the instance by calling 
- * {@link ITerminalTextDataReadOnly#makeSnapshot()}. 

+ * 

+ * Drawing optimization: To optimize redrawing of changed lines, this
+ * class keeps track of lines that have changed since the previous snapshot.
+ * 

+ * 
+ * 
+ * // iterate over the potentially changed lines
+ * for (int line = snap.getFirstChangedLine(); line <= snap.getLastChangedLine(); line++)
+ * 	// redraw only if the line has changed
+ * 	if (snap.hasLineChanged(line))
+ * 		for (int column = 0; column < snap.getWidth(); column++)
+ * 			drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
+ * 

+ * 
+ * 

+ * Scroll optimization: Often new lines are appended at the bottom of
+ * the terminal and the rest of the lines are scrolled up. In this case all
+ * lines would be marked as changed. To optimize for this case,
+ * {@link #updateSnapshot(boolean)} can be called with true for
+ * the detectScrolling parameter. The object will keep track of
+ * scrolling. The UI must first handle the scrolling and then use the
+ * {@link #hasLineChanged(int)} method to determine scrolling:
+ * 
+ * 
+ * // scroll the visible region of the UI <b>before</b> drawing the changed lines.
+ * doUIScrolling(snap.getScrollChangeY(), snap.getScrollChangeN(), snap.getScrollChangeShift());
+ * // iterate over the potentially changed lines
+ * for (int line = snap.getFirstChangedLine(); line <= snap.getFirstChangedLine(); line++)
+ * 	// redraw only if the line has changed
+ * 	if (snap.hasLineChanged(line))
+ * 		for (int column = 0; column < snap.getWidth(); column++)
+ * 			drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
+ * 

+ * 

+ * 

+ * Threading Note: This class is not thread safe! All methods have to be
+ * called by the a same thread, that created the instance by calling
+ * {@link ITerminalTextDataReadOnly#makeSnapshot()}.
+ * 

+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	/**
@@ -79,7 +90,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	 * is called and a new snapshot needs to be updated again.
 	 * 

 	 * A typical terminal view would not update the snapshot immediately
-	 * after the {@link #snapshotOutOfDate(ITerminalTextDataSnapshot)} has been called. It would introduce a 
+	 * after the {@link #snapshotOutOfDate(ITerminalTextDataSnapshot)} has been called. It would introduce a
 	 * delay to update the UI (and the snapshot} 10 or 20 times per second.
 	 * 
 	 * 
Make sure you don't spend too much time in this method.
@@ -94,7 +105,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	}
 	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.
@@ -115,11 +126,11 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	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. 
+	 * The snapshot also keeps track of the changes since the previous snapshot.
 	 * 
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.
@@ -134,9 +145,9 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 
 	/**
 	 * @return The first line changed in this snapshot compared
-	 * to the previous snapshot. 
+	 * to the previous snapshot.
 	 * 
-	 * 
Note: If no line has changed, this 
+	 * 
Note: If no line has changed, this
 	 * returns {@link Integer#MAX_VALUE}
 	 * 
 	 * 
Note: if {@link #updateSnapshot(boolean)} has been called with true,
@@ -171,11 +182,11 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	 * @return true if the line has changed since the previous snapshot
 	 */
 	boolean hasLineChanged(int line);
-	
+
 	boolean hasDimensionsChanged();
-	
+
 	/**
-	 * @return true if the terminal has changed (and not just the 
+	 * @return true if the terminal has changed (and not just the
 	 * window of interest)
 	 */
 	boolean hasTerminalChanged();
@@ -203,7 +214,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
 	 * to the previous snapshot. See also {@link ITerminalTextData#scroll(int, int, int)}
 	 */
 	int getScrollWindowShift();
-	
+
 	/**
 	 * @return The {@link ITerminalTextData} on that this instance is observing.
 	 */