Java Doc for Term.java in  » IDE-Netbeans » cvsclient » org » netbeans » lib » terminalemulator » Java Source Code / Java DocumentationJava Source Code and Java Documentation

It has the following generic features:

• All "dumb" operations. Basically putting characters on a screen and processing keyboard input.
• ANSI mode "smart" operations. Cursor control etc.
• Character attributes like color, reverse-video etc.
• Selection service in character, word and line modes matching xterm with configurable word boundary detection.
• History buffer.
• Facilities to iterate through logical lines, to implement search for example.
• Support for nested pickable regions in order to support hyperlinked views or more complex active text utilities.
• Support for double-width Oriental characters.

Coordinate systems

ANSI Screen coordinates

Address only the visible portion of the screen. They are 1-origin and extend thru the width and height of the visible portion of the screen per getColumns() and getRows().

This is how an application (like 'vi' etc) views the screen. This coordinate system primarily comes into play in the cursor addressing directive, op_cm() and otherwise is not really used in the implementation.

Cell coordinates

Each character usually takes one cell, and all placement on the screen is in terms of a grid of cells getColumns() wide This cellular nature is why fixed font is "required". In some locales some characters may be double-width. Japanese characters are like this, so they take up two cells. There are no double-height characters (that I know of).

Cursor motion is in cell coordinates, so to move past a Japanese character you need the cursor to move right twice. A cursor can also be placed on the second cell of a double-width character.

Note that this is strictly an internal coordinate system. For example Term.getCursorCol() and getCursorCoord() return buffer coordinates.

The main purpose of this coordinate system is to capture logical columns. In the vertical direction sometimes it extends only the height of the screen and sometimes the height of the buffer.

Buffer coordinates ...

... address the whole history character buffer. These are 0-origin and extend thru the width of the screen per getColumns(), or more if horizontal scrolling is enabled, and the whole history, that is, getHistorySize()+getRows().

The BCoord class captures the value of such coordinates. It is more akin to the 'int offset' used in the Java text package as opposed to javax.swing.text.Position.

If there are no double-width characters the buffer coords pretty much overlap with cell coords. If double-width characters are added then the buffer column and cell column will have a larger skew the more right you go.

Absolute coordinates ...

... are like Buffer coordinates in the horizontal direction. In the vertical direction their origin is the first line that was sent to the terminal. This line might have scrolled out of history and might no longer be in the buffer. In effect each line ever printed by Term gets a unique Absolute row.

What good is this? The ActiveRegion mechanism maintains coordinates for its' boundaries. As text scrolls out of history buffer row coordinates have to shift and all ActiveRegions' coords need to be relocated. This can get expensive because as soon as the history buffer becomes full each newline will require a relocation. This is the approach that javax.swing.text.Position implements and it's justified there because no Swing component has a "history buffer". However, if you use absolute coordinates you'll never have to relocate anything! Simple and effective.

Well almost. What happens when you reach Integer.MAX_VALUE? You wrap and that can confuse everything. What are the chances of this happening? Suppose term can process 4000 lines per second. A runaway process will produce Integer.MAX_VALUE lines in about 4 days. That's too close for comfort, so Term does detect the wrap and only then goes and relocates stuff. This, however, causes a secondary problem with testability since no-one wants to wait 4 days for a single wrap. So what I've done is periodically set Term.modulo to something smaller and tested stuff.

I'm indebted to Alan Kostinsky for this bit of lateral thinking.

Modes of use

Screen mode

This represents the traditional terminal without a history buffer. Applications running under the terminal assume they are dealing with a fixed size screen and interact with it in the screen coordinate system through escape sequence (ANSI or otherwise). The most common application which uses terminals in this ways is the screen editor, like vi or emacs.

Term will convert keystrokes to an output stream and will process characters in an input stream and render them unto the screen. What and how these streams are connected to is up to the client of Term, since it is usually highly platform dependent. For example on unixes the streams may be connected to partially-JNI-based "pty" streams.

