home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / libraries / printspool_393 / printspool.doc < prev    next >
Text File  |  1990-10-28  |  9KB  |  226 lines
  1. Set your editor's TAB width to 3
  2.  
  3.         ««««««««««««««««««««« What's all this then? »»»»»»»»»»»»»»»»»»»»»»
  4.  
  5.     The dissidents prtspool.library provides an extremely easy way to print
  6. graphics and text for any application. It can print ascii text (with imbedded
  7. printer codes) of any length, or dump any part or all of a rastport. It takes
  8. care of opening the printer.device (and associated devices) and manages its
  9. own resources. This library can be opened and used by many applications just
  10. like the intuition or graphics libs. There are examples for C, asm, and Basic.
  11.     The library is approx. 2800 bytes, and of course in 68000, so it is very
  12. small and efficient for what it does.
  13.  
  14.         ««««««««««««««««««« Big Deal? Why should I care? »»»»»»»»»»»»»»»
  15.  
  16.     Because printers are extremely slow output devices relative to the computer,
  17. a print dump can take a long time. Much of the Amiga's time is spent waiting
  18. for the printer to accept the next bit of data.
  19.     The prtspool.library implements print spooling in a manner completely in-
  20. visible to your application. What this means is that, provided that there is
  21. enough memory, the library will make a copy of what you want printed, and
  22. return control back to your application before printing has even started. The
  23. library not only manages all interaction with the printer, it also frees all
  24. resources after printing. Your program could even terminate before the printing
  25. has completed. Furthermore, the library cues up subsequent requests so that if
  26. your program asks the lib to print something else while printing is in progress,
  27. the library will ALSO SPOOL THAT JOB. Control will be returned to your program
  28. immediately, and the lib will start that next job automatically when the
  29. current job finishes.
  30.     The net result is that your application need not have to deal with the
  31. printer.device, IOBs, SendIO or DoIO, nor manage resources for print spooling.
  32. Furthermore, a user of your program can be assessing functions while the
  33. prtspool.library handles your print job in the background. Any changes that
  34. the user makes to the program's data will not affect the print because the
  35. lib is using a copy of the data.
  36.     In the event that there is not enough memory to spool the print job, the
  37. library will suspend your program until such time as the printer is free, and
  38. the job is completed. Once again, this is invisible to your application.
  39.  
  40.  
  41.         ««««««««««««««««««««««««« NOTES »»»»»»»»»»»»»»»»»»»»»»»»»»»»
  42.  
  43.     The caller of any library functions must be a process (not a spawned task).
  44.  
  45.     Before calling any lib routine except AbortPrint(), you should display some
  46. sort of wait pointer for the user. Upon return, restore your regular pointer.
  47. You may also wish to OffGadget() or RMBTRAP before the call, in the event that
  48. there is not enough memory to print spool, and you don't want the user to touch
  49. gadgets or menus while your program is suspended.
  50.  
  51.     The library uses the preferences settings for printer port, color, margins,
  52. etc. The user (or your program) should adjust these settings before starting a
  53. print job.
  54.  
  55.     A C program should be linked with an assembly of the file "SpoolInterface.asm".
  56. This is the notorius C poot interface to the library. This can be substituted
  57. by PRAGMA statements.
  58.     Basic programmers need prtspool.bmap
  59.  
  60.  
  61. ***************************** AbortPrint() *****************************
  62.  
  63. SYNOPSIS
  64.     AbortPrint();
  65.  
  66. DESCRIPTION
  67.     Aborts all printing including the current dump and all queued requests.
  68.     Note that this only affects the prtspool.library jobs, not any other
  69.     task's use of the printer device. This is useful if you wish to abort
  70.     some spooled printing job after returning from a lib routine.
  71.  
  72. INPUT
  73.     None
  74.  
  75. RETURN
  76.     None
  77.  
  78.  
  79. ***************************** PrintNullText() *****************************
  80.  
  81. SYNOPSIS
  82.     PrintNullText(flags, window, textPtr);
  83.                         d0            a0            a1
  84.  
  85. DESCRIPTION
  86.     This prints the passed Null-terminated text. If the text does not end with
  87.     a newline char (ascii 10), then a newline is forced at the end of the print
  88.     unless the NONEWLINE bit of flags is set.    This insures that all output for
  89.     the last line is flushed to the printer.
  90.     NOTE: Passing a null string to this function will result in a blank line
  91.     being printed if NONEWLINE is not set. Otherwise, the null string will
  92.     print nothing.
  93.     Low byte of flags is the # of additional copies (i.e. 0 means just 1 print).
  94.  
  95. INPUT
  96.     textPtr    -    a pointer to the null-terminated text to be printed
  97.     window    -    the window where error messages should be posted
  98.     flags        -    low byte is number of additional copies, 2nd byte is flags
  99.                     NONEWLINE = hex 1000. So for 2 copies with NONEWLINE, pass
  100.                     hex 1001.
  101.  
  102. RETURN
  103.     None
  104.  
  105.  
  106. ***************************** PrintText() *****************************
  107.  
  108. SYNOPSIS
  109.     PrintText(flags, textSize, window, textPtr);
  110.                     d0            d1            a0            a1
  111.  
  112. DESCRIPTION
  113.     This is a lower level function than PrintNullText(). The text does not have
  114.     to be null-terminated (and in fact may contain nulls). You must pass the
  115.     total number of chars within (size of) the text.
  116.     flags is the same as PrintNullText().
  117.     NOTE: Passing a textSize of 0 to this function will result in a blank line
  118.     being printed if NONEWLINE is not set. Otherwise, nothing is printed.
  119.  
  120. INPUT
  121.     textPtr    -    a pointer to the null-terminated text to be printed
  122.     textSize    -  size of the block of text to be printed
  123.     window    -    the window where error messages should be posted
  124.     flags        -    low byte is number of additional copies, 2nd byte is flags
  125.  
  126. RETURN
  127.     None
  128.  
  129.  
  130. *************************** PrintRawNullText() *****************************
  131.  
  132. SYNOPSIS
  133.     PrintRawNullText(flags, window, textPtr);
  134.                             d0            a0            a1
  135.  
  136. DESCRIPTION
  137.     This prints the passed Null-terminated text like PrintNullText(). The
  138.     difference is that this does a RAWWRITE to the printer device. What this
  139.     means is that there is no translation of chars to the proper printer codes
  140.     for a printer. The chars are output as is. This is useful if you need to
  141.     send a special string of chars to a printer and do not want them to be
  142.     misinterpreted as a printer code. For example, you may wish to send raw
  143.     "command" strings to a plotter that does not have a proper Preferences
  144.     device driver (i.e. you can use the Generic driver).
  145.     A newline is NOT forced out at the end of output.
  146.     NOTE: Passing a null string to this function will result in nothing being
  147.     output.
  148.  
  149. INPUT
  150.     textPtr    -    a pointer to the null-terminated text to be printed
  151.     window    -    the window where error messages should be posted
  152.     flags        -    low byte is number of additional copies, 2nd byte is flags
  153.  
  154. RETURN
  155.     None
  156.  
  157.  
  158. ***************************** PrintRawText() *****************************
  159.  
  160. SYNOPSIS
  161.     PrintRawText(flags, textSize, window, textPtr);
  162.                         d0            d1            a0            a1
  163.  
  164. DESCRIPTION
  165.     This is like PrintText() except that it does a RAWWRITE of the chars and
  166.     does not force a newline at the end of the output.
  167.  
  168. INPUT
  169.     textPtr    -    a pointer to the null-terminated text to be printed
  170.     textSize    -  size of the block of text to be printed
  171.     window    -    the window where error messages should be posted
  172.     flags        -    low byte is number of additional copies, 2nd byte is flags
  173.  
  174. RETURN
  175.     None
  176.  
  177.  
  178. ***************************** PrintFullWindow() ***************************
  179.  
  180. SYNOPSIS
  181.     PrintFullWindow(flags, window);
  182.                             d0        a0
  183.  
  184. DESCRIPTION
  185.     This dumps the window's entire rastport to the printer. It allows the user
  186. to choose to remap color #0 (i.e. usually the background color) to white.
  187. If BWFLAG of flags is set, then when the "Remap to White" requester appears,
  188. the window colors 0 and 1 will be temporarily changed to black and white. This
  189. is desirable if you aren't sure that your colormap's colors 0 and 1 aren't
  190. significantly different intensities. Otherwise, the user may not be able to
  191. read the text in the requester. This does not affect the print.
  192.  
  193. INPUT
  194.     window    -    the window containing the graphics to be dumped (this is also
  195.                     where error messages will be posted)
  196.     flags        -    low byte is number of additional copies, other bits are for
  197.                     printing features such as row and column aspect, BW window for
  198.                     reqs. BWFLAG = hex 10000.
  199.  
  200. RETURN
  201.     None
  202.  
  203.  
  204. ***************************** PrintWindow() *****************************
  205.  
  206. SYNOPSIS
  207.     PrintWindow(flags, window, Rectangle);
  208.                     d0            a0            a1
  209.  
  210. DESCRIPTION
  211.     This is a lower level version of PrintFullWindow() which facilitates print-
  212. ing only a portion of the window's rastport.
  213.     This dumps that area of the window's rastport as determined by the Rectangle
  214. structure. (The rectangle structure is defined in gfx.h).
  215.  
  216. INPUT
  217.     Rectangle -    a pointer to an initialized Rectangle structure
  218.     window    -    the window containing the graphics to be dumped (this is also
  219.                     where error messages will be posted)
  220.     flags        -    low byte is number of additional copies, other bits are for
  221.                     printing features such as row and column aspect, BW window for
  222.                     reqs
  223.  
  224. RETURN
  225.     None
  226.