001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.openide.windows;
043:
044: import java.io.InputStreamReader;
045: import java.io.OutputStreamWriter;
046: import java.io.Reader;
047: import org.openide.util.io.NullOutputStream;
048: import org.openide.util.io.NullInputStream;
049:
050: /** An I/O connection to one tab on the Output Window. To acquire an instance
051: * to write to, call, e.g.,
052: * <code>IOProvider.getDefault().getInputOutput("someName", false)</code>.
053: * To get actual streams to write to, call <code>getOut()</code> or <code>
054: * getErr()</code> on the returned instance.
055: * <p>
056: * Generally it is preferable not to hold a reference to an instance of
057: * {@link org.openide.windows.InputOutput}, but rather to fetch it by name from {@link org.openide.windows.IOProvider} as
058: * needed.<p>
059: * <b>Note:</b> For historical reasons, the mechanism to clear an output tab
060: * is via the method {@link org.openide.windows.OutputWriter#reset}, though it would have
061: * made more sense implemented here.
062: *
063: * @see OutputWriter
064: * @author Ian Formanek, Jaroslav Tulach, Petr Hamernik, Ales Novak, Jan Jancura
065: */
066: public interface InputOutput {
067:
068: /** Null InputOutput */
069: /*public static final*/InputOutput NULL = new InputOutput$Null();
070:
071: /** Acquire an output writer to write to the tab.
072: * This is the usual use of a tab--it writes to the main output pane.
073: * @return the writer
074: */
075: public OutputWriter getOut();
076:
077: /** Get a reader to read from the tab.
078: * If a reader is ever requested, an input line is added to the
079: * tab and used to read one line at a time.
080: * @return the reader
081: */
082: public Reader getIn();
083:
084: /** Get an output writer to write to the tab in error mode.
085: * This might show up in a different color than the regular output, e.g., or
086: * appear in a separate pane.
087: * @return the writer
088: */
089: public OutputWriter getErr();
090:
091: /** Closes this tab. The effect of calling any method on an instance
092: * of InputOutput after calling <code>closeInputOutput()</code> on it is undefined.
093: */
094: public void closeInputOutput();
095:
096: /** Test whether this tab has been closed, either by a call to <code>closeInputOutput()</code>
097: * or by the user closing the tab in the UI.
098: *
099: * @see #closeInputOutput
100: * @return <code>true</code> if it is closed
101: */
102: public boolean isClosed();
103:
104: /** Show or hide the standard output pane, if separated. Does nothing in either
105: * of the available implementations of this API.
106: * @param value <code>true</code> to show, <code>false</code> to hide
107: */
108: public void setOutputVisible(boolean value);
109:
110: /** Show or hide the error pane, if separated. Does nothing in either
111: * of the available implementations of this API.
112: * @param value <code>true</code> to show, <code>false</code> to hide
113: */
114: public void setErrVisible(boolean value);
115:
116: /** Show or hide the input line.
117: * @param value <code>true</code> to show, <code>false</code> to hide
118: */
119: public void setInputVisible(boolean value);
120:
121: /**
122: * Ensure this pane is visible.
123: */
124: public void select();
125:
126: /** Test whether the error output is mixed into the regular output or not.
127: * Always true for both available implementations of this API.
128: * @return <code>true</code> if separate, <code>false</code> if mixed in
129: */
130: public boolean isErrSeparated();
131:
132: /** Set whether the error output should be mixed into the regular output or not.
133: * Note that this method is optional and is not supported by either of the
134: * current implementations of InputOutput (core/output and core/output2).
135: * @param value <code>true</code> to separate, <code>false</code> to mix in
136: */
137: public void setErrSeparated(boolean value);
138:
139: /** Test whether the output window takes focus when anything is written to it.
140: * @return <code>true</code> if any write to the tab should cause it to gain
141: * keyboard focus <strong>(not recommended)</strong>
142: */
143: public boolean isFocusTaken();
144:
145: /** Set whether the output window should take focus when anything is written to it.
146: * <strong>Note that this really means the output window will steal keyboard
147: * focus whenever a line of output is written. This is generally an extremely
148: * bad idea and strongly recommended against by most UI guidelines.</strong>
149: * @param value <code>true</code> to take focus
150: */
151: public void setFocusTaken(boolean value);
152:
153: /** Flush pending data in the input-line's reader.
154: * Called when the reader is about to be reused.
155: * @return the flushed reader
156: * @deprecated meaningless, does nothing
157: */
158: public Reader flushReader();
159:
160: /** @deprecated Use {@link #NULL} instead. */
161: /*public static final*/Reader nullReader = new InputStreamReader(
162: new NullInputStream());
163:
164: /** @deprecated Use {@link #NULL} instead. */
165: /*public static final*/OutputWriter nullWriter = new InputOutput$NullOutputWriter();
166:
167: }
168:
169: final class InputOutput$Null extends Object implements InputOutput {
170: public InputOutput$Null() {
171: }
172:
173: public OutputWriter getOut() {
174: return nullWriter;
175: }
176:
177: public Reader getIn() {
178: return nullReader;
179: }
180:
181: public OutputWriter getErr() {
182: return nullWriter;
183: }
184:
185: public void closeInputOutput() {
186: }
187:
188: public boolean isClosed() {
189: return true;
190: }
191:
192: public void setOutputVisible(boolean value) {
193: }
194:
195: public void setErrVisible(boolean value) {
196: }
197:
198: public void setInputVisible(boolean value) {
199: }
200:
201: public void select() {
202: }
203:
204: public boolean isErrSeparated() {
205: return false;
206: }
207:
208: public void setErrSeparated(boolean value) {
209: }
210:
211: public boolean isFocusTaken() {
212: return false;
213: }
214:
215: public void setFocusTaken(boolean value) {
216: }
217:
218: public Reader flushReader() {
219: return nullReader;
220: }
221: }
222:
223: final class InputOutput$NullOutputWriter extends OutputWriter {
224: InputOutput$NullOutputWriter() {
225: super (new OutputStreamWriter(new NullOutputStream()));
226: }
227:
228: public void reset() {
229: }
230:
231: public void println(String s, OutputListener l) {
232: }
233: }
|