This mode works correctly even if there is history and you see a scrollbar, just as it does under XTerm and it's derivatives.

Buffer/Interactive mode

This is the primary facility that XTerm and other derivatives provide. The screen has a history buffer in the vertical dimension.

Because of limited history active regions can scroll out of history and while the coordinate invalidation problem is not addressed by absolute coordiantes sometimes we don't want stuff to wink out.
Which is why we have ...

Page mode

It is possible to "anchor" a location in the buffer and prevent it from going out of history. This can be helpful in having the client of Term make sure that crucial output doesn't get lost due to short-sighted history settings on the part of the user.

To use Term in this mode you can use setText() or appendText() instead of connecting to Terms streams. This mode is called page mode because the most common use of it would be as something akin to a hypertext browser. To that end Term supports nestable ActiveRegions and mapping of coordinates to regions. ActiveTerm puts all of this together in a comprehensive subclass.

What Term is not

• While there is an internal Buffer class, and while it behaves like a document in that it can be implicitly "edited" and character attributes explicitly changed, Term is not a document editing widget.

• Term is also not a command line processor in the sense that a MS Windows console is. Its shuttling of keyboard events to an output stream and rendering of characters from the input stream unto the screen are completely independent activities.

  This is due to Terms unix heritage where shells (ksh, bash etc) do their own cmdline and history editing, but if you're so inclined the LineDiscipline may be used for experimentation with indigenous cmdline processing.

Usually called from within a LogicalLineVisitor.visit().

Normally a putChar() or putChars() will call repaint, unless ... setRepaintEnabled() has been called with false.

Be default Term consumes all keystrokes.

This is how xterm and other X-windows selections work.

This property can probably be deprecated.

A Term is a composite widget made of a contained screen (getScreen()) and a scrollbar.

When set to false, if the user moves the scrollbar to see some text higher up in history, the view will not change even if more output is produced.

Sizes are usually set by containers' layout managers.

The cursor is moved to the next column such that

 column (0-origin) modulo tab_size == 0
 

Note that the conventional assumption of what a tab is, is not entirely accurate.

If the size of the text exceeds history early parts of it will get lost, unless an anchor was set using setAnchor().

This function really should be private but I need it to be public for unit-testing purposes.

This function really should be private but I need it to be public for unit-testing purposes.

Text entered via the keyboard gets sent via this listener.

Travels forward over line boundaries.
Returns null if 'c' is the last character in the buffer.

Doesn't repaint the view unless 'repaint' is set to 'true'.
Doesn't do anything if 'text' is 'null'.

Travels back over line boundaries
Returns null if 'c' is the first character in the buffer.

Use Term.clearHistoryNoRefresh() if you find that clearHistory causes flickering.

This is useful if you want to avoid flicker.

Usually called from within a LogicalLineVisitor.visit(). 'begin' should be the 'begin' Coord passed to visit. 'offset' is an offset into the logical line, the 'text' argument passed to visit().

Note that 'offset' is relative to begin.col!

Following is an example of a line "aaaaaxxxxxxxxxXXXxxxxxxxx" which got wrapped twice. Suppose you're searching for "XXX" and you began your search from the first 'x' on row 2.

 row |  columns |
 ----+----------+
 0	|0123456789|
 1	|          |
 2	|aaaaaxxxxx| wrap
 3	|xxxxXXXxxx| wrap
 4	|xxxxx     |
 5	|	   |
 

The implementation of this function is not snappy (it calls Term.advance() in a loop) but the assumption is that his function will not be called in a tight loop.

Normally a putChar() or putChars() will call repaint, unless ... setRepaintEnabled() has been called with false. This function allows for some flexibility wrt to buffering and flushing:

 term.setRefreshEnabled(false);
 for (cx = 0; cx < buf.length; cx++) {
 term.putChar(c);
 if (c % 10 == 0)
 term.flush();
 }
 term.setRefreshEnabled(true);
 

