1 /*

     2  * Copyright (c) 2002-2018, the original author or authors.

     3  *

     4  * This software is distributable under the BSD license. See the terms of the

     5  * BSD license in the documentation provided with this software.

     6  *

     7  * http://www.opensource.org/licenses/bsd-license.php

     8  */

     9 package jdk.internal.org.jline.terminal;

    10 

    11 import java.io.Closeable;

    12 import java.io.Flushable;

    13 import java.io.InputStream;

    14 import java.io.OutputStream;

    15 import java.io.PrintWriter;

    16 import java.nio.charset.Charset;

    17 import java.util.function.IntConsumer;

    18 import java.util.function.IntSupplier;

    19 

    20 import jdk.internal.org.jline.terminal.impl.NativeSignalHandler;

    21 import jdk.internal.org.jline.utils.InfoCmp.Capability;

    22 import jdk.internal.org.jline.utils.NonBlockingReader;

    23 

    24 /**

    25  * A terminal representing a virtual terminal on the computer.

    26  *

    27  * Terminals should be closed by calling the {@link #close()} method

    28  * in order to restore their original state.

    29  */

    30 public interface Terminal extends Closeable, Flushable {

    31 

    32     /**

    33      * Type used for dumb terminals.

    34      */

    35     String TYPE_DUMB = "dumb";

    36     String TYPE_DUMB_COLOR = "dumb-color";

    37 

    38     String getName();

    39 

    40     //

    41     // Signal support

    42     //

    43 

    44     enum Signal {

    45         INT,

    46         QUIT,

    47         TSTP,

    48         CONT,

    49         INFO,

    50         WINCH

    51     }

    52 

    53     interface SignalHandler {

    54 

    55         SignalHandler SIG_DFL = NativeSignalHandler.SIG_DFL;

    56         SignalHandler SIG_IGN = NativeSignalHandler.SIG_IGN;

    57 

    58         void handle(Signal signal);

    59     }

    60 

    61     SignalHandler handle(Signal signal, SignalHandler handler);

    62 

    63     void raise(Signal signal);

    64 

    65     //

    66     // Input / output

    67     //

    68 

    69     /**

    70      * Retrieve the <code>Reader</code> for this terminal.

    71      * This is the standard way to read input from this terminal.

    72      * The reader is non blocking.

    73      *

    74      * @return The non blocking reader

    75      */

    76     NonBlockingReader reader();

    77 

    78     /**

    79      * Retrieve the <code>Writer</code> for this terminal.

    80      * This is the standard way to write to this terminal.

    81      *

    82      * @return The writer

    83      */

    84     PrintWriter writer();

    85 

    86     /**

    87      * Returns the {@link Charset} that should be used to encode characters

    88      * for {@link #input()} and {@link #output()}.

    89      *

    90      * @return The terminal encoding

    91      */

    92     Charset encoding();

    93 

    94     /**

    95      * Retrieve the input stream for this terminal.

    96      * In some rare cases, there may be a need to access the

    97      * terminal input stream directly. In the usual cases,

    98      * use the {@link #reader()} instead.

    99      *

   100      * @return The input stream

   101      *

   102      * @see #reader()

   103      */

   104     InputStream input();

   105 

   106     /**

   107      * Retrieve the output stream for this terminal.

   108      * In some rare cases, there may be a need to access the

   109      * terminal output stream directly. In the usual cases,

   110      * use the {@link #writer()} instead.

   111      *

   112      * @return The output stream

   113      *

   114      * @see #writer();

   115      */

   116     OutputStream output();

   117 

   118     //

   119     // Input control

   120     //

   121 

   122     /**

   123      * Whether this terminal supports {@link #pause()} and {@link #resume()} calls.

   124      *

   125      * @return whether this terminal supports {@link #pause()} and {@link #resume()} calls.

   126      * @see #paused()

   127      * @see #pause()

   128      * @see #resume()

   129      */

   130     boolean canPauseResume();

   131 

   132     /**

   133      * Stop reading the input stream.

   134      *

   135      * @see #resume()

   136      * @see #paused()

   137      */

   138     void pause();

   139 

   140     /**

   141      * Stop reading the input stream and optionally wait for the underlying threads to finish.

   142      *

   143      * @param wait <code>true</code> to wait until the terminal is actually paused

   144      * @throws InterruptedException if the call has been interrupted

   145      */

   146     void pause(boolean wait) throws InterruptedException;

   147 

   148     /**

   149      * Resume reading the input stream.

   150      *

   151      * @see #pause()

   152      * @see #paused()

   153      */

   154     void resume();

   155 

   156     /**

   157      * Check whether the terminal is currently reading the input stream or not.

   158      * In order to process signal as quickly as possible, the terminal need to read

   159      * the input stream and buffer it internally so that it can detect specific

   160      * characters in the input stream (Ctrl+C, Ctrl+D, etc...) and raise the

   161      * appropriate signals.

   162      * However, there are some cases where this processing should be disabled, for

   163      * example when handing the terminal control to a subprocess.

   164      *

   165      * @return whether the terminal is currently reading the input stream or not

   166      *

   167      * @see #pause()

   168      * @see #resume()

   169      */

   170     boolean paused();

   171 

   172     //

   173     // Pty settings

   174     //

   175 

   176     Attributes enterRawMode();

   177 

   178     boolean echo();

   179 

   180     boolean echo(boolean echo);

   181 

   182     Attributes getAttributes();

   183 

   184     void setAttributes(Attributes attr);

   185 

   186     Size getSize();

   187 

   188     void setSize(Size size);

   189 

   190     default int getWidth() {

   191         return getSize().getColumns();

   192     }

   193 

   194     default int getHeight() {

   195         return getSize().getRows();

   196     }

   197 

   198     void flush();

   199 

   200     //

   201     // Infocmp capabilities

   202     //

   203 

   204     String getType();

   205 

   206     boolean puts(Capability capability, Object... params);

   207 

   208     boolean getBooleanCapability(Capability capability);

   209 

   210     Integer getNumericCapability(Capability capability);

   211 

   212     String getStringCapability(Capability capability);

   213 

   214     //

   215     // Cursor support

   216     //

   217 

   218     /**

   219      * Query the terminal to report the cursor position.

   220      *

   221      * As the response is read from the input stream, some

   222      * characters may be read before the cursor position is actually

   223      * read. Those characters can be given back using

   224      * <code>org.jline.keymap.BindingReader#runMacro(String)</code>

   225      *

   226      * @param discarded a consumer receiving discarded characters

   227      * @return <code>null</code> if cursor position reporting

   228      *                  is not supported or a valid cursor position

   229      */

   230     Cursor getCursorPosition(IntConsumer discarded);

   231 

   232     //

   233     // Mouse support

   234     //

   235 

   236     enum MouseTracking {

   237         /**

   238          * Disable mouse tracking

   239          */

   240         Off,

   241         /**

   242          * Track button press and release.

   243          */

   244         Normal,

   245         /**

   246          * Also report button-motion events.  Mouse movements are reported if the mouse pointer

   247          * has moved to a different character cell.

   248          */

   249         Button,

   250         /**

   251          * Report all motions events, even if no mouse button is down.

   252          */

   253         Any

   254     }

   255 

   256     /**

   257      * Returns <code>true</code> if the terminal has support for mouse.

   258      * @return whether mouse is supported by the terminal

   259      * @see #trackMouse(MouseTracking)

   260      */

   261     boolean hasMouseSupport();

   262 

   263     /**

   264      * Change the mouse tracking mouse.

   265      * To start mouse tracking, this method must be called with a valid mouse tracking mode.

   266      * Mouse events will be reported by writing the {@link Capability#key_mouse} to the input stream.

   267      * When this character sequence is detected, the {@link #readMouseEvent()} method can be

   268      * called to actually read the corresponding mouse event.

   269      *

   270      * @param tracking the mouse tracking mode

   271      * @return <code>true</code> if mouse tracking is supported

   272      */

   273     boolean trackMouse(MouseTracking tracking);

   274 

   275     /**

   276      * Read a MouseEvent from the terminal input stream.

   277      * Such an event must have been detected by scanning the terminal's {@link Capability#key_mouse}

   278      * in the stream immediately before reading the event.

   279      *

   280      * @return the decoded mouse event.

   281      * @see #trackMouse(MouseTracking)

   282      */

   283     MouseEvent readMouseEvent();

   284 

   285     /**

   286      * Read a MouseEvent from the given input stream.

   287      *

   288      * @param reader the input supplier

   289      * @return the decoded mouse event

   290      */

   291     MouseEvent readMouseEvent(IntSupplier reader);

   292 

   293     /**

   294      * Returns <code>true</code> if the terminal has support for focus tracking.

   295      * @return whether focus tracking is supported by the terminal

   296      * @see #trackFocus(boolean)

   297      */

   298     boolean hasFocusSupport();

   299 

   300     /**

   301      * Enable or disable focus tracking mode.

   302      * When focus tracking has been activated, each time the terminal grabs the focus,

   303      * the string "\33[I" will be sent to the input stream and each time the focus is lost,

   304      * the string "\33[O" will be sent to the input stream.

   305      *

   306      * @param tracking whether the focus tracking mode should be enabled or not

   307      * @return <code>true</code> if focus tracking is supported

   308      */

   309     boolean trackFocus(boolean tracking);

   310 }