/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.felix.service.terminal;
import java.io.*;
/**
* Terminal.
*
* The Terminal interface describes a minimal terminal that can easily be mapped
* to command line editing tools.
*
* A Terminal is associated with an Input Stream and an Output Stream. The Input
* Stream represents the keyboard and the Output Stream the screen.
*
* A terminal does not block the input, each character is returned as it is
* typed, no buffering or line editing takes place, characters are also not
* echoed. However, the Input Stream is not restricted to bytes only, it can
* also return translated key strokes. Integers from 1000 are used for those.
* Not all keys have to be supported by an implementation.
*
* A number of functions is provided to move the cursor and erase
* characters/lines/screens. Any text outputed to the Output Stream is
* immediately added to the cursor position, which is then moved forwards. The
* control characters (LF,CR,TAB,BS) perform their normal actions. However lines
* do not wrap. Text typed that is longer than the window will not be visible,
* it is the responsibility of the sender to ensure this does not happen.
*
* A screen is considered to be {@link #height()} lines that each have
* {@link #width()} characters. For cursor positioning, the screen is assumed to
* be starting at 0,0 and increases its position from left to right and from top
* to bottom. Positioning outside the screen bounds is undefined.
*/
public interface Terminal {
/**
* Cursor up key
*/
int CURSOR_UP = 1000;
/**
* Cursor down key.
*/
int CURSOR_DOWN = 1001;
/**
* Cursors forward key. Usually right.
*/
int CURSOR_FORWARD = 1002;
/**
* Cursors backward key. Usually left.
*/
int CURSOR_BACKWARD = 1003;
/**
* Page up key
*/
int PAGE_UP = 1004;
/**
* Page down key
*/
int PAGE_DOWN = 1005;
/**
* Home key
*/
int HOME = 1006;
/**
* End key
*/
int END = 1007;
/**
* Insert key
*/
int INSERT = 1008;
/**
* Delete key
*/
int DELETE = 1009;
/**
* Break key
*/
int BREAK = 1009;
/**
* Function key 1
*/
int F1 = 1101;
/**
* Function key 2
*/
int F2 = 1102;
/**
* Function key 3
*/
int F3 = 1103;
/**
* Function key 4
*/
int F4 = 1104;
/**
* Function key 5
*/
int F5 = 1105;
/**
* Function key 6
*/
int F6 = 1106;
/**
* Function key 7
*/
int F7 = 1107;
/**
* Function key 8
*/
int F8 = 1108;
/**
* Function key 9
*/
int F9 = 1109;
/**
* Function key 10
*/
int F10 = 1110;
/**
* Function key 11
*/
int F11 = 1111;
/**
* Function key 12
*/
int F12 = 1112;
enum Attribute {
BLINK, UNDERLINE, STRIKE_THROUGH, BOLD, DIM, REVERSED;
}
enum Color {
NONE, BLACK, GREEN, YELLOW, MAGENTA, CYAN, BLUE, RED, WHITE;
}
/**
* Return the associated Input Stream that represents the keyboard. Note
* that this InputStream can return values > 256, these characters are
* defined in this interface as special keys. This Input Stream should not
* be closed by the client. If the client is done, it should unget the
* services.
*
* @return the current Input Stream.
*/
InputStream getInputStream();
/**
* Return the Output Stream that is associated with the screen. Any writes
* Clear the complete screen and position the cursor at 0,0.
*
* @throws Exception
*/
void clear() throws Exception;
/**
* Leave the cursor where it is but clear the remainder of the line.
*/
void eraseEndOfLine();
/**
* Move the cursor up one line, this must not cause a scroll if the cursor
* moves off the screen.
*
* @throws Exception
*/
void up() throws Exception;
/**
* Move the cursor down one line, this must not cause a scroll if the
* cursors moves off the screen.
*
* @throws Exception
*/
void down() throws Exception;
/**
* Move the cursor backward. Must not wrap to previous line.
*
* @throws Exception
*/
void backward() throws Exception;
/**
* Move the cursor forward. Must not wrap to next line if the cursor becomes
* higher than the width.
*
* @throws Exception
*/
void forward() throws Exception;
/**
* Return the actual width of the screen. Some screens can change their size
* and this method must return the actual width.
*
* @return the width of the screen.
*
* @throws Exception
*/
int width() throws Exception;
/**
* Return the actual height of the screen. Some screens can change their
* size and this method must return the actual height.
*
* @return the height of the screen.
*
* @throws Exception
*/
int height() throws Exception;
/**
* Return the current cursor position.
*
* The position is returned as an array of 2 elements. The first element is
* the x position and the second elements is the y position. Both are zero
* based.
*
* @return the current position or null if not possible.
*
* @throws Exception
*/
int[] getPosition() throws Exception;
/**
* Position the cursor on the screen. Positioning starts at 0,0 and the
* maxium value is given by {@link #width()}, {@link #height()}. The visible
* cursor is moved to this position and text insertion will continue from
* that position.
*
* @param x
* The x position, must be from 0-width
* @param y
* The y position, must be from 0-height
* @throws IllegalArgumenException
* when x or y is not in range
* @throws Exception
*/
boolean position(int x, int y) throws Exception;
/**
* Set the attributes of the text to outputed. This method
* must reset all current attributes. That is, attributes
* are not inherited from the current position.
*
* @param foreground The foreground color
* @param background The background color (around the character)
* @param attr A number of attributes.
*/
boolean attributes(Color foreground, Color background, Attribute... attr);
}