Accessibility for Term is tricky because it doesn't fit into the roles delineated by Swing. The closest role is that of TEXT and that is too bound to how JTextComponent works. To wit ...

2D vs 1D coordinates

Term has a 2D coordinate system while AccessibleText works with 1D locations. So Term actually has code which translates between the two. This code is not exactly efficient but only kicks in when assistive technology latches on.
Line breaks ('\n's) count as characters! However we only count logical line breaks ('\n's appearing in the input stream) as opposed to wrapped lines!

The current implementation doesn't cache any of the mappings because that would require a word per line extra storage for the cumulative char count. The times actually we're pretty fast with a 4000 line histroy.

WORDs and SENTENCEs

For AccessibleText.get*Index() functions WORD uses the regular Term WordDelineator. SENTENCE translates to just a line.

Character attributes

Term uses the ANSI convention of character attributes so when AccessibleText.getCharacterAttribute() is used a rough translation is made as follows:

• ANSI underscore -> StyleConstants.Underline
• ANSI bright/bold -> StyleConstants.Bold
• Non-black foreground color -> StyleConstants.Foreground
• Explicitly set background color -> StyleConstants.Background

Font related information is always constant so it is not provided.

History

Term has history and lines wink out. If buffer coordinates were used to interact with accessibility, caretPosition and charCount would be dancing around. Fortunately Term has absolute coordinates. So positions returned via AccessibleText might eventually refer to text that has gone by.

Caret and Mark vs Cursor and Selection

While Term keeps the selection and cursor coordinates independent, JTextComponent merges them and AccessibleText inherits this view. With Term caretPosition is the position of the cursor and selection ends will not neccessarily match with the caret position.

Currently only notifications of ACCESSIBLE_CARET_PROPERTY and ACCESSIBLE_TEXT_PROPERTY are fired and that always in pairs. They are fired on the receipt of any character to be processed.

IMPORTANT: It is assumed that under assistive technology Term will be used primarily as a continuous text output device or a readonly document. Therefore ANSI cursor motion and text editing commands or anything that mutates the text will completely invalidate all of AccessibleTexts properties. (Perhaps an exception SHOULD be made for backspace)

Include logical newlines for now to match the above conversions. Hmm, do we include chars in prehistory?

The returned Coord is newly allocated and need not be cloned.

Be default Term consumes all keystrokes. Any KeyStroke added to this set will be passed through and not consumed.

Be careful with control characters you need to create the keystroke as follows (note the - 64):

 KeyStroke.getKeyStroke(new Character((char)('T'-64)), Event.CTRL_MASK)
 

Returns 'null' if there is no current selection.

If there is no selection returns 'null'.

See Term.setSizeRounded(boolean) for more info.

In the returned Point, x represents the column, y the row.

In the returned Point, x represents the column, y the row.

A page is the height of the view.

A page is the height of the view.

The pasted content is sent through sendChars.
The paste will silently fail if:

• The selection has null contents.
• The selections data flavor is not string.

The pasted content is sent through sendChars.
The paste will silently fail if:

• The selection has null contents.
• The selections data flavor is not string.

If the given coordinate is visible within the screen nothing happens. Otherwise the screen is scrolled so that the given target ends up approximately mid-sceeen.

If the given region is visible within the screen nothing happens. If the region is bigger than the screen height, first line of the region will be displayed in first line of screen and end of region won't be displayed. If the region is bigger than the half of screen height, last line of the region will be displayed in the last line of the screen. Otherwise the region will start approximately in mid-sceeen

Pass on the request to the screen where all the actual focus management happens.

If begin is null, then the start of the buffer is assumed. If end is null, then the end of the buffer is assumed.

Setting an anchor will automatically cause the buffer to grow, in excess of what was set by setHistorySize(), to ensure that whatever is displayed and in the current history will still be accessible.

