mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-06-09 02:36:01 +02:00
Code Issues Wiki Activity

[261486][api][cleanup] Mark @noimplement interfaces as @noextend

Browse source
This commit is contained in:
Martin Oberhuber 2009-01-19 14:05:25 +00:00
parent a9a9a085ea
commit 489e43c538
5 changed files with 73 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalConnector.java
View file

@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2006, 2008 Wind River Systems, Inc. and others.
* Copyright (c) 2006, 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
@ -8,6 +8,7 @@
* Contributors:
* Michael Scharf (Wind River) - initial API and implementation
* Martin Oberhuber (Wind River) - fixed copyright headers and beautified
* Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend
*******************************************************************************/
package org.eclipse.tm.internal.terminal.provisional.api;
@ -17,15 +18,14 @@ import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.tm.internal.terminal.control.ITerminalViewControl;
import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnectorImpl;
/**
* A contributed connection type to manage a single connection.
*
* Implementations of this class are contributed through the
* <code>org.eclipse.tm.terminal.terminalConnectors</code> extension point.
* This class gives access to the static markup of a terminal connector
* extension as well as providing the lifecycle management for the dynamically
* loaded {@link TerminalConnectorImpl} instance, which performs the actual
* <code>org.eclipse.tm.terminal.terminalConnectors</code> extension point. This
* class gives access to the static markup of a terminal connector extension as
* well as providing the lifecycle management for the dynamically loaded
* {@link TerminalConnectorImpl} instance, which performs the actual
* communications. This pattern allows for lazy initialization, bundle
* activation and class loading of the actual {@link TerminalConnectorImpl}
* instance.
@ -36,13 +36,14 @@ import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnect
* active terminal widget.
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*
* @author Michael Scharf
* <p>
* <strong>EXPERIMENTAL</strong>. 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 <a
* <strong>EXPERIMENTAL</strong>. 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 <a
* href="http://www.eclipse.org/dsdp/tm/">Target Management</a> team.
* </p>
*/
@ -128,7 +129,7 @@ public interface ITerminalConnector extends IAdaptable {
* FIXME should not have UI related stuff in ITerminalConnector, since
* connectors may be totally programmatic and UI-less. Better make the
* connector adapt to an interface that controls the UI aspect.
*
*
* @return a new page that can be used in a dialog to setup this connection.
* The dialog should persist its settings with the
* {@link #load(ISettingsStore)} and {@link #save(ISettingsStore)}

15
org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java
View file

@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2006, 2008 Wind River Systems, Inc. and others.
* Copyright (c) 2006, 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
@ -9,6 +9,7 @@
* Michael Scharf (Wind River) - initial API and implementation
* Martin Oberhuber (Wind River) - fixed copyright headers and beautified
* Martin Oberhuber (Wind River) - [204796] Terminal should allow setting the encoding to use
* Martin Oberhuber (Wind River) - [261486][api][cleanup] Mark @noimplement interfaces as @noextend
*******************************************************************************/
package org.eclipse.tm.internal.terminal.provisional.api;
@ -20,15 +21,15 @@ import org.eclipse.swt.widgets.Shell;
/**
* Represents the terminal view as seen by a terminal connection.
* <p>
* <strong>EXPERIMENTAL</strong>. 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 <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a>
* team.
* <strong>EXPERIMENTAL</strong>. 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 <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a> team.
* </p>
*
* @author Michael Scharf
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ITerminalControl {
@ -79,7 +80,7 @@ public interface ITerminalControl {
* setEncoding() call failed and the fallback default encoding should be
* queried, such that e.g. a combobox with encodings to choose can be
* properly initialized.
*
*
* @return the current Encoding of the Terminal.
* @since org.eclipse.tm.terminal 2.0
*/

18
org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java
View file

@ -1,24 +1,26 @@
/*******************************************************************************
* Copyright (c) 2007, 2008 Wind River Systems, Inc. and others.
* 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 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
* 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.
* <p>
* <b>Note: </b> Implementations of this interface has to be thread safe.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ITerminalTextData extends ITerminalTextDataReadOnly {
@ -95,7 +97,7 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* 3 dddd
* 4 eeee
* </pre>
*
*
* Shift a region of 3 lines <b>up</b> by one line <code>shift(1,3,-1)</code>
* <pre>
* 0 aaaa
@ -104,8 +106,8 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* 3
* 4 eeee
* </pre>
*
*
*
*
* Shift a region of 3 lines <b>down</b> by one line <code>shift(1,3,1)</code>
* <pre>
* 0 aaaa

24
org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataReadOnly.java
View file

@ -1,16 +1,20 @@
/*******************************************************************************
* 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
*
* Contributors:
* 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 org.eclipse.tm.terminal.model;
/**
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ITerminalTextDataReadOnly {
/**
@ -50,14 +54,14 @@ public interface ITerminalTextDataReadOnly {
* can be used to track changes. Make sure to call {@link ITerminalTextDataSnapshot#detach()}
* if you don't need the snapshots anymore.
* <p><b>Note: </b>A new snapshot is empty and needs a call to {@link ITerminalTextDataSnapshot#updateSnapshot(boolean)} to
* get its initial values. You might want to setup the snapshot to your needs by calling
* get its initial values. You might want to setup the snapshot to your needs by calling
* {@link ITerminalTextDataSnapshot#setInterestWindow(int, int)}.
* </p>
* @return a new instance of {@link ITerminalTextDataSnapshot} that "listens" to changes of
* <code>this</code>.
*/
public ITerminalTextDataSnapshot makeSnapshot();
char[] getChars(int line);
Style[] getStyles(int line);

55
org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
View file

@ -1,12 +1,13 @@
/*******************************************************************************
* Copyright (c) 2007, 2008 Wind River Systems, Inc. and others.
* 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 org.eclipse.tm.terminal.model;
@ -18,32 +19,32 @@ package org.eclipse.tm.terminal.model;
* {@link ITerminalTextData} might get modified by another thread. Suppose you
* would want to draw the content of the {@link ITerminalTextData} using the
* following loop:
*
*
* <pre>
* for (int line = 0; line &lt; term.getHeight(); line++)
* for (int column = 0; column &lt; term.getWidth(); column++)
* drawCharacter(column, line, term.getChar(column, line), term.getStyle(column, line));
* </pre>
*
*
* 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 <code>synchronized(term){}</code> statement around the code.
* This has two problems: 1. you would have to know about the internals of the
* be to put a <code>synchronized(term){}</code> 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.
* <p>
* <b>Solution:</b> 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.
* <b>Solution:</b> 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.
* </p>
*
*
* <p>
* <b>Drawing optimization</b>: To optimize redrawing of changed lines, this
* class keeps track of lines that have changed since the previous snapshot.
* </p>
*
*
* <pre>
* // iterate over the potentially changed lines
* for (int line = snap.getFirstChangedLine(); line &lt;= snap.getLastChangedLine(); line++)
@ -52,16 +53,16 @@ package org.eclipse.tm.terminal.model;
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
*
*
* <p>
* <b>Scroll optimization:</b> 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 <code>true</code> for
* the <code>detectScrolling</code> parameter. The object will keep track of
* <b>Scroll optimization:</b> 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 <code>true</code> for the
* <code>detectScrolling</code> parameter. The object will keep track of
* scrolling. The UI must <b>first</b> handle the scrolling and then use the
* {@link #hasLineChanged(int)} method to determine scrolling:
*
*
* <pre>
* // scroll the visible region of the UI &lt;b&gt;before&lt;/b&gt; drawing the changed lines.
* doUIScrolling(snap.getScrollChangeY(), snap.getScrollChangeN(), snap.getScrollChangeShift());
@ -72,14 +73,16 @@ package org.eclipse.tm.terminal.model;
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
*
* </p>
* <p>
* <b>Threading Note</b>: 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()}.
* </p>
*
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
/**
@ -92,7 +95,7 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
* A typical terminal view would not update the snapshot immediately
* 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.
*
*
* <p>Make sure you don't spend too much time in this method.
*/
interface SnapshotOutOfDateListener {
@ -146,10 +149,10 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
/**
* @return 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.
@ -161,13 +164,13 @@ public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
* 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>&lt;=</code> in the for loop):
* <pre>
* for(int line=snap.{@link #getFirstChangedLine()}; line <b>&lt;=</b> snap.getLastChangedLine(); line++)