home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Fish 'n' More 2
/
fishmore-publicdomainlibraryvol.ii1991xetec.iso
/
dirs
/
printspool_463.lzh
/
PrintSpool
/
PrintSpool.doc
< prev
next >
Wrap
Text File
|
1991-03-09
|
9KB
|
226 lines
Set your editor's TAB width to 3
««««««««««««««««««««« What's all this then? »»»»»»»»»»»»»»»»»»»»»»
The dissidents prtspool.library provides an extremely easy way to print
graphics and text for any application. It can print ascii text (with imbedded
printer codes) of any length, or dump any part or all of a rastport. It takes
care of opening the printer.device (and associated devices) and manages its
own resources. This library can be opened and used by many applications just
like the intuition or graphics libs. There are examples for C, asm, and Basic.
The library is approx. 2800 bytes, and of course in 68000, so it is very
small and efficient for what it does.
««««««««««««««««««« Big Deal? Why should I care? »»»»»»»»»»»»»»»
Because printers are extremely slow output devices relative to the computer,
a print dump can take a long time. Much of the Amiga's time is spent waiting
for the printer to accept the next bit of data.
The prtspool.library implements print spooling in a manner completely in-
visible to your application. What this means is that, provided that there is
enough memory, the library will make a copy of what you want printed, and
return control back to your application before printing has even started. The
library not only manages all interaction with the printer, it also frees all
resources after printing. Your program could even terminate before the printing
has completed. Furthermore, the library cues up subsequent requests so that if
your program asks the lib to print something else while printing is in progress,
the library will ALSO SPOOL THAT JOB. Control will be returned to your program
immediately, and the lib will start that next job automatically when the
current job finishes.
The net result is that your application need not have to deal with the
printer.device, IOBs, SendIO or DoIO, nor manage resources for print spooling.
Furthermore, a user of your program can be assessing functions while the
prtspool.library handles your print job in the background. Any changes that
the user makes to the program's data will not affect the print because the
lib is using a copy of the data.
In the event that there is not enough memory to spool the print job, the
library will suspend your program until such time as the printer is free, and
the job is completed. Once again, this is invisible to your application.
««««««««««««««««««««««««« NOTES »»»»»»»»»»»»»»»»»»»»»»»»»»»»
The caller of any library functions must be a process (not a spawned task).
Before calling any lib routine except AbortPrint(), you should display some
sort of wait pointer for the user. Upon return, restore your regular pointer.
You may also wish to OffGadget() or RMBTRAP before the call, in the event that
there is not enough memory to print spool, and you don't want the user to touch
gadgets or menus while your program is suspended.
The library uses the preferences settings for printer port, color, margins,
etc. The user (or your program) should adjust these settings before starting a
print job.
A C program should be linked with an assembly of the file "SpoolInterface.asm".
This is the notorius C poot interface to the library. This can be substituted
by PRAGMA statements.
Basic programmers need prtspool.bmap
***************************** AbortPrint() *****************************
SYNOPSIS
AbortPrint();
DESCRIPTION
Aborts all printing including the current dump and all queued requests.
Note that this only affects the prtspool.library jobs, not any other
task's use of the printer device. This is useful if you wish to abort
some spooled printing job after returning from a lib routine.
INPUT
None
RETURN
None
***************************** PrintNullText() *****************************
SYNOPSIS
PrintNullText(flags, window, textPtr);
d0 a0 a1
DESCRIPTION
This prints the passed Null-terminated text. If the text does not end with
a newline char (ascii 10), then a newline is forced at the end of the print
unless the NONEWLINE bit of flags is set. This insures that all output for
the last line is flushed to the printer.
NOTE: Passing a null string to this function will result in a blank line
being printed if NONEWLINE is not set. Otherwise, the null string will
print nothing.
Low byte of flags is the # of additional copies (i.e. 0 means just 1 print).
INPUT
textPtr - a pointer to the null-terminated text to be printed
window - the window where error messages should be posted
flags - low byte is number of additional copies, 2nd byte is flags
NONEWLINE = hex 1000. So for 2 copies with NONEWLINE, pass
hex 1001.
RETURN
None
***************************** PrintText() *****************************
SYNOPSIS
PrintText(flags, textSize, window, textPtr);
d0 d1 a0 a1
DESCRIPTION
This is a lower level function than PrintNullText(). The text does not have
to be null-terminated (and in fact may contain nulls). You must pass the
total number of chars within (size of) the text.
flags is the same as PrintNullText().
NOTE: Passing a textSize of 0 to this function will result in a blank line
being printed if NONEWLINE is not set. Otherwise, nothing is printed.
INPUT
textPtr - a pointer to the null-terminated text to be printed
textSize - size of the block of text to be printed
window - the window where error messages should be posted
flags - low byte is number of additional copies, 2nd byte is flags
RETURN
None
*************************** PrintRawNullText() *****************************
SYNOPSIS
PrintRawNullText(flags, window, textPtr);
d0 a0 a1
DESCRIPTION
This prints the passed Null-terminated text like PrintNullText(). The
difference is that this does a RAWWRITE to the printer device. What this
means is that there is no translation of chars to the proper printer codes
for a printer. The chars are output as is. This is useful if you need to
send a special string of chars to a printer and do not want them to be
misinterpreted as a printer code. For example, you may wish to send raw
"command" strings to a plotter that does not have a proper Preferences
device driver (i.e. you can use the Generic driver).
A newline is NOT forced out at the end of output.
NOTE: Passing a null string to this function will result in nothing being
output.
INPUT
textPtr - a pointer to the null-terminated text to be printed
window - the window where error messages should be posted
flags - low byte is number of additional copies, 2nd byte is flags
RETURN
None
***************************** PrintRawText() *****************************
SYNOPSIS
PrintRawText(flags, textSize, window, textPtr);
d0 d1 a0 a1
DESCRIPTION
This is like PrintText() except that it does a RAWWRITE of the chars and
does not force a newline at the end of the output.
INPUT
textPtr - a pointer to the null-terminated text to be printed
textSize - size of the block of text to be printed
window - the window where error messages should be posted
flags - low byte is number of additional copies, 2nd byte is flags
RETURN
None
***************************** PrintFullWindow() ***************************
SYNOPSIS
PrintFullWindow(flags, window);
d0 a0
DESCRIPTION
This dumps the window's entire rastport to the printer. It allows the user
to choose to remap color #0 (i.e. usually the background color) to white.
If BWFLAG of flags is set, then when the "Remap to White" requester appears,
the window colors 0 and 1 will be temporarily changed to black and white. This
is desirable if you aren't sure that your colormap's colors 0 and 1 aren't
significantly different intensities. Otherwise, the user may not be able to
read the text in the requester. This does not affect the print.
INPUT
window - the window containing the graphics to be dumped (this is also
where error messages will be posted)
flags - low byte is number of additional copies, other bits are for
printing features such as row and column aspect, BW window for
reqs. BWFLAG = hex 10000.
RETURN
None
***************************** PrintWindow() *****************************
SYNOPSIS
PrintWindow(flags, window, Rectangle);
d0 a0 a1
DESCRIPTION
This is a lower level version of PrintFullWindow() which facilitates print-
ing only a portion of the window's rastport.
This dumps that area of the window's rastport as determined by the Rectangle
structure. (The rectangle structure is defined in gfx.h).
INPUT
Rectangle - a pointer to an initialized Rectangle structure
window - the window containing the graphics to be dumped (this is also
where error messages will be posted)
flags - low byte is number of additional copies, other bits are for
printing features such as row and column aspect, BW window for
reqs
RETURN
None