Also, if you're working with Extents, Coords and ActiveRegions, or visiting logical lines, you might want to anchor the text so that your coordinates don't get invalidated by lines going out of the buffer.

Repeated enabling of the anchor will discard all text that doesn't fit in history and start a new anchor.

When anchoring is disabled any text in excess of setHistorySize() is trimmed and the given history size comes into effect again.

Unrecognized values silently ignored.

This is how xterm and other X-windows selections work.

This property can probably be deprecated. It was neccessary in the pre-1.4.2 days when we didn't have a systemSelection and we wanted to have the option of not cloberring the systemClipboard on text selection.

Will cause a repaint.

See setRowsColumns() for some additional important information.

We don't want a visible cursor when we're using Term in non-interactve mode.

Pass on enabledness to sub-components (scrollbars and screen)

We absolutely require fixed width fonts, so if the font is changed we create a monospaced version of it with the same style and size.

If an anchor is in effect the history size will only have an effect when the anchor is reset.

When enabled a horizontal scrollbar becomes visible and line-wrapping is disabled.

It is not advisable to change the emulation after Term has been connected to a process, since it's often impossible to advise the process of the new terminal type.

Note: This is independent of characters' reverse attribute.

See setRowsColumns() for some additional important information.

A Term is a composite widget made of a contained screen (getScreen()) and a scrollbar. It is not a JScrollPane. You're actually setting the screen size here.

Setting the column size also sets the width of the buffer. This doesn't alter the length (column at which lines were wrapped) of past lines, but only new additional lines. For example, if you set columns to 20, print a bunch of lines that wrap, then resize to 80 columns, all the lines that were wrapped to 20 will stay wrapped that way. This is consistent with xterm behaviour.

If this Term is embedded in a component with a layout manager that is set up to accept child resizes gracefully this widget will be resized as expected.

Alternatively if this Term is embedded in a Window (like JFrame) the window will need to be re-pack()ed as it does not accomodate it's childrens size changes. This has to be done by the application using Term. The best way to do this is to add a TermListener() and call pack() on the appropriate window when a resize notification is fired.

This is analogous to the xterm -sk/+sk option.

When set to false, if the user moves the scrollbar to see some text higher up in history, the view will not change even if more output is produced. But if the cursor is visible, scrolling will happen. This is so that in an interactive session any prompt will be visible etc.

However, the tracking of the cursor is controlled by the 'trackCursor' property which by default is set to 'true'.

This property is analogous to the xterm -si/+si option.

Sizes are usually set by containers' layout managers. If rounding is enabled Term will attempt to adjust the size to an even multiple of the character cell size.

The layout manager might not neccesarily honor the rounded size. The situation can be somewhat improved by making sure that the ultimate container is re-packed as described in Term.setRowsColumns(int,int) .

The cursor is moved to the next column such that

 column (0-origin) modulo tab_size == 0
 

Note that the conventional assumption of what a tab is, is not entirely accurate. ANSI does not define TABs as above but rather as a directive to move to the next "tabstop" which has to have been set previously. In fact on unixes it is the terminal line discipline that expands tabs to spaces in the conventional way. That in, turn explains why TAB information doesn't make it into selections and why copying and pasting Makefile instructions is liable to lead to hard-to-diagnose make rpoblems, which, in turn drove the ANT people to reinvent the world.

If the size of the text exceeds history early parts of it will get lost, unless an anchor was set using setAnchor().

If set to true, as output is being generated Term will try to keep the cursor in view.

This property is only relevant when scrollOnOutput is set to false. If scrollOnOutput is true, this property is also implicitly true.

If 'newlines' is set, the passed 'ecol' is set to the actual number of columns in the view to signify that the newline is included. This way of doing it helps with rendering of a whole-line selection. Also Line knows about this and will tack on a "\n" when Line.text() is asked for.

If begin is null, then the start of the buffer is assumed. If end is null, then the end of the buffer is assumed.