# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic ctrl.terminal
.title Terminal
.toc 1 Special Controls
.toc 1 Terminal
.index Terminal
.index ANSI Terminal
.index VT100

.h1 Terminal

DVX Extension -- DVX Widget: ansiterm

A VT100/ANSI terminal emulator with a text-mode cell buffer, 16-color CGA palette, and scrollback history. Processes standard ANSI escape sequences (cursor control, erase, scroll, SGR colors, DEC private modes) typically used by DOS BBS software. Default size is 80 columns by 25 rows. Supports text selection with the mouse, Ctrl+C to copy, and Ctrl+V to send clipboard text as input.

.h2 Type-Specific Properties

.table
  Property     Type      Description
  ----------   -------   -------------------------------------------
  Cols         Integer   Number of character columns (read-only).
  Rows         Integer   Number of character rows (read-only).
  Scrollback   Integer   Maximum number of scrollback lines. Older lines are dropped (write-only; default 500).
.endtable

.h2 Type-Specific Methods

.table
  Method             Description
  ------             -----------
  Clear              Clear the terminal screen and reset the cursor to the home position.
  Poll               Poll the attached communication channel for incoming bytes and feed them into the ANSI parser.
  Write text$        Write a string to the terminal with full ANSI escape processing.
.endtable

No default event. Uses common events only.

.h2 Serial Communication

Use the comm.bas library to connect a Terminal to a serial link:

.code
Dim link As Integer
link = CommOpen(1, 115200)
CommHandshake link
CommAttach link, "Terminal1"
.endcode

See comm.bas for the full communications API.

.h2 Example

.code
Begin Terminal Terminal1
    MinWidth  = 640
    MinHeight = 400
End

Sub Form_Load ()
    Terminal1.Write "Welcome!" & Chr$(13) & Chr$(10)
End Sub
.endcode

.link ctrl.common.props Common Properties, Events, and Methods
