NAME
Term::WinConsole - Perl extension for text based windows management.
SYNOPSIS
use WinConsole;
$con = WinConsole->new('HELLO',80,25,1,1,'~',1);
$con->home;
$con->gotoCR(1,1);
$con->centerSt('This application uses WinConsole!');
$index = $con->setWindow('Login',5,5,55,5,1,1,'.');
$con->setActiveWin($index);
$con->setWinColor('light red on_black');
$con->resetColor;
$con->home;
$con->gotoCR(1,2);
$con->printSt('Hi you! what is your name ? :');
$con->fullDump;
$con->readyCurs;
chomp($answer = <>);
$con->doCR;
$index = $con->setWindow('Connected',7,7,50,6,1,1,'_');
$con->setActiveWin($index);
$con->setWinColor('light green on_black');
$con->resetColor;
$con->home;
$con->printSt("Your access is granted\n");
$con->printSt("Glads to see you $answer\n");
$con->printSt("Have a nice day\n");
$con->flush;
<>;
$con->setActiveWin(1);
$con->setWinTitle('Disconnected');
$con->home;
$con->printSt("Good Bye $answer\n");
$con->showWindow;
$con->fullDump;ABSTRACT
This module allows you to handle windows, cursor and colors on an ANSI compliant terminal.
DESCRIPTION
First of all, WinConsole uses ANSI sequences so don't expect to use it if your terminal is not ANSI/VT100 compliant.
WinConsole uses a backbuffer to build your screens. This means that all printing operations are invisible to the user until the next terminal refresh. WinConsole implements two methods for screen display. The first is a simple refresh method that just prints the backbuffer on the terminal. The second prints only differences between the terminal and the back buffer. Thanks to this feature, WinConsole allows you to greatly improve terminal applications performance by reducing the amount of data sent other the net.
WinConsole allows you to manage independent regions of text called miniwins. each miniwin has its own backbuffer so it can be moved around the screen and overlapped as you wish. they can even be resized under some restrictions.
There's always an active miniwin (miniwin 0 stands for the full screen) and all the cursor moving, color changing and text printing operations take place in that active miniwin. Thus, coordinates are relative to the active miniwin and not the entire screen (unless using the miniwin 0).
MINIWINS HANDLING
... functions used to create, move, resize, activate and delete miniwins ...
setWindow ($title, $colTop, $rowTop, $width, $height, $border, $cr, $pattern)
Creates a new miniwin starting at row $rowTop and column $colTop (in screen coordinates), $width characters wide and $height characters high with $title as title and char $pattern used as a default pattern. $border and $cr are just flags meaning 'draw a window border' if $border is true, and manage automatic carriage return if $cr is true.
This function returns the new miniwin index.
deleteWin ($winId)
Deletes the miniwin number $winId. Beware, this function just frees the memory used by the miniwin. It doesn't suppress this entry in the miniwin array.
setActiveWin ($winId)
Sets miniwin number $winId as the current active miniwin.
setWinBorder ($bool)
Sets the value of the 'border' flag for the active miniwin.
setWinCarret ($bool)
Sets the value of the 'automatic carriage return' flag for the active miniwin.
setWinPattern($pattern)
Sets $pattern as the default char used as background pattern in the active miniwin.
setWinTitle ($title)
Sets $title as the new miniwin title for the active miniwin
setWinCol ($col)
Sets $col as the new starting column for the active miniwin.
setWinRow ($row)
Sets $row as the new starting row for the active miniwin.
setWinWidth ($width)
Sets $width as the new width for the active miniwin.(The new value can't be greater than the creation size)
setWinHeight ($height)
Sets $height as the new height for the active miniwin.(The new value can't be greater than the creation size)
indexFind ($title)
Returns the miniwin index with $title as title
DISPLAY HANDLING
... functions used to send data to the terminal ...
Every drawing operations are made in a local miniwin backbuffer, so are they invisible to the user until the next refresh. When you want to refresh the terminal, all the miniwins' backbuffers are melt into a unique fullscreen backbuffer. This fullscreen backbuffer is then copied into a fullscreen frontbuffer (its purpose is to store a mirror of terminal's content into memory).
There are two methods to send the frontbuffer to the terminal :
- fullDump : displays every character on the terminal using correct colors and attributes. (it needs less computations but sends more data to the terminal)
- flush : makes a diff between the front and the back buffer and sends only differences (more computations needed but less data sent to the terminal)
makeFullBackBuffer
return a fullscreen attribute and a fullscreen text backbuffers using all the miniwins' backbuffer content.
flush ($win)
(See above for description) $win is optional. if defined, the refresh is limited to the miniwin $win. if ommited full screen will be refreshed.
In an array context : return data to be sent as a string.
In a non array context : send data to the terminal (i.e. print).
fullDump ($win)
(See above for description) $win is optional. if defined, the refresh is limited to the miniwin $win. if ommited full screen will be refreshed.
In an array context : return data to be sent as a string.
In a non array context : send data to the terminal (i.e. print).
CURSOR HANDLING
...functions used to set or retrieve the cursor position...
(these functions target the active miniwin's backbuffer. It means that you won't see their effect until the next terminal refresh.)
gotoCR ($col,$row)
Sets the cursor position on column $col and row $row of the active miniwin.A negative value takes the opposite edge as origin (-1,-1 means the last row and the last column)
getCR
Returns the cursor current column and row position relative to the active miniwin.
getAbsCR
Returns the cursor current column and row position relative to the entire screen.
doCR
Sets the cursor position to the left side of the active miniwin, one row below. ("do Carriage return")
readyCurs ($col,$row)
Prepares the terminal for direct character display. Useful if you want to retrieve user input with the correct active win colors and char attributes. Basically it sends ESC[$row;$colH and some ESC[....m to the terminal.
COLOR HANDLING
...functions used to set the current and window color...
(these functions target the active miniwin's backbuffer. It means that you won't see their effect until the next terminal refresh.)
To set a character color and attribute you have to define a color string using a combination of the following keywords :
Background colors : on_black on_red on_green on_yellow on_blue on_magenta on_cyan on_white
Foreground colors : black red green yellow blue magenta cyan white
Attributes : reset dark underscore clear light underline blink reverse hidden
for example : to define a light blue blinking text on a white background you will use the following string "light blue blink on_white".
setWinColor ($colorString)
Set a new default color for the active window. This default color is especially used when calling the home function.
setCurrentColor ($colorString)
Set a new current color for the active window. This color is used when printing text.
resetColor
Set the default window color as the new current color.
PRINTINGS HANDLING
...functions used to draw text and clear screen...
(these functions target the active miniwin's backbuffer. It means that you won't see their effect until the next terminal refresh.)
home
Erases the active miniwin content replacing every character by the miniwin's pattern and draws a border around the miniwin if its border flag is set to true.
deleteCh ($col, $row)
deletes the char at column $col and row $row in current active miniwin coordinates.
printCh ($char, $col, $row)
prints the char $char at column $col and row $row in current active miniwin coordinates.
streamCh ($char)
prints the char $char at column $col and row $row in current active miniwin coordinates and moves the cursor one column right.
printSt ($text)
prints the string $text at the current cursor position in current active miniwin coordinates.
centerSt($text)
prints the string $text centered at the current cursor row in the active miniwin.
BLOCK HANDLING
...functions used to paste or move text area...
(these functions target the active miniwin's backbuffer. It means that you won't see their effect until the next terminal refresh.)
The direction parameter is one of the following keywords : 'up' or 'u', 'down' or 'd', 'left' or 'l', 'right' or 'r'.
scrollWin($dir, $dist)
Scrolls the active miniwin's content $dist steps in the $dir direction.
pasteWin($dir, $txtref, $attref)
Paste the content of the supplied arrays on the $dir border. $txtref and $attref are arrays reference. txtref contains the characters to be printed. attref is optionnal and contains the attributes to be associated with each character of txtref.
WINDOW STACK HANDLING
... In order to manage miniwins overlapping, a stack is used to store miniwins depth level. I recommend you to only use the showWindow and hideWindow functions...
stackAdd ($idx)
adds window with ref $idx on top of the stack
stackDel ($idx)
supress window $idx from the stack
stackFocus ($idx)
moves window $idx on top of the stack
stackFind ($idx)
returns the offset of window $idx in the stack
showWindow
sets the active miniwin visible
hideWindow
sets the active miniwin hidden
MISCELLANEOUS FUNCTIONS
...the stat counter is incremented each time a character is printed by a display function (currently fullDump and flush). This feature is given for optimisation purposes...
resetStat
reset the stat counter.
getStat
return the stat counter value.
TIPS
Changing the characters used to draw miniwins' borders
These characters are stored in a hash %borderChr. the keys are : 'ul' for upper left corner 'ur' for upper right corner 'bl' for bottom left corner 'br' for bottom right corner 'hrz' for horizontal border 'vrt' for vertival border
How to bypass the 20 miniwins max limit ?
Just change the value of $MAXWIN
The terminal don't manage color orders but can use attributes orders (light, underline...)
You can set $USECOLOR to zero.
EXPORT
None by default.
AUTHOR
Jean-Michel VILOMET, jmichel@faeryscape.com
SEE ALSO
Term::ANSIColor - Color screen output using ANSI escape sequences by Russ Allbery
Term::ANSIScreen - Terminal control using ANSI escape sequences by Autrijus Tang
CREDITS
ANSI sequence call via AUTOLOAD with placeholders borrowed from Term::ANSIScreen.
COPYRIGHT
Copyright 2002 by Jean-Michel VILOMET <jmichel@faeryscape.com>
All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.