home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
SCRNMS.ZIP
/
SCREEN.DOC
< prev
next >
Wrap
Text File
|
1990-03-15
|
32KB
|
1,080 lines
--------------------------------------------------------
Screen and Keyboard Functions Screen and Keyboard Functions
--------------------------------------------------------
Copyright (c) 1988-89, Christopher Laforet
Copyright (c) 1990, Chris Laforet Software
All Rights Reserved
_________________________________________________________________
Chapter 1 Chapter 1
Introduction Introduction
_________________________________________________________________
The Screen and Keyboard Library contains a great number of
functions for non-graphics (read text-mode) screen handling under
DOS and OS/2. These routines contain functions which range from
putting one character on the screen to functions which allow
shadowed windows to be manipulated. There are also a number of
low level keyboard accessing functions. These routines are
created for LARGE MODEL, the only model available for serious
applications.
The routines in this library are Copyrighted (c) 1989-89 by
Christopher Laforet and (c) 1990 by Chris Laforet Software and
all rights are reserved by the author. There are absolutely no
warranties implied or otherwise on these routines. Use them at
your own risk. While no software can be guaranteed absolutely
bug-free, these routines have been extensively tested and work on
most IBM-PC compatible displays. The author and copyright holder
shall in no way be held liable for any damages incurred by the
use of these routines.
The following mnemonics are copyright (c) 1987-90 by Dave
Neathery Software, and are used with express permission. The
permit portability to QNX systems using the library available
from Dave Neathery Software. The mnemonics are:
_vcw, _vcw, _bcw, _bsw, _vbr, prntnomov, prntnomovf,
prntmov, prntmovf, open_window, close_window, scr_init,
clrblk, phantom, _read_keyboard, _scan_keyboard and
_get_shift_status.
These routines contain my ideas insofar as screen routines
are concerned. Most of the time spent in writing to the display
using other routines is spent pushing the cursor around the
screen. Moving the cursor is a very intensive task, and it is
one of the reasons that BIOS video routines are so slow. My
contention is that there should be routines to write to the
screen and routines to write to the screen and move the cursor
ONCE to its final resting place. Hence, here is my philosophy of
video handling in a small neat package.
------------------------------------------------------
Screen and Keyboard Function Library
Page 2
_________________________________________________________________
Chapter 2 Chapter 2
Structures, Globals and Macros Structures, Globals and Macros
_________________________________________________________________
The purpose of this chapter is to present the various
structures and macros available for your use when accessing the
functions in the library.
2.1-Colors 2.1-Colors
_________________________________________________________________
There is an extensive array of color macros available in the
header file SCREEN.H. Here is a listing of the available colors.
Foreground:
BLACK
BLUE
GREEN
CYAN
RED
MAGENTA
BROWN
LT_GRAY -or- NORMAL
GRAY
LT_BLUE
LT_GREEN
LT_CYAN
LT_RED
LT_MAGENTA
YELLOW
WHITE -or- INTENSE
Modifier:
BLINK
Background:
ON_BLUE
ON_GREEN
ON_CYAN
ON_RED
ON_MAGENTA
ON_YELLOW
ON_WHITE -or- INVERSE
------------------------------------------------------
Screen and Keyboard Function Library
Page 3
These macros can be used anytime you need to pass colors to
a function (e.g WHITE). To create a complex color, simply OR the
individual values together. For example, blinking yellow on a
blue background will be YELLOW | ON_BLUE | BLINK.
2.2-Coordinates 2.2-Coordinates
_________________________________________________________________
Coordinates are specified as unsigned shorts encoded as (row
<< 8) + column. Rows and columns start at 0 from the top left
corner of the screen. For example, the bottom right corner of
the screen in 25 line mode will be specified as 0x184f (0x18 << 8
+ 0x4f) since line 24 is 0x18 and column 79 is 0x4f.
2.3-Cursor Shapes 2.3-Cursor Shapes
_________________________________________________________________
There are macros defined in SCREEN.H which define cursor
shapes and sizes. These are as follows:
HIDDEN - this may not work on ALL video cards
LINE - the underline cursor
UPPER_HALF - a block in the top half of the character
LOWER_HALF - a block in the bottom half of the character
FULL - a complete character block
Notice that due to a bug, some hardware implementations do not
set hidden cursors correctly. If this is the case (under DOS
only), you may park the cursor at the first column of one line
below the bottom line of the screen (in 25 line mode, 0x1900).
This is effective in hiding the cursor on ALL systems.
2.4-Current Cursor Position 2.4-Current Cursor Position
_________________________________________________________________
There is a macro in SCREEN.H which will return the current
cursor position mapped in the standard way for the use of the
library. The format is ((row << 8) + column) mapped into an
unsigned short. The macro that returns the current position is
CURPOS. Should you wish to print a string at the current cursor
position, you may do the following:
prntmovf(CURPOS,80,LIGHT_GRAY | ON_RED,"Here is a string!");
------------------------------------------------------
Screen and Keyboard Function Library
Page 4
The CURPOS macro will pass the current cursor position to the
prntmovf() function. The 80 merely indicates to the function
that the maximum length to print is 80 characters. The printing
will actually stop after the ! in the string.
2.5-Window Structure 2.5-Window Structure
_________________________________________________________________
The windowing functions return or accept a pointer to a
structure called window. This structure is declared in the
header WINDOW.H. Here is the structure for your information:
struct window
{
int *save;
int curpos;
int curmode;
int start; /* the upper left corner of window */
int stop; /* the lower left corner of window */
};
2.6-CGA Snow Flag 2.6-CGA Snow Flag
_________________________________________________________________
There is a global integer variable called _snow_flag which
is used only under DOS. This variable is used to select retrace
checking on old CGA monitors to reduce video snow while accessing
video RAM. By default, it is set to 0 which disables snow
checking, but may be set to 1 to enable snow checking on snowy
monitors. Notice that this variable is not present (nor needed)
under OS/2.
------------------------------------------------------
Screen and Keyboard Function Library
Page 5
_________________________________________________________________
Chapter 3 Chapter 3
Header Files Header Files
_________________________________________________________________
There are four header files for this library. They are
SCREEN.H, WINDOW.H, KB.H, and KEYS.H. KEYS.H contains macro
definitions for most of the extended keystrokes as they would be
returned by the _read_keyboard() function.
If you are using MSC, the headers automatically insert the
name of the correct library for your application into the object
file using the #pragma comment(lib,...) statement of the
Microsoft compiler. To specify the protected mode (OS/2)
library, you must #define PROTECTED (either in the source file or
using the -DPROTECTED option on the compiler's command line) at
some point in your program prior to calling any of the screen
library headers.
------------------------------------------------------
Screen and Keyboard Function Library
Page 6
_________________________________________________________________
Chapter 4 Chapter 4
Function Descriptions Function Descriptions
_________________________________________________________________
4.1-Screen Handling Functions 4.1-Screen Handling Functions
_________________________________________________________________
* int scr_init(void)
This function MUST be called before calling any other screen
library function. It needs to be called only once. It sets the
video library into motion, detects the type of adapter card, and
initializes all of the necessary variables.
Returns: At this time, the return value is not implemented.
* void _cls(int attribute);
This function clears the screen to the requested color
(attribute). It does not move the cursor.
Example: _cls(YELLOW | ON_BLUE);
* int prntnomov(int cursor,int length,int attribute,
char *string);
This function will print up to length characters of the
passed string with the requested attribute starting at the
requested cursor position (encoded ((col << 8) + row)). If the
string is longer than length, then it is truncated. If the
string is shorter than length, then only strlen(string)
characters are printed to the screen. The cursor is not moved at
any time during this operation.
Example: prntnomov(0x100,80,WHITE,"Copyright (c) 1990.");
Returns: Number of characters written.
------------------------------------------------------
Screen and Keyboard Function Library
Page 7
* int prntnomovf(int cursor,int length,int attribute,
char *format,...);
This function will print up to length characters of the
passed string with the requested attribute starting at the
requested cursor position (encoded ((col << 8) + row)). If the
string is longer than length, then it is truncated. This
function allows the use of formatting statements in the string
which correspond to arguments passed after string (eg %s or %u)
just like printf(). If the expanded string is shorter than
length, then only strlen(string) characters are printed to the
screen. The cursor is not moved at any time during this
operation.
Example: char name[11];
prntnomovf(0x1010,20,YELLOW,"Name is %s",name);
Returns: Number of characters written.
* int prntmov(int cursor,int length,int attribute,
char *string);
This function will print up to length characters of the
passed string with the requested attribute starting at the
requested cursor position (encoded ((col << 8) + row)). If the
string is longer than length, then it is truncated. If the
string is shorter than length, then only strlen(string)
characters are printed to the screen. The cursor is moved to the
end of the printed string.
Example: prntmov(0,50,LT_CYAN | ON_RED,"Do you want to exit? ");
Returns: Number of characters written.
* int prntmovf(int cursor,int length,int attribute,
char *format,...);
This function will print up to length characters of the
passed string with the requested attribute starting at the
requested cursor position (encoded ((col << 8) + row)). If the
string is longer than length, then it is truncated. This
function allows the use of formatting statements in the string
which correspond to arguments passed after string (eg %s or %u)
just like printf(). If the expanded string is shorter than
length, then only strlen(string) characters are printed to the
screen. The cursor is moved to the end of the printed string.
Example: char username[21];
prntmovf(0x1800,80,WHITE,"Are you %s? ",username);
Returns: Number of characters written.
------------------------------------------------------
Screen and Keyboard Function Library
Page 8
* int prntmem(int length,int attribute,void *buffer,
char *string);
This function will format up to length characters of the
passed string with the requested attribute to the passed buffer
location. The buffer must be capable of holding (length * 2)
characters. If the expanded string is longer than length, then
it is truncated. If the string is shorter than length, then only
strlen(string) characters are printed to the buffer.
Example: char image[40];
prntmem(20,GREEN,image,"Memory image!");
Returns: Number of characters formatted into buffer.
* int prntmemf(int length,int attribute,void *buffer,
char *format,...);
This function will format up to length characters of the
passed string with the requested attribute to the passed buffer
location. The buffer must be capable of holding (length * 2)
characters. This function allows the use of formatting
statements in the string which correspond to arguments passed
after string (eg %s or %u) just like printf(). If the string is
longer than length, then it is truncated. If the string is
shorter than length, then only strlen(string) characters are
printed to the buffer.
Example: char func_name[32];
char message[160];
prntmemf(80,WHITE,message,"Error in %s",func_name);
Returns: Number of characters formatted into buffer.
* int prntcenter(int cursor,int width,int color,
char *string);
This function will print a string centered in an imaginary
block starting at cursor and extending for width characters with
the respective color.
Example: prntcenter(0x0,80,LT_BLUE,"*** Presenting ***");
Returns: Number of characters written.
------------------------------------------------------
Screen and Keyboard Function Library
Page 9
* int _vcw(char character,int attribute,int cursor,
int length);
This is one of the low level functions and is fast. It
prints a character with the respective attribute for length
repetitions starting at cursor. The cursor is not moved.
Example: _vcw('▓',LT_GRAY | ON_BLUE,0x0,80);
Returns: Number of characters written.
* int _vsw(char far *string,int cursor,int length,
int attribute);
This function is one of the low-level functions and can be
expected to be fast. It prints a string with the respective
attribute for length starting at cursor. The cursor is not
moved.
Example: _vsw("This is a test",0x900,80,LT_GREEN);
Returns: Number of characters written.
* int _bcw(char character,int attribute,int length,
void *buffer);
This is one of the low level functions. It prints a
character with the respective attribute for length repetitions to
the passed buffer. The buffer must be at least (length * 2)
characters long. This function is useful in preparing buffered
screens.
Example: char buffer[20];
_bcw('_',WHITE | ON_RED,10,buffer);
Returns: Number of characters formatted.
* int _bsw(char *string,int attribute,int length,void *buffer);
This function is a low-level function. It prints a string
with the respective attribute for length into the passed buffer.
The buffer must at least be (length * 2) characters long. It is
useful in preparing buffered screens.
Example: char buffer[32];
_bsw("This is buffered",WHITE,16,buffer);
Returns: Number of characters formatted.
------------------------------------------------------
Screen and Keyboard Function Library
Page 10
* int _vbw(void *buffer,int cursor,int length);
This function is low level and hence should be fast. It
will write a previously buffered character-attribute list to the
screen at the specified cursor location and for the specified
length. The cursor is not moved.
Example: char buffer[32];
_bsw("This is buffered",WHITE,16,buffer);
_vbw(buffer,0x1020,16);
Returns: Number of characters written.
* int _vbr(void * buffer,int cursor,int length);
This function is low level. It will read the length of
character-attribute pairs from the screen memory into the
specified buffer. The buffer must be at least (length * 2)
characters long.
Example: char cell[2];
_vbr(cell,0x0,1);
_cls(cell[1]); /* clear the screen to same color */
Returns: Number of character-attribute pairs read.
------------------------------------------------------
Screen and Keyboard Function Library
Page 11
4.2-Windowing Functions 4.2-Windowing Functions
_________________________________________________________________
* struct window *open_window(int start,int stop,int attribute,
int type);
This function will open a window on the screen extending
from the start (top-left corner) to the stop (bottom-left corner)
positions. The window will have the attribute (color) specified.
The type refers to the type of box to draw around it and can be
one of the following:
0────┐ 1════╕ 2────╖ 3════╗ 4
│ │ │ │ ║ ║ ║ ║ No Box
└────┘ ╘════╛ ╙────╜ ╚════╝
The function returns a pointer to a window structure if it is
successful, else it returns NULL.
Example: struct window *wndw;
if (wndw = open_window(0x0,0x184f,WHITE,3))
{
...
close_window(wndw);
}
Returns: Pointer to struct window or NULL if error.
* void close_window(struct window *scrn);
This function closes a window previously opened with
open_window(). It frees any memory used to hold screen
information.
Example: See open_window() for example.
------------------------------------------------------
Screen and Keyboard Function Library
Page 12
* struct window *open_shadow_window(int start,int stop,
int attribute,
int type);
This function will open a window on the screen extending
from the start (top-left corner) to the stop (bottom-left corner)
positions. The window will have the attribute specified and will
have a shadow around the bottom and right hand sides. The type
refers to the type of box to draw around it and can be one of the
following:
0────┐ 1════╕ 2────╖ 3════╗ 4
│ │ │ │ ║ ║ ║ ║ No Box
└────┘ ╘════╛ ╙────╜ ╚════╝
The function returns a pointer to a window structure if it is
successful, else it returns NULL.
Example: struct window *wndw;
if (wndw = open_shadow_window(0x101,0x174e,WHITE,3))
{
...
close_shadow_window(wndw);
}
Returns: Pointer to struct window or NULL if error.
* void close_shadow_window(struct window *scrn);
This function closes a window previously opened with
open_shadow_window(). It frees any memory used to hold screen
information.
Example: See open_shadow_window() for example.
* int scroll_down(int tlc,int brc,int attribute,int lines);
This function scrolls the window specified by the
coordinates tlc (top left corner) and brc (bottom right corner)
down by the specified number of lines. Any lines left clear will
be set to the specified attribute (color).
Example: scroll_down(0x0,0x184f,GREEN,2);
Returns: The number of lines scrolled.
------------------------------------------------------
Screen and Keyboard Function Library
Page 13
* int scroll_up(int tlc,int brc,int attribute,int lines);
This function scrolls the window specified by the
coordinates tlc (top left corner) and brc (bottom right corner)
up by the specified number of lines. Any lines left clear will
be set to the specified attribute (color).
Example: scroll_up(0x0,0x184f,WHITE | ON_BLUE,1);
Returns: The number of lines scrolled.
4.3-Box Handling Functions 4.3-Box Handling Functions
_________________________________________________________________
* void clrblk(int start,int stop,int attribute);
This function will clear a block on the screen extending
from the top-left (start) coordinate to the bottom-right (stop)
coordinate to the desired attribute.
Example: clrblk(0x101,0x174e,WHITE | ON_GREEN);
* void drawbox(int start,int stop,int attribute,int type);
This function will draw a box frame (perimeter only, not the
inside) from the specified top-left coordinate to the bottom-
right coordinate and will use the specified attribute. The type
refers to the type of box to draw and can be one of the
following:
0────┐ 1════╕ 2────╖ 3════╗ 4
│ │ │ │ ║ ║ ║ ║ No Box
└────┘ ╘════╛ ╙────╜ ╚════╝
Example: drawbox(0x0,0x184f,WHITE | ON_RED,1);
* int phantom(int cursor,int length,int attribute);
This function is used to draw "phantom" cursors or to
otherwise change the attributes of a part of the screen. The
function will change the attributes starting at cursor on the
screen to the specified attribute for the specified length.
Example: phantom(0x100a,20,ON_WHITE);
Returns: Number of characters with changed attributes.
------------------------------------------------------
Screen and Keyboard Function Library
Page 14
4.4-Cursor Handling Functions 4.4-Cursor Handling Functions
_________________________________________________________________
* void _setcurpos(int cursor);
This function sets the cursor to the specified cursor
position (encoded ((row << 8) + column)).
Example: _setcurpos(0);
* void set_cursor_type(int type);
This function sets the specified cursor type (see above
macros).
Example: set_cursor_type(LINE);
4.5-Keyboard Routines 4.5-Keyboard Routines
_________________________________________________________________
* int _read_keyboard(void);
This function does a destructive read from the keyboard and
returns the key scan code in the low byte and a 1 in the high
byte if it was an extended keystroke (like F1 or Home) or a 0 in
the high byte if the ASCII value is in the low byte. This
function will wait for a keystroke if none is waiting.
Example: int key;
key = _read_keyboard();
if (key == 0x12d) /* key is Alt-X */
....
else if (key == 'A')
....
Returns: Key pressed.
------------------------------------------------------
Screen and Keyboard Function Library
Page 15
* int far _scan_keyboard(void);
This function polls the keyboard and returns a 0 if there is
not a keystroke waiting. If it returns a value other than 0,
then there is a key waiting to be retrieved with
_read_keyboard(). Watch out for polling loops under OS/2 as they
will bring the system down.
Example: while (!_scan_keyboard()) /* under DOS */
....
key = _read_keyboard();
while (!_scan_keyboard()) /* under OS/2 */
{
...
DosSleep(10L); /* sleep 10 msecs */
}
key = _read_keyboard();
Returns: 0 if no key is ready, or the keycode for the next key.
* int far _get_shift_status(void);
This function returns the state of the shift keys mapped
into a byte thus:
Ins Caps-Lock Num-Lock Scroll-Lock Alt Ctrl L-Shift R-Shift
7 6 5 4 3 2 1 0
Example: if (_get_shift_status() & 32)
prntnomov(0x40,8,YELLOW,"Num Lock");
Returns: Bitmapped status of shift keys.
------------------------------------------------------
Screen and Keyboard Function Library
Page 16
Contents Contents
Chapter 1 Introduction 2
Chapter 2 Structures, Globals and Macros 3
2.1 Colors . . . . . . . . . . . . . . . . . . . 3
2.2 Coordinates . . . . . . . . . . . . . . . . . 4
2.3 Cursor Shapes . . . . . . . . . . . . . . . . 4
2.4 Current Cursor Position . . . . . . . . . . . 4
2.5 Window Structure . . . . . . . . . . . . . . 5
2.6 CGA Snow Flag . . . . . . . . . . . . . . . . 5
Chapter 3 Header Files 6
Chapter 4 Function Descriptions 7
4.1 Screen Handling Functions . . . . . . . . . . 7
4.2 Windowing Functions . . . . . . . . . . . . 12
4.3 Box Handling Functions . . . . . . . . . . 14
4.4 Cursor Handling Functions . . . . . . . . . 15
4.5 Keyboard Routines . . . . . . . . . . . . . 15
i
