smg - Perl extension for screen management
use smg;
This package was released under the terms of the artistic license which terms are in the file copy.art.
This package uses the OpenVMS screen management utility. Curses work in a very poorly way on this system, while the native SMG package takes care of all the terminals you defined in the terminal library, of all collating tables you might have defined ...
It is obvious that this package is not portable on other OSs :-<
if you want to be informed of any new release mail to smg@tebbal.demon.co.uk
syntax initscr( $PbId, $KbId);
screen 4bytes integer is a pointer to the main screen definition. kb 4bytes integer is a pointer to the keyboard definition.
Changes the video attributes for all or part of a window.
Syntax:
changewinattr ($win ,$Y ,$X ,$nb_lines ,$nb_cols ,$attr );
Parameters:
$nb_cols: Horizontal width of the rectangle which attributes are to be modified.
$nb_lines: Vertical height of the rectangle which attributes are to be modified.
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$X: Number of the column ( leftmost column is number 1 ) of the upper left corner.
$Y: Number of the line ( top line is number 1 ) of the upper left corner.
$win: the window you created with crewin or loadwin
The function lets you change the
dimensions of a window.
Syntax:
changewinsize ($win ,$nb_lines ,$nb_cols);
Parameters:
$nb_cols: Number of columns of the new window
$nb_lines: Number of lines of the new window
$win: the window you created with crewin or loadwin
The function displays menu choices in the window indicated, starting at the specified line.
Syntax:
cremenu ($win ,$choices ,$option_size ,$flags ,$Y ,$attr);
Parameters:
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$Y: Number of the line ( top line is number 1 )
$flags: A character string with one character/option:
D: Double-spaced rows of menu items. The default is single spaced.
F: Each menu item is in a fixed-length field. The is the size of the largest menu item. The default is compress.
W: Wide characters are used in the menu items. The default is normal sized characters.
B: The menu items are displayed in matrix format (default).
V: Each menu item is displayed on its own line.
H: The menu items are displayed all on one line.
$option_size: size of every item in $choices . $choices will be
sliced according to this value.
The function creates a subwindow (called viewport in VMS terminology)
and associates it with a window. The location and size of
the subwindow are specified by the caller. When the window is sent
to screen, only the part mapped by the subwindow will be put on the
screen but it will be possible to move the subwindow over the window
to browse all the window.
Syntax:
cresubwin ($win ,$Y ,$X ,$nb_lines ,$nb_cols);
Parameters:
$nb_cols: Number of columns to show on screen
$nb_lines: Number of lines to show on screen
$X: Number of the column where start the subwindow ( leftmost column is number 1 )
$Y: Number of the line where start the subwindow ( top line is number 1 )
$win: the window you created with crewin or loadwin and which visible part will be reduced to the subwindow.
The function creates a window and returns its assigned display identifier
(please note it will not be visible until you use putwin() ).
Syntax:
crewin($Y,$X,$winId,$attr)
Parameters:
$attr: A character string with one character/attribute:
L: A lined border will be drawn around the window.
B: A thick block border will be drawn around the window.
Note that the window needs a border in order to have a title.
For a normal rendition just send the string "\0"
$X: Number of columns in the window (excluding the border).
$Y: Number of lines in the window (excluding the border).
$winId: the identifier of the window you want to create.
The function returns the virtual
cursor's current column position in a specified window.
Syntax:
curcol ($win);
Parameters:
$win: the window you created with crewin or loadwin
The function returns the virtual
cursor's current line position in a specified window.
Syntax:
curline ($win)
Parameters:
$win: the window you created with crewin or loadwin
The function deletes characters in a window.
Syntax:
delchars ($win ,$nb_chars ,$Y ,$X);
Parameters:
$nb_chars: Number of characters to delete.
$X: Number of the column where is starting the deletion ( leftmost column is number 1 )
$Y: Number of the line where is starting the deletion ( top line is number 1 )
$win: the window you created with crewin or loadwin
The function deletes lines from a window.
Syntax:
delline ($win ,$Y ,$nb_lines);
Parameters:
$nb_lines: Number of lines to delete.
$Y: Number of the first line to delete( top line is number 1 )
$win: the window you created with crewin or loadwin
The function ends access to the menu choices in the specified window.
Syntax:
delmenu ($win);
Parameters:
$win: the window you created with crewin or loadwin and where you created this menu.
The function deletes a window.
Syntax:
delwin ($win);
Parameters:
$win: the window you created with crewin or loadwin .
The function draws a horizontal or vertical line.
Syntax:
drawline ($win ,$Y0 ,$X0 ,$Y1 ,$X1 ,$attr);
Parameters:
$X0: Number of the column of line start point ( leftmost column is number 1 )
$Y0: Number of the row of line start point ( top line is number 1 )
$X1: Number of the column of line end point ( leftmost column is number 1 )
$Y1: Number of the row of line end point ( top line is number 1 )
$win: the window you created with crewin or loadwin
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
The function draws a rectangle.
Syntax:
drawbox ($win ,$Y0 ,$X0 ,$Y1 ,$X1 ,$attr);
Parameters:
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
($X0,$Y0) and ($X1,$Y1): are coordinates of one of the box diagonals.
$win: the window you created with crewin or loadwin
The function erases characters in a virtual
display by replacing them with blanks.
Syntax:
erasechars ($win ,$nb_chars ,$Y, $X);
Parameters:
$nb_chars: Number of characters to erase.
$X: Number of the column where the erase process starts ( leftmost column is number 1 )
$Y: Number of the line where the erase process starts ( top line is number 1 )
$win: the window you created with crewin or loadwin
The function erases the specified
portion of the window from the given position to the
end of the column. Erases the column number $X from
line number $Y0 to line number $Y1
Syntax:
erasecol ($win ,$Y0 ,$X ,$Y1 );
Parameters:
$X: Number of the column ( leftmost column is number 1 )
$Y0: Number of the starting line ( top line is number 1 )
$Y1: Number of the ending line ( top line is number 1 )
$win: the window you created with crewin or loadwin
The function erases all or part of a virtual
display by replacing text characters with blanks.
Syntax:
erasewin ($win ,$Y0 ,$X0 ,$Y1 ,$X1);
Parameters:
($X0,$Y0) and ($X1,$Y1): are coordinates of one of the diagonals of the rectangular area to erase.
$win: the window you created with crewin or loadwin
The function erases all or part of a line in a virtual
display. Erase line number $Y from column $X to the end
of line.
Syntax:
eraseline ($win ,$Y ,$X);
Parameters:
$X: Number of the column where line erasing starts ( leftmost column is number 1 )
$Y: Number of the line to erase ( top line is number 1 )
$win: the window you created with crewin or loadwin
The function erases the contents of a physical screen.
Syntax:
clearscreen ($PbId);
Parameters:
$PbId: The physical screen you defined in initscr
The function inserts characters into a virtual
display.
Syntax:
insertchars ($win , $string ,$Y ,$X ,$attr);
Parameters:
$string: Character string to insert in window.
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$X: Number of the column where the insertion starts ( leftmost column is number 1 )
$Y: Number of the line where the insertion starts ( top line is number 1 )
$win: the window you created with crewin or loadwin
The function inserts a line into a window and
scrolls the following lines or the previous lines
according to $direction.
Syntax:
insertline ($win ,$Y , $string ,$direction ,$attr);
Parameters:
$string: Character string containing the line to insert.
$direction:A one character string:
U: Preceding will be scrolled up, the first line will be lost.
D: following will be scrolled down, the last line will be lost.
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$Y: Number of the line ( top line is number 1 ) to insert.
$win: the window you created with crewin or loadwin
The function translates the
key code of a key on the keyboard into its associated key name.
Syntax:
codetoname ($code ,$name);
Parameters:
$name: Ascii String Giving The name of the pressed key.
$code: A 2byte integer number last pressed code; this code is using 0-255 for extended ascii character set, and over for the other keys (ex: F10, PF2, SELECT ...)
The function supplies a label for a
window's border. Note that the window must have created with
a border.
Syntax:
labelwin ($win ,$text ,$position ,$offset ,$attr );
Parameters:
$text: Text of the label.
$position: a one character string saying on which side is the label:
T: The label will be on the top side of the border.
B: The label will be on the bottom side of the border.
L: The label will be on the left side of the border.
R: The label will be on the right side of the border.
$offset: Position where start the label.
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$win: the window you created with crewin or loadwin
The function creates a new window and loads it with a window
saved with savwin.
Syntax:
loadwin ($win ,$filespec);
Parameters:
$filespec: the specification of the file containing the window saved with savewin (wild cards are not allowed).
$win: the window you created with crewin and saved with savwin
The Move function moves a rectangle of text from one window to
another window. Given two points in opposite corners of the rectangle.
When $win and $towin are the same windows the intersection between
source area and target area may not be what you expect. :-)
Syntax:
movearea ($win ,$Y0 ,$X0 ,$Y1 ,$X1, $towin, $toY, $toX, $flags);
Parameters:
($X0,$Y0) and ($X1,$Y1): are coordinates of two opposite corners of the rectangle to move.
$toX: Number of the column where to copy the area
$toY: Number of the line where to copy the area.
$flags: A character string with one character/option:
C: Just copy don't erase text from source window.
T: Move only the text not the video attributes.
$win: the window you created with crewin or loadwin
$towin: another window you created with crewin or loadwin
The function relocates a window on a
physical screen and preserves the pasting order.
Syntax:
movewin ($win ,$PbId, $Y, $X);
Parameters:
$X,$Y: New position of the window on the physical screen.
$PbId: The physical screen you defined in initscr
$win: the window you created with crewin or loadwin
The function translates the
key name of a key on the keyboard into its associated key code.
Syntax:
nametocode ($name ,$code);
Parameters:
$name: Ascii String Giving The name of the pressed key.
$code: A 2byte integer number last pressed code; this code is using 0-255 for extended ascii character set, and over for the other keys (ex: F10, PF2, SELECT ...)
The function pastes a window to a
physical screen.
Syntax:
putwin($Y,$X,$winId,$PbId);
Parameters:
$X: Number of the column on the physical screen where to display this window ( leftmost column is number 1 ).
$Y: Number of the line on the physical screen where to display this window ( top line is number 1 ).
$PbId: The physical screen you defined in initscr
$winId: the window you created with crewin or loadwin
The function prints the
contents of the specified physical screen on a line printer.
Syntax:
printscreen ($PbId ,$queue);
Parameters:
$PbId: The physical screen you defined in initscr
$queue: Name of the printer queue where to submit the print job.
The function writes
characters in a window with the text you specify.
Syntax:
putchars($winId,$SmgX,$SmgY,$SMGString,$attrib);
Parameters:
$SmgX: Number of the starting column of the string ( leftmost column is number 1 )
$SmgY: Number of the line where to write the string ( top line is number 1 )
$SmgString: Character string containing the text to write in the window
$attrib: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$win: the window you created with crewin or loadwin
The function writes
double-height, double-width (highwide) characters to a virtual
display.
Syntax:
puthichars($winId,$SmgX,$SmgY,$SMGString,$attrib);
Parameters:
$SmgX: Number of the starting column of the string ( leftmost column is number 1 )
$SmgY: Number of the line where to write the string ( top line is number 1 )
$SmgString: Character string containing the text to write in the window
$attrib: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$win: the window you created with crewin or loadwin
The function writes double-width
characters to a window.
Syntax:
putfatchars($winId,$SmgX,$SmgY,$SMGString,$attrib);
Parameters:
$SmgX: Number of the starting column of the string ( leftmost column is number 1 )
$SmgY: Number of the line where to write the string ( top line is number 1 )
$SmgString: Character string containing the text to write in the window
$attrib: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$win: the window you created with crewin or loadwin
The function writes a line of text
to a window, beginning at the current virtual cursor
position.
Syntax:
putline ($win ,$text ,$advance ,$attr);
Parameters:
$text: Character string containing the text to write in the window
$advance: Number of line to scroll before writing. If 0 the current line will be overwritten with $text.
$attr: A character string with one character/attribute:
I: Invisible;
B: Bold;
R: Reverse;
U: Underline;
F: Flashing
1: terminal user defined feature number 1;
2: terminal user defined feature number 2;
3: terminal user defined feature number 3;
4: terminal user defined feature number 4;
5: terminal user defined feature number 5;
6: terminal user defined feature number 6;
7: terminal user defined feature number 7;
8: terminal user defined feature number 8;
The user defined features are more often ansi colours and are available on Xterms or on colour terminals and colour terminal emulators VT2XX and over. For a normal rendition just send the string "\0"
$win: the window you created with crewin or loadwin
The function reads a keystroke and returns
that keystroke's terminator code.
Syntax:
readkey ($KbId ,$code);
Parameters:
$KbId: The Keyboard identifier returned by the function initscr
$code: A 2byte integer number last pressed code; this code is using 0-255 for extended ascii character set, and over for the other keys (ex: F10, PF2, SELECT ...)
The function reads a string off a keyboard with echo in the
window and returns the last keystroke's terminator code.
any unprintable key other than arrows or delete terminates
the program.
Syntax:
read_string($win,$KbId,$Str,$Size)
Parameters:
$KbId: The Keyboard identifier returned by the function initscr
$Str: The returned string.
$Size: Maximum size of the returned string.
$win: the window you created with crewin or loadwin
The function reads a keystroke and returns
that keystroke's terminator code.
Syntax:
readkeypt ($KbId ,$code ,$prompt ,$timeout ,$win);
Parameters:
$prompt: Ascii String use to prompt the user before waiting for the key stroke.
$timeout: Number of seconds to wait before returning with ``TIMEOUT'' as key name.
$KbId: The Keyboard identifier returned by the function initscr
$code: A 2byte integer number last pressed code; this code is using 0-255 for extended ascii character set, and over for the other keys (ex: F10, PF2, SELECT ...)
$win: the window you created with crewin or loadwin
The function repaints the specified
physical screen after non-SMG$ I/O has occurred.
Syntax:
refresh($PbId);
Parameters:
$PbId: The physical screen you defined in initscr
The function moves a window
to a new position on the physical screen. The pasting order is not
preserved. The difference with movewin() is that the window is moved
and put over all the other windows.
Syntax:
putwinagain($win ,$PbId ,$Y ,$X);
Parameters:
$X: Number of the physical screen column where to put the window ( leftmost column is number 1 )
$Y: Number of the physical screen line where to put the window ( top line is number 1 )
$PbId: The physical screen you defined in initscr
$win: the window you created with crewin or loadwin
The function returns the current virtual
cursor position in a specified window.
Syntax:
curpos ($win ,$Y ,$X);
Parameters:
$X: Number of the cursor current column in window $win ( leftmost
column is number 1 )
$Y: Number of the cursor current line in window $win ( top line is
number 1 )
$win: the window you created with crewin or loadwin
The Ring the function sounds the terminal
bell or buzzer.
Syntax:
bell ($win ,$nbtimes);
Parameters:
$nbtimes: Number of times the bell will ring on the terminal.
$win: the window you created with crewin or loadwin
The Save the function saves the contents
of a window and stores it in a file.
Syntax:
savewin ($win ,$filespec);
Parameters:
$filespec: the specification of the file that will contain the window (wild cards are not allowed).
$win: the window you created with crewin or loadwin
The function scrolls a virtual
display under its associated subwindow.
Syntax:
scrollsubwin ($win ,$direction ,$count);
Parameters:
$direction: A one character string:
U: Scrolls the window up $count lines
D: Scrolls the window down $count lines
L: Scrolls the window left $count lines
R: Scrolls the window right $count lines
The Make a Selection from the function lets you move between
the menu choices using the arrow keys and lets you make a
selection by pressing the Return key.
Syntax:
selmenuopt ($KbId ,$win ,$sel_nb ,$def_sel ,$flags ,$hlp);
Parameters:
$KbId: The Keyboard identifier returned by the function initscr
$flags: A character string with one character/option:
I: Returns immediately whatever is the pressed key.
R: Removes the selected option from the list.
$win: the window you created with crewin or loadwin
$sel_nb: Number of the selected option.
$def_sel: The option highlighted at start of the function.
$hlp: Default VMS help library searched for the current option when <help:> key is pressed (this parameter is meaningless when flag I is set.
The function moves the virtual cursor
to the specified position in a window.
Syntax:
setcurpos ($win ,$Y ,$X);
Parameters:
$X,$Y: Cursor new position.
$win: the window you created with crewin or loadwin
The function turns the physical cursor on or
off and selects jump or smooth scrolling.
Syntax:
setcurmode ($PbId ,$flags);
Parameters:
$flags: A character string with one character/option:
0: The cursor will not be visible.
1: The cursor will be visible.
J: The srolling will be on jump mode (faster).
S: The srolling will be on smooth mode (better for your eyes).
$PbId: The physical screen you defined in initscr
The function removes a window from
a physical screen.
Syntax:
remwin($win ,$PbId);
Parameters:
$PbId: The physical screen you defined in initscr
$win: the window you created with crewin or loadwin and you put on the screen with putwin.
Jean-claude Tebbal