home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 15
/
CD_ASCQ_15_070894.iso
/
maj
/
680
/
pictor.doc
< prev
next >
Wrap
Text File
|
1994-03-14
|
177KB
|
4,370 lines
PICTOR Video Library
User's Guide and Reference
For IBM (R) personal computers
and 100% compatibles
PICTOR User's Guide and Reference
SoftCircuits and PICTOR are trademarks of SoftCircuits. All other
brands and product names are trademarks or registered trademarks
of their respective holders.
PICTOR Video Library, Version 1.51
Copyright (c) 1992-94 SoftCircuits.
Redistributed by permission.
PICTOR was designed and written by Jonathan Wood.
SoftCircuits Programming
P.O. Box 16262
Irvine, CA 92713
U.S.A.
2
PICTOR User's Guide and Reference
COPYRIGHTED MATERIAL
---------------------------------------------------------------
This product (source code, object code, supporting programs, and
documentation) is protected by United States copyright law as
well as international copyright treaty provisions. SoftCircuits
is releasing this product to be used and distributed free of
charge, providing that SoftCircuits retains its copyright, and
receives credit for the work done in this product's creation.
In keeping with the above, SoftCircuits grants to you the
following rights:
1. You may make any number of copies of the source code, object
code, and supporting programs, for your own use or to be
distributed to others, provided that you distribute them in the
original, unmodified form, complete with all files, copyrights
notices, etc, and that no fee is charged for such distribution
except for reasonable media and shipping charges.
2. You may modify the copyrighted source code, object code, and
supporting programs in connection with your use of this product.
However, under copyright law, the modified source code and
resulting object code remain the copyrighted property of
SoftCircuits, regardless of the extent of the modifications.
Therefore, you may not alter or remove any copyright notices or
similar proprietary rights notices from any portion of this
product.
3. You may also incorporate any of the copyrighted object code
in executable form into your own programs, and you may use and
distribute these programs royalty free, provided that all of the
following requirements are satisfied:
a. All copies of such programs must bear a copyright notice,
and the form of the notice must not detract from
SoftCircuits' copyright in any way. Your own copyright
notice is sufficient if it consists entirely of the
following: the word "Copyright", the years(s) of publication
of the program, and your name (or your company name).
b. Such programs must not substantially duplicate the overall
functionality of this product or any portion thereof.
c. You must assume full and complete responsibility and
liability for the operation of these programs, including
testing of all included object code to ensure that it
functions as documented and/or as expected or required.
Except as described above, you may not legally copy or distribute
the documentation, source code, object code, or supporting
programs, in whole or in part. All rights not specifically
granted above are reserved by SoftCircuits.
3
PICTOR User's Guide and Reference
SOFTCIRCUITS SPECIFICALLY DISCLAIMS ALL WARRANTIES, INCLUDING,
WITHOUT LIMITATION, ALL IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD
PARTY RIGHTS.
UNDER NO CIRCUMSTANCES WILL SOFTCIRCUITS BE LIABLE FOR SPECIAL,
INCIDENTAL, CONSEQUENTIAL, INDIRECT, OR ANY OTHER DAMAGES OR
CLAIMS ARISING FROM THE USE OF THIS PRODUCT, INCLUDING LOSS OF
PROFITS OR ANY OTHER COMMERCIAL DAMAGES, EVEN IF WE HAVE BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL
SOFTCIRCUITS BE LIABLE FOR ANY CLAIMS, LIABILITY, OR DAMAGES
ARISING FROM CHANGES MADE BY YOU TO THE SOURCE CODE, OBJECT CODE,
OR SUPPORTING PROGRAMS.
4
PICTOR User's Guide and Reference
INTRODUCTION
-----------------------------------------------------------------
Pictor (pik'ter) [L, painter] a constellation between Carina and
Dorado.
PICTOR is a powerful video library designed for text-mode
applications written in C running on IBM personal computers and
100% compatibles. Features of the package include:
* Multi-pane stacked windows.
* Complete pulldown menu system.
* Complete hypertext help system and help compiler.
* Interrupt-driven serial communications routines.
* Ctrl-C, Ctrl-Break, and critical error handling. On
screen Clock.
* Text compression routines.
* Text editor sample application that edits files up to
available memory.
* All source code is included.
* Over 100 highly granular high-level and low-level
routines provide complete control over display and
keyboard.
The library provides many high level routines, most of which can
easily be implemented in just one or two function calls. For
example, the Ctrl-C, Ctrl-Break and critical error handlers are
all installed (and will all uninstall automatically) with a
single function call. The library also provides many low-level
functions that provide support for custom routines that you
create.
This package includes two sets of libraries: one for Microsoft C
7.0 and another for Borland C 3.0. Wherever practical, the
library routines are ANSI C compatible; therefore, the library
will link with programs compiled with C compilers from most other
vendors with little or no modifications.
Please read the README.DOC file on the distribution disk(s). It
contains last minute additions and corrections to the manual.
This file also has notes about working with the source code.
Refer to the file FILELIST.DOC for a list and description of all
the files on the distribution disk(s).
USING PICTOR
-----------------------------------------------------------------
This section describes the key elements of the PICTOR library.
Refer to the function reference section for a comprehensive
description of all functions and macros.
Getting Started
To install PICTOR on your system, you can use the INSTALL.EXE
program included with this package. Since none of the files on
the distribution disk(s) are compressed, you do not need to use
5
PICTOR User's Guide and Reference
this program. You might prefer to simply copy the files as you
need them. To start the installation program, make the drive that
contains the distribution disk(s) the active drive and enter the
following command at the DOS prompt:
INSTALL
The installation program's main menu contains the following three
selections:
Selection Description
-------------------------------------------------------------
Set Install Options This selection allows you to select
which elements of the PICTOR package you
want to install.
Set Install Directories This selection lets you specify the
directories where the library will be
installed. We recommend installing the
libraries and include files in your
compiler's library and include
directories.
Begin Installation This selection begins the installation
process.
The installation program will copy the selected files to the
specified directories.
Once PICTOR is installed, you can incorporate PICTOR functions
into your program by linking your program with the library that
matches the memory model and compiler that you are using. The
library names for each memory model and compiler are as follows:
Library Name Memory Model and Compiler
------------------------------------------------------------
PICTORSM.LIB Small and tiny memory models for Microsoft C
and Quick C.
PICTORMM.LIB Medium memory model for Microsoft C and Quick
C.
PICTORCM.LIB Compact memory model for Microsoft C and
Quick C.
PICTORLM.LIB Large and huge memory models for Microsoft C
and Quick C.
PICTORSB.LIB Small and tiny memory models for Borland C
and Turbo C.
PICTORMB.LIB Medium memory model for Borland C and Turbo
C.
PICTORCB.LIB Compact memory model for Borland C and Turbo
C.
PICTORLB.LIB Large and huge memory models for Borland C
and Turbo C.
If you are compiling from the command line, be sure that the
library is passed to the linker as a library and not linked in as
an object module. The library is highly granular so only the
6
PICTOR User's Guide and Reference
routines your program uses will be linked into your executable
file; however, linking with a library as an object module will
place the entire library into your program.
You should include the appropriate header file(s) in your source
code to insure proper type-checking of function arguments and
return values. The function reference section lists the
appropriate include file for each function or macro. We recommend
putting the include files in your compiler's include directory.
Refer to your C compiler's documentation for information about
the library and include directories and how to access the files
in those directories.
IMPORTANT: All programs that use PICTOR library functions to
access the display should begin by calling the initvideo
function. initvideo determines the type of display adapter that
is active and sets several internal variables accordingly. You
can then use getvconfig to return information about the current
display configuration if your application needs it.
PICTOR Windows
PICTOR library functions that write to the display can be divided
into two groups: those that are screen oriented and those that
are window oriented. The screen oriented functions can be used to
write anywhere on the screen. Window oriented functions restrict
output to within the active window pane. PICTOR provides a
stacked windowing system. Stacked windows created with wopen
remain on top of all previously created windows until they are
closed using wclose. While this method has limitations, it
provides the easiest possible interface for your applications.
PICTOR windows can have multiple window panes. Window panes are
window subdivisions that are created using wpane, and made active
with setwpane. A window always has at least one window pane and
can have as many as the window's size and system memory will
allow.
Using the Cursor
Within the library, there are actually three types of cursors:
the hardware text cursor, the screen's logical cursor, and the
active window pane's logical cursor. The hardware text cursor is
the visible, blinking cursor that you normally see when using
text-mode applications. The screen and active window pane's
logical cursors are not really cursors at all; they are values
maintained internally by the library to specify where screen
writes will occur. PICTOR library routines that write to the
screen pay no attention to the location of the hardware text
cursor.
The PICTOR library's use of cursors may be a little confusing at
first if you are used to always writing to the screen at the
position of the hardware text cursor. Since the library routines
write directly to display memory, it would be additional overhead
for those functions to always program the hardware text cursor.
7
PICTOR User's Guide and Reference
Many parts of the library (such as the menu system) simply
position the hardware text cursor off the screen while the user
makes selections by moving highlight bars and pressing hotkeys.
The functions and macros for working with the different cursors
are listed in the following table:
Function Description
--------------------------------------------------------------
getcurs Returns the current row and column position of the
hardware text cursor.
getcurscol Returns the current column position of the
hardware text cursor.
getcursrow Returns the current row position of the hardware
text cursor.
getcurstype Returns the hardware text cursor's starting and
ending scan line values.
getvcol Returns the current column position of the
screen's logical cursor position.
getvrow Returns the current row position of the screen's
logical cursor position.
getwcol Returns the current column position of the active
window pane's logical cursor position.
getwrow Returns the current row position of the active
window pane's logical cursor position.
popcurs Restores the hardware text cursor to the position
and type it was prior to the last call to
pushcurs.
pushcurs Saves the current hardware text cursor position
and type so that it can later be restored with
popcurs.
setcurs Sets the position of the hardware text cursor.
setcurstype Sets the starting and ending scan lines of the
hardware text cursor.
setvpos Sets the screen's logical cursor position.
setwpos Sets the active window pane's logical cursor
position.
showcurs Hides or restores the hardware text cursor.
synccurs Sets the position of the hardware text cursor to
match the current screen's logical cursor
position.
syncvpos Sets the screen's logical cursor position to match
the current position of the hardware text cursor.
wsynccurs Sets the position of the hardware text cursor to
match the active window pane's logical cursor
position.
All cursor coordinates are 1-based so 1, 1 specifies the top,
left corner of the cursor's respective region.
Displaying Colors
The PICTOR library provides complete control over screen colors.
The following color constants are defined in PICTOR.H:
8
PICTOR User's Guide and Reference
BLACK BLUE GREEN CYAN RED
MAGENTA YELLOW WHITE BOLD BLINKING
PICTOR functions that accept color specifiers require that the
foreground and background arguments are combined into a single
color value. The foreback macro can be used to combine foreground
and background arguments into a value that can be passed to
PICTOR functions. All of the color constants listed above can be
used as either foreground or background arguments except for BOLD
and BLINKING. BOLD and BLINKING are only valid when combined with
foreground arguments using + or |. For example, the following
statement uses vcolor to set the current color attribute to bold
white characters on a blue background.
vcolor(foreback(BOLD+WHITE,BLUE));
In addition, some library functions (such as runmenu and
messagebox) use several color attributes to display hotkeys and
highlight bars. These functions take a pointer to a COLORSTRUCT
structure. This structure contains the following members:
Member Description
----------------------------------------------
int normal Normal text.
int boldnormal Bold normal text.
int select Selected text.
int boldselect Bold selected text.
When writing your application, you should remember that some
users may not use a color display. You can use the getvconfig
function to determine if the active display supports color and
set your program's color attributes accordingly.
Creating Menus
The PICTOR library includes a complete menuing subsystem.
Incorporating menus into your application requires two steps:
creating your application's menu data structures, and placing a
call to runmenu in your application's main loop (or one of the
main loops).
The menu data structures contain the information that appears in
the menus and defines which functions will be called if the user
selects the corresponding menu selection. Optionally, they can
also contain information to be displayed on the status bar when
an item is highlighted, and can include a help topic string that
will be passed to helprun if the user presses <F1> when that item
is highlighted. Each pulldown submenu is defined as an array of
SUBMENU structures. This structure contains the following
members:
Member Description
----------------------------------------------
char *item The text that appears as the submenu
selection.
9
PICTOR User's Guide and Reference
char *description The text that appears on the status bar
when this selection is highlighted. (Use
NULL for none.)
char *helptopic A pointer to a help topic string to be
sent to helprun if the user presses <F1>
when this selection is highlighted.
void (*function)(void) A pointer to the function to be
called if the user selects this
selection.
You can use the constant SUBMENU_DIVIDER (defined in PICTOR.H) as
one or more of the array elements. This constant creates a
dividing bar that can be used to separate non-related menu items.
IMPORTANT: The last structure in the array must be the constant
END_SUBMENU (also defined in PICTOR.H). This constant signifies
the end of the submenu array.
When you have defined your submenus, you are ready to create the
mainmenu that references each of those submenus. A mainmenu is
created with an array of MAINMENU structures. This structure
contains the following members:
Member Description
---------------------------------------------
char *item The text that appears as the menu
selection.
char *description The text that appears on the status bar
when this selection is highlighted. (Use
NULL for none.)
char *helptopic A pointer to a help topic string to be
sent to helprun if the user presses <F1>
when this selection is highlighted.
SUBMENU *submenu A pointer to the submenu (pulldown menu)
to be activated if the user selects this
selection.
IMPORTANT: The last structure in the mainmenu array must be the
constant END_MAINMENU (also defined in PICTOR.H). This constant
signifies the end of the mainmenu array.
For both the SUBMENU and MAINMENU structures, the string in the
item field can contain embedded hotkeys. A hotkey is a bold
letter within a string that can be used to select the item
associated with that string. You can embed hotkeys by preceding
the character you want to be the hotkey with the tilde character
(~). (Note that the tilde character is not displayed in the
menu.) Hotkeys in the mainmenu can be used to select a submenu
(mainmenu hotkeys are used in combination with the Alt key when
the menu is not active). Hotkeys in the submenu can be used to
select submenu selections. For example, if one of your submenus
is called the "File" menu, and you want the first letter (F) to
be the hotkey, the item string in the MAINMENU structure might
appear as:
10
PICTOR User's Guide and Reference
"~File"
The main menu function_runmenu_works somewhat like kbdread
because it returns the keyboard code for the next available
keystroke. However, if the next keystroke is relevant to the
current menu, the keystroke is processed by runmenu and runmenu
returns 0. If runmenu returns the keystroke (a non-zero value),
your program can process the keystroke. By placing the call to
runmenu within your program's main loop (or one of its main
loops), the menu becomes an integrated part of your application.
In addition, you can use the showmenu function to display a menu
when your application paints the screen.
To see an example program that shows how to use runmenu, see the
example for runmenu in the function reference section.
Although the library provides no direct support for adding and
removing menu selections, it would be easy to implement such a
feature. Since runmenu takes a pointer to a menu data structure,
you can simple modify this data. In fact, you could easily create
an application with context-sensitive menus by defining several
menus and passing different ones to runmenu at different
locations in your program.
Creating On-line Help
This package provides a complete hypertext help system and help
compiler. Being hypertext means that you can embed links within
the help text. A link is a reference to another help topic,
usually displayed with bold attributes. The user can select a
link to view the topic it references. A help database can be
built with many links between topics that allows the user to
easily traverse between related topics.
The first step in creating on-line help is to write the help
text. The help compiler requires that the text follows a simple
set of syntax rules so that the compiler can generate the
required information.
Help compiler directives begin with the '@' character. In this
version of the help compiler, only two directives are supported:
@BEGIN and @END. @BEGIN defines the beginning of a help topic and
is followed on the same line by a label that names the topic. The
label may be one or more words. The @END directive marks the end
of a help topic. Compiler directives must always be the first
non-space characters on the line, and are not case sensitive.
Links are defined by placing text between two vertical bars (|).
The text should match a @BEGIN label defined elsewhere in the
help file. The text is not case sensitive but must match
character for character with the referenced topic label. Note
that the vertical bar characters are not displayed in the help
window. Also note that the starting and ending vertical bar must
be on the same line.
11
PICTOR User's Guide and Reference
Each line outside @BEGIN/@END directives that has a semicolon (;)
as the first non-space character is considered a comment and is
ignored by the help compiler. Blank lines outside @BEGIN/@END
directives are also ignored.
Here is a short example of a help text file:
;
; This line is a comment and is ignored by the help compiler
;
@BEGIN Apples
Apples can be red or green. Like other |Fruit|, apples grow on
trees.
@END
@BEGIN Bananas
Bananas are always yellow unless they are not yet ripe. For
another tasty fruit, see |Apples|.
@END
@BEGIN Fruit
Fruit grows on trees and is usually sweet to the taste. Some
examples of fruit are |Apples| and |Bananas|.
@END
This example defines three help topics: "Apples", which contains
a hypertext link to "Fruit"; "Bananas", which contains a link to
"Apples"; and "Fruit", which contains links to both "Apples" and
"Bananas".
The next step is to compile the help text using the help compiler
(HC.EXE). The help compiler has many warning and error messages
to help pinpoint any syntax errors in the input file. The
compiler uses the text compression routines included in the
PICTOR library. This results in an output file that averages
about 60% of the size of the input text file. The command line
syntax for the help compiler is:
HC <inputfile> <outputfile>
Although you can name the files anything you like, we recommend
giving the input file a .TXT extension, and the output file a
.HLP extension. Make certain that you never place the input file
in the <outputfile> field or else your input file could be
overwritten.
At this point, you have your application's help file and are
ready to program your application to use it. The first function
to call is helpopen. This function takes the name of the help
file, and the colors used to display the help window and help-
related messages. Note that helpopen doesn't actually open any
files; it just activates the help system so that helprun can be
called. helprun takes a string pointer as an argument. The string
12
PICTOR User's Guide and Reference
should match one of the topic names in your help file. If NULL is
passed to helpopen, a help index list box is displayed and the
user can select from any of the topics contained in the help
file.
You can use the helpsetcontext and helpgetcontext macros to set
and retrieve the current help context. Although the help context
has no effect on calls made by your application directly to
helprun, some PICTOR library routines that take input from the
user will call the help system if the user presses <F1> and the
help system has been enabled (by calling helpopen). The help
topic string that is passed to helprun by these functions is the
string specified by the help context.
Note that help text is uncompressed "on-the-fly" only for the
topics viewed by the user. The first time helprun is called,
several data structures are built. This means that if your
application only calls helpopen and the user never activates your
application's help system (that is, helprun is never called), no
overhead associated with opening the help file or allocating
memory for the data structures is incurred. You can call
helpclose to destroy the data objects created by helprun if you
need to recover the memory for them before your program
terminates.
For more information on the help functions, and to see an example
application, refer to the helprun description in the function
reference section. For a more significant help example, refer to
the help included with the text editor sample application that is
included in this package.
Serial Communications
The PICTOR library provides support for RS-232 asynchronous
serial communications. The communications routines implement
interrupt-driven data input (data output is not interrupt-
driven). Note that this version of the library only supports one
serial port at one time.
Although there are MS-DOS and ROM BIOS services available for
serial communications, none of them are interrupt driven. To use
these services, your program must either continually poll the
receive status, or risk losing data while your program is
performing another task. In addition, these services don't
support the highest baud rates possible on PC's. For these
reasons, the PICTOR communications routines by-pass the MS-DOS
and ROM-BIOS services altogether and program the hardware
directly.
The comopen function is used to prepare the serial port for input
and output. All other communications functions return an error if
comopen has not been called. Specifically, comopen does the
following:
13
PICTOR User's Guide and Reference
* Configures the serial port according to the port
number, baud rate, parity, data bits, stop bits, and
IRQ (interrupt request) values that you supply.
* Installs an interrupt handler for receiving data. The
handler places the data received in an internal
circular buffer where it remains until one of the
communications functions is called to retrieve it.
* Installs an interrupt handler for the system timer.
This handler is used for detecting time-out conditions.
The other communications routines are:
Function Description
-----------------------------------------------------
comclose Uninstalls the interrupt handlers installed
by comopen.
comflush Clears any characters waiting in the receive
buffer.
comgetc Reads a single character from the serial
port.
comgets Reads a '\r'-terminated string from the
serial port.
comloc Returns the number of characters waiting in
the receive buffer.
computc Writes a character to the serial port.
computs Writes a null-terminated string to the serial
port.
comread Reads the specified number of characters from
the serial port.
comwrite Writes the specified number of characters to
the serial port.
In addition, the comsettimeout and comgettimeout macros can be
used to set and retrieve the time-out value. The time-out value
specifies the amount of time allowed between characters before a
time-out condition is generated.
See the function reference section for a detailed description of
each of the communications functions.
Additional Information
This section has described how to use some of the key features of
the PICTOR library. We recommend that you browse through the
function reference section if you haven't done so already.
Reading the function descriptions will give you an idea of the
features available in this package. In addition, many function
descriptions include example programs. These example programs are
also on the distribution disk(s) for you to compile and modify.
The distribution disk(s) also includes Ed, a text editor program.
All the source code is included. Ed makes use of many of the
features of the PICTOR library. In addition, you can review the
14
PICTOR User's Guide and Reference
source code to see an implementation of a text editor and,
perhaps, customize it to suit your needs. Ed is missing many
features that would be required of a commercial text editor
program, but it has a strong foundation from which a more
professional text editor could be built. Refer to the file
README.DOC for additional information about working with the
editor source code.
Technical Assistance
As a free program, we cannot provide technical support for this
product. However, you may write to us at the address below if you
have any comments or questions. We will try to respond to all
correspondence.
If you would like a printed manual, with table of contents and
index, for the Pictor library, send $9.00 + $1.50 shipping to:
SoftCircuits Programming
P.O. Box 16262
Irvine, CA 92713
FUNCTIONS
----------------------------------------------------------------
This section provides a complete reference for all of the PICTOR
library functions and macros in alphabetical order. There are
several items that describe each function. The meaning of each
item is as follows:
Item Meaning
-------------------------------------------------------------
Syntax Shows the data types received and returned by the
function or macro.
Include Shows the include file that contains the prototype
for the function or the definition for the macro.
The include file also defines any constants or
structures that are associated with the function.
Description Gives a description of the function or macro.
Returns Describes the return value, if any.
See also Lists other functions or macros that are similar
to, or are usually used with, the function.
Example Some function descriptions give an example program
that shows how to use the function. Example
programs are complete programs that can be
compiled and run. All example programs are on the
distribution disk(s). Note that all the example
programs place angle brackets (< >) around
included header files. This assumes that you
placed the included header files in your
compiler's include directory.
beep
---------------------------------------------
15
PICTOR User's Guide and Reference
Syntax void beep(void);
Include pictor.h
Description This function sounds the computer's internal
speaker. beep provides a standard way to alert the
user by making a sound with the same frequency and
duration as is produced by many PICTOR library
routines (such as messagebox and editbox). Using
the beep function to alert the user has an
additional advantage because error beeps can then
be disabled globally using seterrorbeep.
Note that the beep function flushes the keyboard
buffer to prevent keyboard overrun.
See also seterrorbeep, tone
center
---------------------------------------------
Syntax int center(int inside, int outside);
Include pictor.h
Description This macro calculates the starting position so
that an item with inside length is centered inside
an item with outside length. The lengths can refer
to either width or height. If inside is larger
than outside, the result is undefined.
Returns The centered starting position as described above.
Example
/*
** CENTER.C: Displays a message centered on the screen.
*/
#include <string.h>
#include <pictor.h>
char *msg = "Hello, from the PICTOR library!";
void main()
{
VIDEOSTRUCT vstruct;
/* initialize library */
initvideo();
getvconfig(&vstruct);
vcolor(foreback(BOLD+WHITE,BLUE));
cls();
16
PICTOR User's Guide and Reference
setvpos(center(1,vstruct.rows),
center(strlen(msg),vstruct.columns));
vputs(msg);
kbdread();
/* restore screen */
vcolor(foreback(WHITE,BLACK));
cls();
}
cleareol
---------------------------------------------
Syntax void cleareol(void);
Include pictor.h
Description The cleareol function clears from the current
logical cursor position to the end of the line.
The logical cursor position is updated to point to
the start of the next line.
See also wcleareol
clrstatus
---------------------------------------------
Syntax void clrstatus(void);
Include pictor.h
Description The clrstatus function clears the status bar.
See also initstatus, statusbar
cls
---------------------------------------------
Syntax void cls(void);
Include pictor.h
Description This function clears the entire screen and
positions both the logical and the hardware text
cursor at the top, left corner of the screen.
comclose
---------------------------------------------
Syntax int comclose(void)
Include comlib.h
Description This function closes the communications port that
was previously opened using comopen. Since comopen
17
PICTOR User's Guide and Reference
registers comclose with the ANSI C library routine
atexit, you do not need to call this function.
atexit will call comclose upon normal program
termination. You may want to call comclose to
close the communications port before your program
terminates or to reopen the communications port
with a different configuration. There is no ill-
effect from calling comclose multiple times.
Returns 0 if successful or -1 if an error occurred.
See also comopen
comflush
---------------------------------------------
Syntax int comflush(void);
Include comlib.h
Description Clears any characters waiting in the receive
buffer for the communications port previously
opened using comopen.
Returns The number of characters that were in the buffer
before it was flushed.
See also comloc, comopen
comgetc
---------------------------------------------
Syntax int comgetc(char *cptr);
Include comlib.h
Description Gets the next available byte from the
communication port previously opened using
comopen. The byte is written to the character
pointed to by cptr.
Returns 0 if successful or -1 if an error occurred.
See also comloc, comopen, computc, comsettimeout
comgets
---------------------------------------------
Syntax int comgets(char *buffer, int maxlen);
Include comlib.h
Description Reads a string from the communications port
previously opened using comopen. Characters are
18
PICTOR User's Guide and Reference
read from the serial port and copied to buffer
until a carriage return ('\r') is copied or until
maxlen characters have been copied. A null-
terminator ('\0') is then appended to buffer.
buffer should be big enough to hold maxlen + 1
characters. If you need to receive data that may
include embedded carriage returns ('\r'), see the
comread function.
If an error occurs, buffer contains a null-
terminated string with the characters that had
been received prior to the error.
Returns 0 if successful or -1 if an error occurred.
See also comloc, comopen, computs, comread, comsettimeout
comloc
---------------------------------------------
Syntax int comloc(void);
Include comlib.h
Description The comloc function returns the number of
characters waiting in the receive buffer for the
communications port previously opened using
comopen.
Returns The number of characters waiting in the receive
buffer.
See also comflush, comopen
comopen
---------------------------------------------
Syntax int comopen(int comport, int baudrate, int parity,
int databits, int stopbits, int irq);
Include comlib.h
Description Configures the specified communications port based
on the given arguments. The constants (defined in
PICTOR.H) allowed for each argument field are
described below:
Field Constant Meaning
---------------------------------------------
comport CO_COM1 COM1
CO_COM2 COM2
CO_COM3 COM3
CO_COM4 COM4
baudrate CO_BAUD300 300 baud
19
PICTOR User's Guide and Reference
CO_BAUD1200 1200 baud
CO_BAUD2400 2400 baud
CO_BAUD4800 4800 baud
CO_BAUD9600 9600 baud
CO_BAUD19200 19200 baud
CO_BAUD38400 38400 baud
CO_BAUD57600 57600 baud
CO_BAUD115200 115200 baud
parity CO_NOPARITY No parity
CO_ODDPARITY Odd parity
CO_EVENPARITY Even parity
databits CO_DATA7 7 data bits
CO_DATA8 8 data bits
stopbits CO_STOP1 1 stop bit
CO_STOP2 2 stop bits
irq CO_IRQDEFAULT Standard IRQ4 for
COM 1 and 3, IRQ3
for COM 2 and 4.
CO_IRQ2 IRQ2
CO_IRQ3 IRQ3
CO_IRQ4 IRQ4
CO_IRQ5 IRQ5
The I/O address for the specified RS-232 adapter
is read from the ROM BIOS data area. If the value
read is 0, the specified communications port is
considered invalid and comopen returns an error.
When comopen is called for the first time, it
registers comclose with the ANSI C library
function atexit. atexit will automatically call
comclose upon normal program termination.
Note: The comopen function traps interrupt 0x1C.
installclock also traps interrupt 0x1C. If you are
using both functions and you need to manually
remove or close either one, they must be
uninstalled in the reverse order that they were
installed.
Returns 0 if successful or -1 if an error occurred.
See also comclose, comsettimeout
compress
---------------------------------------------
Syntax WORD compress(BYTE *inbuff, WORD len,
BYTE *outbuff, NODE *rootnode);
Include compress.h
Description Compresses an array of characters using the
huffman compression algorithm. inbuff is a pointer
20
PICTOR User's Guide and Reference
to a buffer with the characters to be compressed.
len is the number of characters in inbuff. outbuff
is where the compressed data will be written.
rootnode is the root node to a compression code
tree created with gettree.
The huffman compression algorithm takes advantage
of the fact that some characters are used more
frequently than others. The more frequently a
character is used, the fewer the number of bits
that are used to represent that character.
Therefore, compress is most effective when
compressing straight text files and is not
recommended for compressing binary data.
Note that although this compression algorithm
offers significant compression, if your file is
compressed in multiple segments, it is possible
for the compressed data to be larger than the
original data in one or more of those segments.
For this reason, outbuff should be larger than len
bytes under most conditions. Also note that all
characters in inbuff must have been included in
the file stream passed to gettree when the code
tree was created or compress will fail.
Returns The number of bytes written to outbuff (the
compressed length).
See also freetree, gettree, readtree, uncompress, writetree
Example
/*
** COMPRESS.C: Compresses a text file. Use UNCOMP.C to
** restore to original form.
*/
#include <stdio.h>
#include <string.h>
#include <compress.h>
BYTE inbuff[BUFSIZ];
BYTE outbuff[BUFSIZ + 200];
void main(int argc,char *argv[])
{
FILE *istream,*ostream;
WORD complen,uncomplen;
NODE *rootnode;
/* check arguments */
if(argc != 3 || !stricmp(argv[1],argv[2])) {
printf("Usage:\tCOMPRESS <infile> <outfile>\n");
21
PICTOR User's Guide and Reference
return;
}
/* open files */
istream = fopen(argv[1],"rt");
ostream = fopen(argv[2],"wb");
if(istream == NULL || ostream == NULL) {
printf("File error\n");
return;
}
/* build compression code tree */
rootnode = gettree(istream);
if(rootnode == NULL) {
printf("Out of memory\n");
return;
}
/* set file pointer back to beginning of file */
rewind(istream);
/* write compressed code tree to file */
complen = writetree(rootnode,outbuff);
putw(complen,ostream);
fwrite(outbuff,sizeof(BYTE),complen,ostream);
/* compress data and write to output file */
do {
uncomplen = fread(inbuff,sizeof(BYTE),BUFSIZ,
istream);
complen = compress(inbuff,uncomplen,outbuff,
rootnode);
putw(uncomplen,ostream);
putw(complen,ostream);
fwrite(outbuff,sizeof(BYTE),complen,ostream);
} while(uncomplen == BUFSIZ);
/* indicate end of file */
putw(0x00,ostream);
fclose(istream);
fclose(ostream);
}
computc
---------------------------------------------
Syntax int computc(char c);
Include comlib.h
Description Writes a single character to the communications
port previously opened using comopen.
22
PICTOR User's Guide and Reference
Returns 0 if successful or -1 if an error occurred.
See also comgetc, comopen, comsettimeout
computs
---------------------------------------------
Syntax int computs(char *string);
Include comlib.h
Description Writes a null-terminated string to the
communications port previously opened using
comopen. The null-terminator is not written. If
you need to send data that contains embedded null
characters ('\0'), use the comwrite function.
Returns 0 of successful or -1 if an error occurred.
See also comgets, comopen, comsettimeout, comwrite
comread
---------------------------------------------
Syntax int comread(char *buffer, int count);
Include comlib.h
Description Copies count bytes to buffer from the
communications port previously opened using
comopen.
Returns 0 if successful or -1 if an error occurred.
See also comloc, comopen, comwrite, comsettimeout
comgettimeout, comsettimeout
---------------------------------------------
Syntax int comgettimeout(void);
void comsettimeout(int timeout);
Include comlib.h
Description These macros get and set the time-out value used
by the serial communications functions. Many of
these functions return an error condition if a
time-out occurs while trying to send or receive a
character across the serial port.
The time-out value defines the number of 18ths of
a second allowed between each character
transmitted or received before a time-out
condition is generated.
23
PICTOR User's Guide and Reference
Returns comgettimeout returns the current time-out value.
comwrite
---------------------------------------------
Syntax int comwrite(char *buffer, int count);
Include comlib.h
Description Copies count bytes from buffer to the
communications port previously opened using
comopen.
Returns 0 if successful or -1 if an error occurred.
See also comopen, comread, comsettimeout
_CURR_WPANE
---------------------------------------------
Include pictor.h
Description The _CURR_WPANE macro is equal to the active
window pane. You can use the macro as a structure;
it is not a pointer. The effects of this macro are
undefined if there is no active window pane.
This macro is designed to only be used internally
by PICTOR library functions but is documented here
in case you need it.
editbox
---------------------------------------------
Syntax int editbox(char *prompt, char *buffer,
int maxlen, char *title,
COLORSTRUCT *colors);
Include pictor.h
Description The editbox function creates a window with the
given prompt, and calls kbdedit to edit a string.
buffer is where the edited text will be stored and
maxlen is the maximum number of characters
allowed. title is the title given to the window
(use NULL for no title). colors is a pointer to a
COLORSTRUCT structure that contains the colors
used to display the window.
Returns TRUE if the user pressed <Enter>, or FALSE if the
user pressed <Escape>. If the user pressed
<Escape>, the contents of buffer are not modified.
24
PICTOR User's Guide and Reference
escpressed
---------------------------------------------
Syntax int escpressed(void);
Include pictor.h
Description The escpressed macro determines if the last key
returned by kbdread was the <Escape> key. This
macro is useful with some library functions such
as messagebox for determining if the function
ended in response to the user pressing <Escape>.
Returns TRUE if the last keystroke returned by kbdread was
the <Escape> key, FALSE otherwise.
foreback
---------------------------------------------
Syntax int foreback(int foreground, int background);
Include pictor.h
Description The foreback macro combines foreground and
background into a single color attribute value.
Since PICTOR library functions that take color
arguments require a single color integer, foreback
can be used as an argument to those functions.
Returns The combined color attribute as described above.
See also vcolor
Example For an example of foreback, please see the helprun
example.
frame
---------------------------------------------
Syntax void frame(int top, int left, int height,
int width);
Include pictor.h
Description This function draws a box using the current frame
type.
See also setframe
freetree
---------------------------------------------
Syntax void freetree(NODE *rootnode);
25
PICTOR User's Guide and Reference
Include compress.h
Description This function frees the memory for a compression
code tree created with gettree or readtree.
rootnode is a pointer to the tree's root node.
This function is provided because simply passing a
root node to the free function does not release
all of the memory in the tree.
See also compress, gettree, readtree, uncompress, writetree
getaltkey
---------------------------------------------
Syntax int getaltkey(int c);
Include pictor.h
Description Converts the ASCII character c into its Alt-key
equivalent. For example, if c is 'A' or 'a',
getaltkey returns the key code for ALT_A which is
defined in PICTOR.H.
Returns The Alt-key equivalent of c, or 0 if c is not
alpha-numeric.
See also gethotkey
getcurs, getcurscol, getcursrow
---------------------------------------------
Syntax int getcurs(void);
int getcurscol(void);
int getcursrow(void);
Include pictor.h
Description The getcurs routines return the current location
of the hardware text cursor. getcurs returns the
location as a single integer value. The high byte
contains the cursor's row coordinate; the low byte
contains the cursor's column coordinate. The
getcursrow and getcurscol macros return the row
and column coordinates separately.
Returns The cursor location as described above.
See also getvcol, getvrow, setcurs
getcurstype
---------------------------------------------
Syntax int getcurstype(void);
26
PICTOR User's Guide and Reference
Include pictor.h
Description This function returns the starting and ending scan
lines of the current hardware text cursor. The
high byte of the return value contains the
cursor's starting scan line, and the low byte
contains the ending scan line.
Returns The current cursor type as described above.
See also setcurstype
gethotkey
---------------------------------------------
Syntax int gethotkey(char *string);
Include pictor.h
Description This function returns the first character in
string that would be printed bold by hputs. This
is the character that follows the first tilde (~)
character.
Returns The first character in string following the first
tilde character or 0 if string contains no such
character.
See also getaltkey, hputs
getscrn
---------------------------------------------
Syntax void getscrn(int *buffer, int top, int left,
int height, int width);
Include pictor.h
Description Copies the data from the region of the screen
specified by the last 4 arguments to buffer.
getscrn is used to save the screen before opening
a window. The window can then be closed by using
putscrn to write the original data back to the
screen. Since getscrn is called automatically by
wopen, you'll only need to call this function if
you are writing custom windowing routines.
The size of buffer should be ((height * width) *
sizeof(int)).
See also putscrn
gettree
27
PICTOR User's Guide and Reference
---------------------------------------------
Syntax NODE *gettree(FILE *stream);
Include compress.h
Description Builds a compression code tree for the characters
in stream and returns a pointer to the root node.
Since the compression routines are unable to
process blocks of data larger than 64k, and the
code tree must include all of the characters to be
compressed, this function takes a FILE pointer as
its argument (as opposed to a buffer pointer).
Characters are read from stream starting from the
current file position and continuing until the end
of file, or until an error occurs. Note that
stream remains open and the file position
associated with stream points past the last
character read when gettree returns.
Returns A pointer to the root node or NULL if there was
not enough memory to create the tree.
See also compress, freetree, readtree, uncompress,
writetree
Example For an example of gettree, please see the compress
example.
getvcol, getvrow
---------------------------------------------
Syntax int getvcol(void)
int getvrow(void)
Include pictor.h
Description These two macros return the current logical screen
position used by PICTOR library routines.
Returns The current logical screen position as described
above.
See also getcurs, getwcol, getwrow, setvpos
getvconfig
---------------------------------------------
Syntax void getvconfig(VIDEOSTRUCT *vstruct);
Include pictor.h
Description This function fills vstruct with information that
reflects the display configuration at the time of
the last call to initvideo. initvideo must have
28
PICTOR User's Guide and Reference
been previously called in order for getvconfig to
return meaningful values.
The VIDEOSTRUCT structure contains the following
members:
Member Description
--------------------------------------------------
unsigned segment The display segment address.
Will be one of the constants
COLOR_SEG or MONO_SEG, which are
defined in PICTOR.H.
int snowcheck TRUE if snow checking is
enabled, FALSE otherwise. (See
the snowcheckoff macro for a
description of snow checking.)
int rows The number of text rows on the
display.
int columns The number of text columns on
the display.
int mode The video mode.
int page The active video page.
int colorsupport TRUE if the display adapter
supports color, FALSE otherwise.
Note that some systems may have
a color adapter with a non-color
display (such as composite
monitors and some LCD's). For
this reason, many applications
allow the user to specify that
only black and white attributes
be used.
See also initvideo
Example For an example of getvconfig, please see the
xprintf example.
getwcol, getwrow
---------------------------------------------
Syntax int getwcol(void);
int getwrow(void);
Include pictor.h
Description The getwcol and getwrow functions return the
current column and row position of the active
window pane.
Returns The current position of the active window pane as
described above. If there is no active window
pane, both functions return 1.
29
PICTOR User's Guide and Reference
See also getvcol, getvrow, setwpos
getwcols, getwrows
---------------------------------------------
Syntax int getwcols(void);
int getwrows(void);
Include pictor.h
Description The getwcols and getwrows macros return the number
of columns and rows in the active window pane. The
values returned are the number of columns or rows
inside the window pane not counting the window
frame or pane border.
Returns The number of columns or rows in the active window
pane. The return values are undefined if there is
no active window pane.
See also getwcol, getwrow
helpclose
---------------------------------------------
Syntax void helpclose(void);
Include pictor.h
Description This function destroys all data objects associated
with the current help file, frees the memory used
for those data objects and disables the help
system. Since MS-DOS automatically reclaims any
memory allocated by your application when the
application terminates, you do not need to call
this function. However, you can call this function
if you need to recover memory allocated by the
help system before your application terminates.
See also helpopen, helprun
helpopen
---------------------------------------------
Syntax void helpopen(char *filename,
COLORSTRUCT *hlpcolors,
COLORSTRUCT *msgcolors);
Include pictor.h
Description This function specifies the filename and color
attributes to be used by the help system when
helprun is called. In effect, helpopen activates
the help system. filename specifies the name of
30
PICTOR User's Guide and Reference
the help file. The help file must be compatible
with the format created by the help compiler
included with the PICTOR tool kit. hlpcolors
points to a COLORSTRUCT structure that contains
the colors to be used to display the help screen.
msgcolors points to a COLORSTRUCT structure that
contains the colors to be used to display the help
index and any help messages that must be
displayed.
If helpopen is called after help has already been
enabled, helpopen begins by calling helpclose to
destroy any data objects associated with the
previous help file. It should be pointed out that
helpopen doesn't actually open any files. The help
file is not accessed until helprun is called and
helprun never lets any files remain open between
calls.
See also helpclose, helprun
Example For an example of helpopen, please see the helprun
example.
helpgetcontext, helpsetcontext
---------------------------------------------
Syntax char *helpgetcontext(void);
void helpsetcontext(char *context);
Include pictor.h
Description The helpgetcontext and helpsetcontext macros get
and set the current help context. These functions
aid in the development of applications with
context-sensitive help.
Many PICTOR library routines that get input from
the user (such as messagebox and editbox) call
helprun if the user presses <F1> (assuming that
the help system has been enabled using helpopen).
The help context is a pointer to a help topic
string that gets passed to helprun by these
functions. Note that the help context does not
affect calls made directly to helprun by your
application.
Returns helpgetcontext returns a pointer to the current
help context string.
See also helpopen, helprun
helprun
31
PICTOR User's Guide and Reference
---------------------------------------------
Syntax int helprun(char *topic);
Include pictor.h
Description Runs the help system. topic is a pointer to a help
topic string and should match a @BEGIN label
defined in the help file. If topic is NULL, the
help index is displayed and the user can select
from any topic in the help file. Note that you
must call helpopen to activate the help system
prior to calling helprun. See the tutorial section
for a discussion about creating on-line help.
Note that since messagebox and listbox can be
called from helprun, and helprun can be called
from messagebox and listbox, helprun simply calls
beep if helprun gets called recursively (gets
called when it is already active).
Returns TRUE if help was successful, FALSE if an error
occurred. Note that if an error occurred, helprun
displays a message to notify the user of the
nature of the error.
See also helpclose, helpopen, helpsetcontext
Example
/*
** HELPRUN.C: Help file viewer.
*/
#include <stdio.h>
#include <pictor.h>
COLORSTRUCT helpcolors = {
foreback(BLACK,WHITE),
foreback(BOLD|WHITE,WHITE),
foreback(WHITE,BLACK),
foreback(BLACK,BLACK)
};
COLORSTRUCT msgcolors = {
foreback(BLACK,CYAN),
foreback(BOLD|WHITE,CYAN),
foreback(WHITE,BLACK),
foreback(BOLD|WHITE,BLACK)
};
void main(int argc,char *argv[])
{
/* check command-line arguments */
if(argc != 2) {
32
PICTOR User's Guide and Reference
printf("Usage:\tHELPRUN <hlpfile>\n");
return;
}
/* initialize library */
initvideo();
cls();
initstatus(25,helpcolors.normal);
/* capture Ctrl-Break & critical error interrupts */
hookints(&msgcolors);
/* activate help system */
helpopen(argv[1],&helpcolors,&msgcolors);
/* run help starting with help index */
helprun(NULL);
/* restore screen */
vcolor(foreback(WHITE,BLACK));
cls();
}
hookints
---------------------------------------------
Syntax int hookints(COLORSTRUCT *colors);
Include pictor.h
Description This function installs interrupt handlers for
Ctrl-C, Ctrl-Break and critical errors (interrupts
0x23, 0x1B and 0x24). The handlers for Ctrl-C and
Ctrl-Break simply return. The handler for critical
errors calls messagebox to display an error
message with the MB_RETRYABORT flag. colors points
to a COLORSTRUCT structure that contains the
colors that will be passed to messagebox during
critical errors.
hookints makes your application more robust by
preventing premature termination due to the user
pressing <Ctrl-Break>, or aborting a critical
error. In addition, the critical error handler
prevents the default MS-DOS critical error handler
from writing to the display, and errors can be
handled in a consistent, user-friendly way.
hookints registers unhookints with the ANSI C
library function atexit. This causes unhookints to
be called (and the installed handlers to be
uninstalled) upon normal program termination.
33
PICTOR User's Guide and Reference
Returns 0 if the function is successful or -1 if an error
occurred.
See also unhookints
Example For an example of hookints, please see the helprun
example.
hputs
---------------------------------------------
Syntax void hputs(char *string, int hcolor);
Include pictor.h
Description The hputs function prints a string that contains
highlighted characters. This function is useful
for printing menu selections with embedded
"hotkeys", and is used by several PICTOR library
functions such as runmenu and messagebox.
hputs prints string using the current default
colors. Any characters that are preceded by a
tilde character (~) are printed using hcolor. The
tilde character is not printed.
See also gethotkey, hstrlen
Example
/*
** HPUTS.C: Writes a string using hputs.
*/
#include <pictor.h>
void main()
{
/* initialize library */
initvideo();
setvpos(5,10);
vcolor(foreback(BOLD+CYAN,BLUE));
cls();
hputs("~Retry, ~Abort, ~Fail, ~F~1=Help",
foreback(BOLD+WHITE,BLUE));
}
hstrlen
---------------------------------------------
Syntax int hstrlen(char *string);
34
PICTOR User's Guide and Reference
Include pictor.h
Description This function returns the length of a string as
printed by hputs. This is the number of characters
in string, not counting the tilde character (~).
Returns The number of characters in string that would be
displayed by hputs.
See also hputs
initstatus
---------------------------------------------
Syntax void initstatus(int row, int color);
Include pictor.h
Description This function specifies parameters used by the
statusbar function to display the status bar. row
specifies the status row and color specifies the
status bar color. By default, the status bar
appears on row 25 with a color attribute equal to
foreback(BLACK, WHITE).
See also statusbar
initvideo
---------------------------------------------
Syntax void initvideo(void);
Include pictor.h
Description initvideo determines the type and configuration of
the host display adapter, and initializes internal
variables appropriately. This function should be
called at the start of your program. IMPORTANT:
Many PICTOR library routines require that
initvideo has already been called in order for
those routines to work correctly.
Use getvconfig to retrieve information about the
current display configuration.
See also getvconfig, snowcheckoff
installclock
---------------------------------------------
Syntax int installclock(int row, int column, int color);
Include pictor.h
35
PICTOR User's Guide and Reference
Description This function puts a clock on the screen at the
location specified by row and column using the
color attribute specified by color. The clock is
automatically updated to display the current time.
When installclock is called for the first time, it
registers removeclock with the ANSI C library
function atexit. This causes removeclock to be
called upon normal program termination. Note that
when your program terminates, it is possible for
the clock to display itself between the time your
program clears the screen and the time removeclock
is called by atexit. In this situation, you might
want to call removeclock explicitly before your
program clears the screen.
Returns 0 if successful or -1 if an error occurred.
See also removeclock
Example
/*
** INSTCLCK.C: Installs an on-screen clock.
*/
#include <pictor.h>
void main()
{
/* initialize library */
initvideo();
cls();
installclock(1,1,foreback(BLACK,WHITE));
setvpos(5,5);
vputs("Press any key to move clock");
kbdread();
removeclock();
cls();
installclock(1,74,foreback(BLACK,WHITE));
setvpos(5,5);
vputs("Press any key to exit");
kbdread();
}
kbdedit
---------------------------------------------
Syntax int kbdedit(char *buffer, int row,
int column, int width,int maxlength,
36
PICTOR User's Guide and Reference
COLORSTRUCT *colors);
Include pictor.h
Description This function allows the user to edit a line of
text. buffer is where the text will be stored. row
and column specify the screen location. width
specifies how many display columns kbdedit will
use for editing. maxlength specifies the maximum
number of characters the string can contain. If
maxlength is greater than width, the text is
scrolled horizontally as the string grows longer
than the edit area. buffer must be big enough to
hold maxlength + 1 characters.
If buffer already contains a string, kbdedit
highlights the existing text to indicate that it
is selected. If the user types an editing key
(such as <Backspace>, <Left>, or <End>), the
selected text becomes unselected and the user can
modify the existing string. Otherwise, if the user
begins typing a new string, it automatically
replaces the selected text.
kbdedit uses an internal buffer of 129 bytes.
buffer should never contain a string of more than
128 characters or the internal buffer will
overflow. If maxlength is greater than 128,
kbdedit uses 128 as the maximum length.
See also kbdread, editbox
Returns TRUE if the user pressed <Enter>, or FALSE if the
user pressed <Escape>. If the user pressed
<Escape>, the original contents of buffer are not
modified.
Example
/*
** KBDEDIT.C: Lets the user edit a string
** using kbdedit.
*/
#include <stdio.h>
#include <pictor.h>
COLORSTRUCT colors = {
foreback(BLACK,WHITE),
0x00, /* not used by kbdedit() */
foreback(WHITE,BLACK),
0x00 /* not used by kbdedit() */
};
37
PICTOR User's Guide and Reference
char buffer[128];
void main()
{
int i;
/* initialize library */
initvideo();
/* clear screen */
vcolor(foreback(BOLD+WHITE,BLUE));
cls();
setvpos(3,5);
vputs("KbdEdit: [");
setvpos(3,15 + 25);
vputc(']');
i = kbdedit(buffer,3,15,25,127,&colors);
/* restore screen */
vcolor(foreback(WHITE,BLACK));
cls();
/* print result */
if(i == TRUE)
printf("You entered: %s\n",buffer);
else
printf("You pressed <Escape>\n");
}
kbdflush
---------------------------------------------
Syntax int kbdflush(void);
Include pictor.h
Description This function flushes any keystrokes waiting in
the keyboard buffer or stuffed using kbdpush.
Returns The number of keystrokes that were in the keyboard
buffer before it was flushed.
See also kbdread, kbdready
kbdpush
---------------------------------------------
Syntax void kbdpush(int key);
Include pictor.h
38
PICTOR User's Guide and Reference
Description Stuffs key into the keyboard buffer so that it is
the next key returned by kbdread. Only one key can
be stuffed at a time. If kbdpush is called twice
with no intervening call to kbdread, the first key
pushed will be lost.
See also kbdread, kbdready
kbdread
---------------------------------------------
Syntax int kbdread(void)
Include pictor.h
Description This function retrieves the next available
keystroke. The value returned indicates which key
was pressed. The low byte is the key's ASCII code
(or 0 if the key has no ASCII code) and the high
byte is the key's scan code. The returned value is
the same as the one returned by the ROM BIOS
interrupt 16h, function 00h except for <Ctrl-
Break>. kbdread returns 0xFFFF for <Ctrl-Break>
while the ROM BIOS returns 0x0000.
PICTOR.H defines constants for many keyboard
codes.
Returns The next available keystroke as described above.
See also escpressed, kbdpush, kbdready, kbdshift
kbdready
---------------------------------------------
Syntax int kbdready(void)
Include pictor.h
Description This function indicates if there are any
keystrokes waiting in the keyboard buffer. If
there are keystrokes waiting, the next available
keystroke (as returned by kbdread) is returned_but
not removed_from the keyboard buffer. Otherwise, 0
is returned.
Returns The next available keystroke as described above,
or 0 if no keystrokes are available.
See also kbdpush, kbdread
kbdshift
---------------------------------------------
39
PICTOR User's Guide and Reference
Syntax int kbdshift(void);
Include pictor.h
Description This function returns the state of various
keyboard shift keys as follows:
Bit Meaning (if set)
---------------------------------------------
0 Right shift key is down
1 Left shift key is down
2 Ctrl key is down
3 Alt key is down
4 Scroll lock is on
5 Num Lock is on
6 Caps Lock is on
7 Insert is on
Returns The current shift status as described above.
See also kbdread
Example
/*
** KBDSHIFT.C: Displays the state of the shift keys until
** the user presses <Escape>.
*/
#include <pictor.h>
char *labels[] = {
"Right shift key down",
"Left shift key down",
"Ctrl-key down",
"Alt key down",
"Scroll Lock on",
"Num Lock on",
"Caps Lock on",
"Insert on",
};
void main()
{
int i,shiftstate;
/* initialize library */
initvideo();
/* clear screen and hide cursor */
cls();
showcurs(FALSE);
40
PICTOR User's Guide and Reference
setvpos(10,1);
vputs("Press <Escape> to end");
while(!kbdready() || kbdread() != ESCAPE_KEY) {
shiftstate = kbdshift();
for(i = 0;i < 8;i++) {
setvpos(1 + i,1);
xprintf(vputs,"%s: %s",labels[i],
(shiftstate & (0x01 << i)) ? "Yes" : "No ");
}
}
/* restore screen */
showcurs(TRUE);
cls();
}
listbox
---------------------------------------------
Syntax int listbox(char **items, int numitems,
int *selection, char *title,
COLORSTRUCT *colors);
Include pictor.h
Description This function allows the user to select from an
array of items. items is the address of an array
of string pointers; these strings are the items
that will appear in the list box. numitems is the
number of items in the array. selection points to
an integer that contains the initial selection. If
selection points to an integer with a value of 0,
the first item in the list is highlighted when
listbox opens. If the user pressed <Return>, the
integer pointed to by selection is modified to
indicate which item was selected; if the user
pressed <Escape>, the integer pointed to by
selection is not modified. title is the title
given to the window (use NULL for no title) and
colors is a pointer to a COLORSTRUCT structure
that contains the colors used to display the
window.
Returns TRUE if the user pressed <Return>, FALSE if the
user pressed <Escape> or if numitems is 0. You can
use escpressed to determine if the user pressed
<Escape>.
See also escpressed, pickfile
Example
/*
41
PICTOR User's Guide and Reference
** LISTBOX.C: Lets the user select from a list
** of items.
*/
#include <stdio.h>
#include <pictor.h>
#define NUM_ITEMS 7
char *items[NUM_ITEMS] = {
"Apples",
"Bananas",
"Carrots",
"Grapes",
"Kiwi",
"Raisins",
"Watermelon",
};
COLORSTRUCT colors = {
foreback(BOLD+CYAN,BLUE),
foreback(BOLD+WHITE,CYAN),
foreback(BLACK,WHITE),
foreback(BOLD+WHITE,WHITE)
};
void main()
{
char buffer[45];
int sel = 0;
/* initialize the library */
initvideo();
if(listbox(items,NUM_ITEMS,&sel,"Fruit",&colors)) {
sprintf(buffer,"You selected %s",items[sel]);
messagebox(buffer,NULL,MB_OK,&colors);
}
else {
messagebox("You pressed <Escape>",NULL,MB_OK,
&colors);
}
}
messagebox
---------------------------------------------
Syntax int messagebox(char *message, char *title,
int flags,COLORSTRUCT *colors);
Include pictor.h
Description messagebox displays a window with a message and
allows the user to select from 1 or more
predefined responses. message is the message
42
PICTOR User's Guide and Reference
displayed in the window. message can contain new-
line ('\n') characters for multi-line messages.
title is the title given to the window (use NULL
for no title). colors is a pointer to a
COLORSTRUCT structure that contains the colors
used to display the window. flags determines the
responses made available to the user and can be
any one of the following constants defined in
PICTOR.H:
Constant Meaning
---------------------------------------------
MB_OK The user is given a single
selection labeled OK.
MB_OKCANCEL The user can select between OK and
Cancel.
MB_RETRYCANCEL The user can select between Retry
and Cancel.
MB_RETRYABORT The user can select between Retry
and Abort.
MB_YESNO The user can select between Yes and
No.
MB_YESNOCANCEL The user can select between Yes, No
and Cancel.
Returns If a single response is available as with MB_OK,
messagebox always returns 0. If two responses are
available as with MB_OKCANCEL, messagebox returns
1 if OK is selected and 0 if Cancel is selected.
If three responses are available as with
MB_YESNOCANCEL, messagebox returns 2 if Yes is
selected, 1 if No is selected and 0 if Cancel is
selected. Also, if the user presses <Escape>,
messagebox returns 0. You can use the escpressed
macro determine if 0 was returned because the
right-most response was selected or <Escape> was
pressed.
See also escpressed
Example
/*
** MSGBOX.C: Takes action based on the user's response
** to a message box.
*/
#include <pictor.h>
COLORSTRUCT msgcolors = {
foreback(BOLD+WHITE,RED),
foreback(BOLD+YELLOW,RED),
foreback(BLACK,WHITE),
foreback(BOLD+WHITE,WHITE)
43
PICTOR User's Guide and Reference
};
void main()
{
/* initialize library */
initvideo();
/* clear screen if user selects yes */
if(messagebox("Do you want the screen cleared?",
"Question",MB_YESNO,&msgcolors)) {
vcolor(foreback(WHITE,BLACK));
cls();
}
}
multiedit
---------------------------------------------
Syntax int multiedit(MEDITSTRUCT *items,
int numitems, char *title,
COLORSTRUCT *colors);
Include pictor.h
Description This function creates an edit box with multiple
edit fields. The user can move between fields by
pressing <Tab> and <Shift-Tab>. items points to
the first element of an array of MEDITSTRUCT
structures. The MEDITSTRUCT structures describe
each field of the multi-edit box and contain the
following members:
Member Description
---------------------------------------------
char *prompt Prompt message for this field
char *buffer Buffer to store text
int maxlen Maximum number of characters
allowed in this field
numitems is the number of MEDITSTRUCT structures
in the array and, therefore, the number of fields
in the edit box. title is the title given to the
window (use NULL for no title). colors points to a
COLORSTRUCT structure that contains the colors
used to display the window.
Returns TRUE if the user pressed <Enter>, FALSE if the
user pressed <Escape>. Unlike kbdedit, some fields
may have been modified when this function returns
even if <Escape> was pressed.
See also editbox, kbdedit
44
PICTOR User's Guide and Reference
Example
/*
** MULTEDIT.C: Uses multiedit to display a dialog
** box with multiple edit fields.
*/
#include <stdio.h>
#include <pictor.h>
#define MAX_LEN 25
char buff1[MAX_LEN + 1];
char buff2[MAX_LEN + 2];
#define NUM_ITEMS 2
MEDITSTRUCT items[NUM_ITEMS] = {
{ "Find What",buff1,MAX_LEN },
{ "Replace with",buff2,MAX_LEN }
};
COLORSTRUCT colors = {
foreback(BLACK,WHITE),
foreback(BOLD+WHITE,WHITE),
foreback(WHITE,BLACK),
foreback(BOLD+WHITE,BLACK)
};
void main()
{
char buffer[81];
/* initialize library */
initvideo();
if(multiedit(items,NUM_ITEMS,"Replace",&colors)) {
sprintf(buffer,
"You entered:\n\"%s\"\nand:\n\"%s\"",
buff1,buff2);
messagebox(buffer,NULL,MB_OK,&colors);
}
else {
messagebox("You pressed <Escape>",NULL,MB_OK,
&colors);
}
}
pause
---------------------------------------------
Syntax void pause(int duration);
Include pictor.h
45
PICTOR User's Guide and Reference
Description pause returns after the specified period of time
has elapsed. duration specifies the pause duration
in approximately 18ths of a second (a duration of
18 is just under one second).
pickfile
---------------------------------------------
Syntax char *pickfile(char *filespec, char *title,
COLORSTRUCT *colors);
Include pictor.h
Description This function uses listbox to let the user select
from a sorted list of files. filespec masks which
files to include in the selection. title specifies
the window title passed to listbox (use NULL for
no title). colors points to a COLORSTRUCT
structure that contains the colors used to display
the window.
If the user selects a file, pickfile returns a
pointer to the file name. You should make use of
the pointer as soon as possible since another call
to pickfile can change the data it points to.
Returns A pointer to the selected filename or NULL if the
user pressed <Escape>, or if an error occurred (in
which case pickfile displays a message notifying
the user). You can use the escpressed macro to
determine if the user pressed <Escape>.
See also escpressed, listbox
Example
/*
** PICKFILE.C: Lets the user select a file in the
** current directory.
*/
#include <stdio.h>
#include <pictor.h>
COLORSTRUCT colors = {
foreback(BOLD+CYAN,BLUE),
foreback(BOLD+WHITE,CYAN),
foreback(BLACK,WHITE),
foreback(BOLD+WHITE,WHITE)
};
void main()
{
char buffer[45];
46
PICTOR User's Guide and Reference
char *cptr;
/* initialize the library */
initvideo();
cptr = pickfile("*.*","Pick a File",&colors);
if(cptr != NULL) {
sprintf(buffer,"You selected %s",cptr);
messagebox(buffer,NULL,MB_OK,&colors);
}
else {
messagebox("You pressed <Escape>",NULL,MB_OK,
&colors);
}
}
popcurs, pushcurs
---------------------------------------------
Syntax int popcurs(void);
int pushcurs(void);
Include pictor.h
Description These functions work together to save and restore
the cursor state. pushcurs saves the current
hardware text cursor position and cursor type.
popcurs restores the cursor position and type to
what it was before the last call to pushcurs.
Returns Both functions return TRUE if they are successful.
pushcurs returns FALSE if there is no more room to
save the cursor; popcurs returns FALSE if there is
no saved cursor to pop.
popstatus, pushstatus
---------------------------------------------
Syntax int popstatus(void);
int pushstatus(void);
Include pictor.h
Description These functions work together to save the status
bar and then restore it. pushstatus save the
contents of, and then clears, the status bar.
popstatus restores the status bar to how it
appeared prior to the last call to pushstatus.
Returns Both function return TRUE if they are successful.
pushstatus returns FALSE if there is no more room
to save the status bar. popstatus returns FALSE if
there is no saved status bar to pop.
47
PICTOR User's Guide and Reference
prnputc
---------------------------------------------
Syntax int prnputc(char c);
Include pictor.h
Description This function writes c to the standard list device
(printer).
Returns 0 if successful or a non-zero value if an error
occurred.
See also prnputs, prnwrite
prnputs
---------------------------------------------
Syntax int prnputs(char *string);
Include pictor.h
Description This function writes string to the standard list
device (printer).
Returns 0 if successful or a non-zero value if an error
occurred.
See also prnputc, prnwrite
prnwrite
---------------------------------------------
Syntax int prnwrite(char *buffer, int count);
Include pictor.h
Description This function writes a series of characters to the
standard list device (printer). buffer is where
the characters are stored and count is the number
of characters to be written.
Returns 0 if successful or a non-zero value if an error
occurred.
See also prnputc, prnputs
putscrn
---------------------------------------------
Syntax void putscrn(int *buffer, int top, int left,
int height, int width);
Include pictor.h
48
PICTOR User's Guide and Reference
Description Copies the contents of buffer to the display area
described by the last four arguments. putscrn is
useful for closing a window by writing the
original contents of the screen (saved with
getscrn) back to the screen. Since wclose
automatically calls this function to close a
window, you won't need to call putscrn unless you
are creating customized windowing routines.
See also getscrn
readtree
---------------------------------------------
Syntax NODE *readtree(BYTE *buffer);
Include compress.h
Description Builds a compression code tree from a buffer
created with writetree.
Returns The root node to the compression code tree or NULL
if there was not enough memory.
See also compress, freetree, gettree, uncompress, writetree
Example For an example of readtree, please see the
uncompress example.
removeclock
---------------------------------------------
Syntax int removeclock(void);
Include pictor.h
Description Removes the on-screen clock previously installed
by installclock. Note that installclock
automatically registers removeclock with the ANSI
C library routine atexit. This causes removeclock
to be called upon normal program termination. As a
result, you do not need to call removeclock.
However, you might call this function if you want
to stop the clock before your program terminates
or if you want to re-install the clock at a
different location.
The installclock function traps interrupt 0x1C.
comopen also traps interrupt 0x1C. If you are
using both functions and you need to manually
remove or close either one, they must be
uninstalled in the reverse order that they were
installed.
49
PICTOR User's Guide and Reference
Returns 0 if successful or -1 if an error occurred.
See also installclock
Example For an example of removeclock, please see the
installclock example.
runmenu
---------------------------------------------
Syntax int runmenu(MAINMENU *menu,
COLORSTRUCT *maincolors,
COLORSTRUCT *subcolors);
Include pictor.h
Description Runs the main menu specified by menu. maincolors
and subcolors point to COLORSTRUCT structures that
contain the colors used to display the mainmenu
and submenus respectively.
runmenu should be used in your program's main loop
(see the example program below). If the next
available keystroke is relevant to the current
menu context, it is processed by runmenu and 0 is
returned. Otherwise, the code for the keystroke is
returned so that it can be processed by your
program. See kbdread for a description of the
keyboard codes.
Returns The keyboard code if the last key pressed was not
processed by the main menu, or 0 if it was.
See also kbdread, showmenu
Example
/*
** RUNMENU.C: Demonstrates use of the PICTOR
** menu system.
*/
#include <stdio.h>
#include <pictor.h>
/* set mainloop = FALSE to terminate main loop */
int mainloop = TRUE;
VIDEOSTRUCT vstruct;
COLORSTRUCT menucolors = {
foreback(BLACK,CYAN),
foreback(BOLD+WHITE,CYAN),
foreback(BOLD+CYAN,BLUE),
50
PICTOR User's Guide and Reference
foreback(BOLD+WHITE,BLUE)
};
/* give function references for menu tables */
void sample(void);
void terminate(void);
SUBMENU filemenu[] = {
{ "~New F2",
"Create a new file",NULL,sample },
{ "~Open...",
"Open an existing file",NULL,sample },
{ "~Save",
"Save the current file",NULL,sample },
{ "Save ~As",
"Save the current file with a different name",
NULL,sample },
SUBMENU_DIVIDER,
{ "E~xit","Exit to DOS",NULL,terminate },
END_SUBMENU
};
SUBMENU editmenu[] = {
{ "~Cut Shift-Del",
"Move text to clipboard",NULL,sample },
{ "C~opy",
"Copy text to clipboard",NULL,sample },
{ "~Paste",
"Paste text from clipboard",NULL,sample },
END_SUBMENU
};
MAINMENU mainmenu[] = {
{ "~File","File operations menu",NULL,filemenu },
{ "~Edit","Edit operations menu",NULL,editmenu },
END_MAINMENU
};
void sample(void)
{
beep();
}
void terminate(void)
{
mainloop = FALSE;
}
void main()
{
int i;
/* initialize library */
initvideo();
51
PICTOR User's Guide and Reference
getvconfig(&vstruct);
/* hide text cursor */
showcurs(FALSE);
/* Default shadow color is white on black. Since */
/* our desktop is white on black, we need to make */
/* shadows darker in order for them to show up */
_PL_shadowcolor = foreback(BOLD+BLACK,BLACK);
/* create desktop */
for(i = 2;i < vstruct.rows;i++) {
setvpos(i,1);
vrepc('\xB1',vstruct.columns);
}
showmenu(mainmenu,&menucolors,FALSE);
initstatus(vstruct.rows,menucolors.normal);
statusbar("<Alt>=Menus <F10>=Exit to DOS");
while(mainloop) {
switch(runmenu(mainmenu,&menucolors,&menucolors)) {
case 0: /* keystroke processed by runmenu */
break;
case F2_KEY:
sample();
break;
case F10_KEY:
mainloop = FALSE;
break;
default:
beep();
break;
}
}
/* restore screen */
vcolor(foreback(WHITE,BLACK));
showcurs(TRUE);
cls();
}
scroll
---------------------------------------------
Syntax void scroll(int lines, int top, int left,
int height, int width);
Include pictor.h
Description This function scrolls the area described by top,
bottom, height, and width. lines specifies how far
each row is scrolled. If lines is positive the
area is scrolled up, if lines is negative the area
52
PICTOR User's Guide and Reference
is scrolled down, and if lines is zero the
specified area is cleared.
See also cls, wclear
setcurs
---------------------------------------------
Syntax void setcurs(int row, int column);
Include pictor.h
Description This function sets the position of the hardware
text cursor. Coordinates are 1-based so 1,1 refers
to the top, left corner of the screen. Note that
PICTOR routines use their own logical cursor and
are not effected by the location of the hardware
text cursor.
See also popcurs, pushcurs, setvpos, synccurs, setwpos
setcurstype
---------------------------------------------
Syntax void setcurstype(int type);
Include pictor.h
Description Sets the starting and ending scan lines for the
hardware text cursor. The upper byte of type
specifies the starting scan line and the lower
byte specifies the ending scan line.
See also getcurstype, popcurs, pushcurs, showcurs
seterrorbeep
---------------------------------------------
Syntax void seterrorbeep(int state);
Include pictor.h
Description The seterrorbeep enables or disables the beep
function. If state is FALSE, beep is disabled, if
state is TRUE, beep is enabled. Many PICTOR
library functions call beep to alert the user
(usually because an invalid key was pressed).
seterrorbeep effectively disables or enables error
beeping for these functions.
See also beep
setframe, setdoubleframe, setsingleframe
53
PICTOR User's Guide and Reference
---------------------------------------------
Syntax void setframe(char topbottom, char sides,
char topleft, char topright, char bottomleft,
char bottomright);
void setdoubleframe(void)
void setsingleframe(void);
Include pictor.h
Description The setframe routines describe the type of lines
used by the frame function. The arguments to
setframe specify the character to be used for each
of the frame elements: topbottom (top and bottom),
sides (left and right sides), topleft, topright,
bottomleft, and bottomright (the corners of the
frame). setdoubleframe and setsingleframe are
simply macros that call setframe with arguments
for a standard double-line frame and single-line
frame respectively.
Note that subsequent calls to frame will make use
of the modified frame style, including internal
library routines that call frame such as wopen and
runmenu.
See also frame
setvpos
---------------------------------------------
Syntax void setvpos(int row, int column);
Include pictor.h
Description setvpos sets the logical cursor position. PICTOR
library routines use their own logical cursor
position instead of the hardware text cursor. Use
this function to set that position. row and column
are 1-based; therefore, the top, left corner of
the screen is at 1,1.
See also getvcol, getvrow, setcurs, syncvpos, setwpos
Example For an example of setvpos, please see the center
example.
setwpane
---------------------------------------------
Syntax int setwpane(int handle);
Include pictor.h
54
PICTOR User's Guide and Reference
Description This functions sets the active window pane for the
currently active window. handle is a handle that
was returned by wpane when the window pane was
created. Every window has at least one window
pane. The original pane (the only pane if the
window only has one) has a handle value of 0.
Returns TRUE if the specified window pane is successfully
selected, FALSE if handle is not a valid pane
handle.
Also see wpane
Example For an example of setwpane, please see the wpane
example.
setwpos
---------------------------------------------
Syntax void setwpos(int row, int column);
Include pictor.h
Description The setwpos function sets the logical window
position for the active window pane. This
determines the location of the next write using
any of the window output functions. It also
positions the hardware text cursor if the window
was created with the WO_TEXTCURSOR attribute.
Window pane coordinates are 1-based so 1,1
specifies the top, left corner of the window pane.
See also setcurs, setvpos
showcurs
---------------------------------------------
Syntax void showcurs(int state);
Include pictor.h
Description Displays or hides the text cursor. The cursor is
hidden if state is FALSE, restored if it is TRUE.
This function modifies the cursor's starting and
ending scan lines and may not work on every
display. A more reliable way to hide the cursor
may be to position it off the screen. For example,
on a 25x80 display, use setcurs(26,1).
See also setcurs, setcurstype
showmenu
---------------------------------------------
55
PICTOR User's Guide and Reference
Syntax void showmenu(MAINMENU *menu, COLORSTRUCT *colors,
int highlight);
Include pictor.h
Description Displays the main menu specified by menu across
the top of the screen. highlight specifies if the
main menu hotkeys (those letters preceded by a
tilde (~) character) are displayed using the bold
attribute specified in the colors structure. If
highlight is TRUE, the hotkeys are highlighted;
otherwise, they aren't.
See also runmenu
Example For an example of showmenu, please see the runmenu
example.
snowcheckoff
---------------------------------------------
Syntax void snowcheckoff(void);
Include pictor.h
Description Many older CGA displays will snow (flicker random
white spots) when the screen is accessed too
quickly. If initvideo determines that a CGA is the
active adapter, it enables snow checking which
slows down screen access in a manner that
eliminates snow. Some newer CGA's do not snow, and
some users of older CGA's may prefer snow to the
slower performance resulting from snow checking.
Therefore, the snowcheckoff macro is provided so
that snow checking can be disabled. snowcheckoff
has no effect if the current display adapter is
not a CGA.
statusbar
---------------------------------------------
Syntax void statusbar(char *string);
Include pictor.h
Description Displays string on the status bar.
See also clrstatus, initstatus
synccurs
---------------------------------------------
Syntax void synccurs(void);
56
PICTOR User's Guide and Reference
Include pictor.h
Description This function positions the hardware text cursor
so that it matches the current logical cursor
position.
See also syncvpos
syncvpos
---------------------------------------------
Syntax void syncvpos(void);
Include pictor.h
Description This function positions the logical cursor so that
it matches the hardware text cursor.
See also synccurs
tone
---------------------------------------------
syntax void tone(int freq, int duration);
Include pictor.h
Description Sounds the computer's internal speaker. freq
specifies the sound's frequency in cycles per
second. duration specifies how long to play the
tone. Each count of duration is equal to about an
18th of a second (a duration of 18 is just under 1
second).
If you want to sound the computer's internal
speaker to alert the user in a manner that is
consistent with the way many of the internal
library routines do, use the beep function which,
in turn, calls tone. Using beep also allows your
program to disable all warning beeps with a single
call to seterrorbeep.
See also beep
Example
/*
** TONE.C: Plays a series of tones.
*/
#include <pictor.h>
void main()
{
57
PICTOR User's Guide and Reference
int i;
for(i = 110;i <= 880;i += 20)
tone(i,1);
for( ;i >= 110;i -= 20)
tone(i,1);
}
uncompress
---------------------------------------------
Syntax void uncompress(BYTE *inbuff, WORD len,
BYTE *outbuff, NODE *rootnode);
Include compress.h
Description Uncompresses data that was compressed using
compress. inbuff is a pointer to a buffer with the
compressed data. len specifies the length of the
uncompressed (output) data. outbuff is where the
uncompressed data will be written and must be big
enough to hold len characters. rootnode points to
the compression code tree used to compress the
data. Note: rootnode must point to the same code
tree used to compress the data or uncompress will
fail.
See also compress, freetree, gettree, readtree, writetree
Example
/*
** UNCOMP.C: Uncompresses a file that was compressed
** with COMPRESS.C.
*/
#include <stdio.h>
#include <string.h>
#include <compress.h>
BYTE inbuff[BUFSIZ + 200];
BYTE outbuff[BUFSIZ];
void main(int argc,char *argv[])
{
FILE *istream,*ostream;
WORD complen,uncomplen;
NODE *rootnode;
/* check arguments */
if(argc != 3 || !stricmp(argv[1],argv[2])) {
printf("Usage:\tUNCOMP <infile> <outfile>\n");
return;
58
PICTOR User's Guide and Reference
}
/* open files */
istream = fopen(argv[1],"rb");
ostream = fopen(argv[2],"wt");
if(istream == NULL || ostream == NULL) {
printf("File error\n");
return;
}
/* read and uncompress code tree */
complen = getw(istream);
fread(inbuff,sizeof(BYTE),complen,istream);
rootnode = readtree(inbuff);
if(rootnode == NULL) {
printf("Out of memory\n");
return;
}
/* uncompress data and write to file */
while((uncomplen = getw(istream)) != 0) {
complen = getw(istream);
fread(inbuff,sizeof(BYTE),complen,istream);
uncompress(inbuff,uncomplen,outbuff,rootnode);
fwrite(outbuff,sizeof(BYTE),uncomplen,ostream);
}
fclose(istream);
fclose(ostream);
}
unhookints
---------------------------------------------
Syntax int unhookints(void);
Include pictor.h
Description This function uninstalls the Ctrl-C, Ctrl-Break
and critical error handlers that were previously
installed by hookints. Since hookints registers
unhookints with the ANSI C library function
atexit, you do not need to call this function.
However, you can call it if you want to restore
the handlers before your program terminates. There
is no ill-effect from calling unhookints multiple
times.
Returns 0 if successful or -1 if an error occurred.
See also hookints
vcolor
59
PICTOR User's Guide and Reference
---------------------------------------------
Syntax void vcolor(int color);
Include pictor.h
Description Selects the default colors for routines that write
to the screen. Note that a number of library
routines call this function and change the default
colors so you should call vcolor just before
writing to the screen. Use wcolor to change the
default color for the current window pane.
See also foreback, wcolor
vgetca
---------------------------------------------
Syntax int vgetca(void);
Include pictor.h
Description This function returns the character and attribute
from the screen at the current logical cursor
position. The low byte contains the character and
the upper byte contains the attribute.
Returns The character and attribute as described above.
See also vputca
vputa
---------------------------------------------
Syntax void vputa(int color);
Include pictor.h
Description This function writes the color attribute color to
the screen at the current logical position without
disturbing the text at that location.
See also vrepa
vputc
---------------------------------------------
Syntax void vputc(char c);
Include pictor.h
Description vputc writes the character c to the screen at the
current logical cursor position using the current
default colors.
60
PICTOR User's Guide and Reference
See also setvpos, vcolor, wputc
vputca
---------------------------------------------
Syntax void vputca(int value);
Include pictor.h
Description This function writes a character and color
attribute to the screen at the current logical
cursor position. The low byte of value should
contain the character and the high byte should
contain the attribute.
See also vgetca, vputc
vputs
---------------------------------------------
Syntax void vputs(char *string);
Include pictor.h
Description vputs writes a null-terminated string to the
screen at the current logical cursor position.
See also wputs, xprintf
Example For an example of vputs, please see the center
example.
vrepa
---------------------------------------------
Syntax void vrepa(int color, int count);
Include pictor.h
Description This function writes the color attribute specified
by color for the number of columns specified by
count without disturbing the text at that
location. This function is useful for creating
highlight bars.
See also vputa, wrepa
vrepc
---------------------------------------------
Syntax void vrepc(char c, int count);
Include pictor.h
61
PICTOR User's Guide and Reference
Description This function writes c to the screen using vputc
for the number of times specified by count.
See also vputc, wrepc
wclear
---------------------------------------------
Syntax void wclear(void);
Include pictor.h
Description This function clears the contents of the active
window pane and homes the window's logical cursor
(and the hardware text cursor if the window was
created with the WO_TEXTCURSOR attribute). wclear
is always called by wopen when a new window or
window pane is created.
See also cls, scroll
wcleareol
---------------------------------------------
Syntax void wcleareol(void);
Include pictor.h
Description This function clears from the current window pane
position to the end of the window pane. Unlike the
cleareol function, wcleareol does not update the
window pane's logical cursor position.
See also cleareol, wclear
wclose
---------------------------------------------
Syntax void wclose(void);
Include pictor.h
Description This function closes the active window and frees
memory associated with it. If another window was
underneath the active window, that window then
becomes the active window.
See also wcloseall, wopen
Example For an example of wclose, please see the wopen
example.
wcloseall
62
PICTOR User's Guide and Reference
---------------------------------------------
Syntax void wcloseall(void);
Include pictor.h
Description This function closes all open windows and frees
memory associated with them.
See also wclose
wcolor
---------------------------------------------
Syntax void wcolor(int color);
Include pictor.h
Description This function changes the default color attribute
for the active window pane to color. The window
does not change appearance when this function is
called. Instead, it sets the attribute to be used
the next time the window pane is written to.
See also foreback, vcolor
wopen
---------------------------------------------
Syntax int wopen(int top, int left, int height,
int width, int color, int flags);
Include pictor.h
Description Creates and displays a new window. The first four
arguments specify the location and size of the
window. Note that since the window has a border,
the window's display area is actually (height - 2)
(width - 2). color specifies the window's color
attribute. flags specifies optional window
attributes. flags should be 0x00 if the window has
no optional attributes, and multiple attributes
can be combined using a bitwise OR (▌). flags can
be any of the following constants defined in
PICTOR.H:
Constant Meaning
---------------------------------------------
WO_SHADOW The window will be displayed with a
shadow.
WO_STATICMEM Causes wopen to allocate memory for
the window from an internal static
buffer instead of dynamically
allocating memory using malloc. You
should avoid using this flag since
63
PICTOR User's Guide and Reference
the static buffer is relatively
small. Also, windows that have the
WO_STATICMEM attribute cannot have
multiple panes. This flag is used
by some of the library routines
such as messagebox so that they can
display errors when there is no
more system memory, and so that
they can be called from interrupt
handlers (which should never call
malloc). If the WO_STATICMEM
attribute is specified and wopen
cannot allocate enough memory from
the static buffer for the window
buffer, the screen beneath the
window will not be saved and the
window will still appear after it
has been closed. If wopen cannot
allocate enough static memory even
for the window structure itself,
wopen terminates the program by
displaying an error message and
calling exit. wopen never returns
FALSE when WO_STATICMEM is
specified.
WO_TEXTCURSOR This gives the window a hardware
text cursor. The cursor position is
updated whenever the window pane's
logical cursor position changes.
WO_TEXTWRAP Normally, text that extends beyond
the edge of the window is clipped
(not displayed). If the WO_TEXTWRAP
attribute is specified, characters
that extend beyond the edge of the
window wrap around to appear at the
beginning of the next line.
Returns TRUE if the window was successfully created and
displayed, FALSE if there is not enough memory to
create the window.
See also wclose, wtitle
Example
/*
** WOPEN.C: Creates a window and displays some text in it.
*/
#include <pictor.h>
void main()
{
/* initialize library */
64
PICTOR User's Guide and Reference
initvideo();
vcolor(foreback(BOLD+WHITE,BLUE)); cls();
/* create a window and write some text in it */
wopen(5,6,17,70,foreback(BLACK,WHITE),WO_SHADOW);
wputs("Hello, world. wputs() here!\n\nPress any key");
/* wait for user to press a key */
kbdread();
wclose();
/* restore screen */
vcolor(foreback(WHITE,BLACK));
cls();
}
wpane
---------------------------------------------
Syntax int wpane(int direction, int position);
Include pictor.h
Description Splits the active window pane into two panes.
direction specifies the direction of the split and
can be any one of the following constants defined
in PICTOR.H:
Constant Meaning
---------------------------------------------
WP_VERTICAL The current window pane is split
vertically.
WP_HORIZONTAL The current window pane is split
horizontally.
position is the column to split the window if
direction is WP_VERTICAL, or the row to split the
window if direction is WP_HORIZONTAL.
When a window is created using wopen, it has a
single pane that is as big as the window minus the
window frame. The original pane always has a
handle value of 0. wpane divides the current
window pane into two panes and returns a handle to
the new pane. The new pane is considered to be the
pane on the right if direction is WP_VERTICAL, or
the pane on the bottom if direction is
WP_HORIZONTAL. The handle returned by this
function can be passed to setwpane to make the new
window pane active.
If creating the new window pane would result in
either the new window pane or the window pane
being split having less than 3 rows or 3 columns
65
PICTOR User's Guide and Reference
(1 row or column inside the pane's border), wpane
refuses to create the new pane and an error is
returned.
Returns The handle to the new window pane as described
above if successful, or 0 if an error occurred.
See also setwpane
Example
/*
** WPANE.C: Divides a window into many panes.
*/
#include <pictor.h>
void main()
{
int i,handle1,handle2;
/* initialize library */
initvideo();
wopen(5,6,17,70,foreback(BOLD+CYAN,BLUE),0x00);
handle1 = 0;
handle2 = wpane(WP_VERTICAL,35);
for(i = 0;i < 8;i++) {
setwpane(handle1);
xprintf(wputs,"Pane handle: %d",handle1);
handle1 = wpane(WP_HORIZONTAL,3);
setwpane(handle2);
xprintf(wputs,"Pane handle: %d",handle2);
handle2 = wpane(WP_HORIZONTAL,3);
}
kbdread();
wclose();
}
wputc
---------------------------------------------
Syntax void wputc(char c);
Include pictor.h
Description Writes c to the active window pane. c is written
at the location of the active window pane's
logical cursor position using the current window
pane color. Characters extending beyond the edge
of the window pane using wputc are clipped.
66
PICTOR User's Guide and Reference
See also setwpos, vputc, wrepc
wputs
---------------------------------------------
Syntax void wputs(char *string);
Include pictor.h
Description Writes string to the active window pane. string is
written starting at the location of the active
window pane's logical cursor position using the
current window pane color. Characters extending
beyond the edge of the window pane are clipped.
See also setwpos, vputs, xprintf
Example For an example of wputs, please see the wopen
example.
wrepa
---------------------------------------------
Syntax void wrepa(int color, int count);
Include pictor.h
Description Writes the color attribute specified by color to
the active window pane and repeats it for the
number of times specified by count. Printing
begins at the window pane's logical cursor
position. If count extends beyond the edge of the
window pane, the output is clipped.
See also vrepa, setwpos
wrepc
---------------------------------------------
Syntax void wrepc(char c, int count);
Include pictor.h
Description Writes c to the active window pane for the number
of times specified by count. Printing begins at
the window pane's logical cursor position.
Characters extending beyond the edge of the window
pane are clipped.
See also vrepc, setwpos
writetree
67
PICTOR User's Guide and Reference
---------------------------------------------
Syntax WORD writetree(NODE *rootnode, BYTE *buffer);
Include compress.h
Description Writes the compression code tree specified by
rootnode to buffer. The code tree is written so as
to take the minimum number of bytes necessary.
This function is suitable for writing a
compression code tree to a buffer so that it can
be written to a file. The data can later to
converted back to a code tree using readtree. The
required length of buffer varies depending on the
number of characters included in the code tree. A
typical value might be around 90 bytes. Since you
don't know how many bytes will be required, you
should be sure to use a buffer that is larger than
the typical value.
Returns The number of bytes that were written to buffer.
See also compress, freetree, gettree, readtree, uncompress
Example For an example of writetree, please see the
compress example.
wsynccurs
---------------------------------------------
Syntax void wsynccurs(void);
Include pictor.h
Description This function synchronizes the hardware text
cursor position with the current window pane's
logical cursor position. The cursor is moved
inside the window so that its location matches
where text will be written with the next call to a
window output function. If the current window
pane's logical cursor position is not within the
current window pane, the hardware text cursor is
hidden.
See also synccurs, syncvpos
wtitle
---------------------------------------------
Syntax void wtitle(char *string);
Include pictor.h
68
PICTOR User's Guide and Reference
Description Gives the active window pane a title by printing
string centered across the top of the window pane.
If string is NULL, the current title is cleared.
xprintf
---------------------------------------------
Syntax void xprintf(void (*func)(), char *format
[, arguments ]...);
Include pictor.h
Description This function formats a string and sends it to any
function that takes a single string as an
argument. xprintf creates a formatted string using
format and arguments and sends the result to func.
The syntax is the same as for the ANSI C library
function fprintf, but instead if the first
argument specifying a stream, the first argument
specifies a function.
xprintf is designed to handle strings that fit on
one line of the display. Creating lines that are
longer than 132 characters will overflow the
internal buffer.
Example
/*
** XPRINTF.C: Displays a window with information about
** the current display configuration.
*/
#include <pictor.h>
void main()
{
VIDEOSTRUCT vstruct;
/* initialize library */
initvideo();
getvconfig(&vstruct);
/* create window and write information */
wopen(6,11,11,60,foreback(BOLD+WHITE,BLUE),0x00);
xprintf(wputs,"Video segment: %04X\n",
vstruct.segment);
xprintf(wputs,"Snow checking: %s\n",
(vstruct.snowcheck) ? "On" : "Off");
xprintf(wputs,"Text rows: %d\n",vstruct.rows);
xprintf(wputs,"Text columns: %d\n",vstruct.columns);
xprintf(wputs,"Video mode: %d\n",vstruct.mode);
xprintf(wputs,"Display page: %d\n",vstruct.page);
xprintf(wputs,"Color support: %s\n",
69
PICTOR User's Guide and Reference
(vstruct.colorsupport) ? "Yes" : "No");
wputs("\nPress any key...");
/* wait for user to press a key and close window */
kbdread();
wclose();
}
VARIABLES
-------------------------------------------------------------
There are a number of variables that are used internally by the
PICTOR library. Normally, these variables are set through
function calls or through macros. We don't recommend directly
accessing those variables that can be accessed through functions
or macros. However, since the source code is provided with this
package, these variables are documented here in case you need
them.
These variables all begin with _PL_ to indicate that they are
PICTOR Library variables and to minimize the chances of conflict
with symbol names in your application.
Variable Description
------------------------------------------------------------
int _PL_beepfreq Specifies the frequency argument passed
to tone by the beep function. Default
value: 880.
int _PL_beeplen Specifies the duration argument passed
to tone by the beep function. Default
value: 2.
int _PL_breakflag Set by the hookints function's Ctrl-
Break handler when the user presses
<Ctrl-Break>.
int _PL_color Internal color attribute. Set by vcolor.
int _PL_colorsupport TRUE if the host display supports color.
One of the values returned by
getvconfig.
int _PL_columns The number of screen columns. One of the
values returned by getvconfig.
int _PL_comoverflow Set to a non-zero value if the
communications' receive buffer
overflows. Set to 0 by comflush.
int _PL_comtimeout Number of 18ths of a second allowed
between characters by the serial
communications' input and output
routines. Set by comsettimeout and
returned by comgettimeout.
int _PL_editfill Character used by kbdedit to fill blank
edit columns. Default value: '\xFA'.
int _PL_errorbeep The beep function beeps only if this
variable is non-zero. Set by
seterrorbeep.
70
PICTOR User's Guide and Reference
int _PL_escape TRUE if the last key returned by kbdread
was the Escape key. This is the value
returned by escpressed.
char *_PL_helpcontext Pointer to the help topic string used by
some library routines that pass it to
helprun. Set by helpsetcontext and
returned by helpgetcontext.
int (*_PL_helpfunc)(); Points to helprun if help has been
activated, or is set to NULL if help is
not activated. This variable is set and
cleared by helpopen and helpclose
respectively. Library functions that
access the help system check this
variable to see if help is active. This
allows these functions to access help
without causing the help routines to be
linked into your program if your program
doesn't activate help.
int _PL_lbcols Specifies the number of columns in the
list box created by listbox.
int _PL_lbcolwidth Specifies the width of each column in
the list box created by listbox.
int _PL_lbrows Specifies the number of rows in the list
box created by listbox.
int _PL_menurow Determines the screen row used for the
pulldown menus. Default value: 1.
int _PL_mode The current video mode. One of the
values returned by getvconfig.
int _PL_offset Screen offset used by library routines
that write to the display. This variable
is set by setvpos. It is used in
combination with _PL_segment to
calculated the screen address when
writing to the display.
int _PL_page The current video display page. One of
the values returned by getvconfig.
int _PL_pushedkey Variable to store the keystroke pushed
by kbdpush. The variable is set to 0 by
kbdread.
int _PL_rows Number of screen rows. One of the values
returned by getvconfig.
int _PL_segment Display segment. This variable is used
in combination with _PL_offset to
calculate the screen address when
writing to the display. One of the
values returned by getvconfig.
int _PL_shadowcolor Color attribute used to create window
shadows. When a window is created with
the WO_SHADOW attribute, this attribute
is written along the bottom and right
side of the window. The default value is
foreback(WHITE, BLACK) (0x07). You may
want to set this variable to
foreback(BOLD+BLACK, BLACK) (0x08) for a
71
PICTOR User's Guide and Reference
darker shadow, but note that some non-
color systems cannot display bold
attributes.
int _PL_snowcheck TRUE if the activate display adapter is
a CGA. One of the values returned by
getvconfig. Set to FALSE by
snowcheckoff. Warning: Setting this
variable to TRUE can cause unpredictable
results if the active display adapter is
not CGA compatible.
int _PL_statusrow Row used to display the status bar. Set
by initstatus.
int _PL_tabendedit If this variable is TRUE, kbdedit will
act as though <Enter> was pressed when
the user presses <Tab> or <Shift-Tab>.
This variable is used by multiedit to
allow the user to tab between edit
fields.
WINDOW *_PL_winhead Pointer to the active window or NULL if
no windows are active.
int _PL_wintab Specifies the tab displacement for tab
characters written to windows. Default
value: 8.
72