RISCOS Ltd                                                         RISCOS Ltd

          --------------------------------------------------------
          TECHNICAL NOTE: CHANGES TO PRINTING SYSTEM FOR RISC OS 4
          --------------------------------------------------------


   Document: 20000320-006

    Version: 1.00 (07 May 1999) RJW: Initial version
             1.01 (10 May 1999) RJW: Added External Config alias docs
                                     Added Message_PrintConfigure docs
             1.02 (14 May 1999) RJW: Added Message_PrintInterrogate docs
             1.03 (20 Mar 2000) DPT: Reformatted to new tech note style

  Author(s): Robin Watts <robin@riscos.com>


This file documents the changes made to the printing system for RISC OS 4. As
far as possible, the changes are backwardly compatible.


1) EXTENDED STRINGS

Due to the design of the PDumper interface, the combined length of all the
strings in use for a printer has to be less than 256 characters. This is
further compounded by the need to hold flags in the string too.

This situation is then made even worse by the fact that the GSTransed version
of the string (typically about twice length of the unGSTransed string) is
manipulated in BASIC - hence roughly halving this length again.

To solve this problem, various changes have been put through the printing
system:

   * PrintEdit now generates files with a version number of '5' (the version
     number is held in the top 8 bits of the flags value).

   * These files contain 20 additional lines at the end of each 'g_mode:'
     section of the file, 'data1:' to 'data20:'. These lines correspond to
     the 20 string entries in the Graphics mode editing window in PrintEdit,
     and contain GSTransed data for those strings.

   * The old 'data:' string is now encoded as if these 20 strings were all
     empty.

   * The !Printers frontend has now been updated to detect and accept these
     extra lines in the PDF file.

   * The SupportDP and SupportLJ libraries have been updated; in the case
     where the PDF version number < 5 then the PDriver_SetDriver SWI is
     called as before. In the case where the version number is >= 5 the SWI
     is now called with a pointer to the following information block in R6:

        0       Number of entries in the block (currently 20)
        4       Size of block
        8       Offset from start of block to counted data1 string (n)
        12      Offset from start of block to counted data2 string (m)
        16      Offset from start of block to counted data3 string
        ...
        n       Number of chars in the data1 string
        n+1     data1 string (possibly null)
        m       Number of chars in the data2 string
        m+1     data2 string (possibly null)

   * The PDriver module is unchanged - it simply passes this extra
     information onto the PDriverDP module.

   * The PDriverDP module now detects the version number of the PDF in use;
     if >= 5, it copies the extra data into a block of memory allocated from
     the RMA, and stores this information in its workspace just after the
     leftmargin information.

   * When the PDumpers are called therefore, they are presented with 2 extra
     words after the existing config data, which now looks like:

        ...     ...
        256     Configuration word for dumper (as passed in R5)
        260     Pointer to active Printer Dumper
        264     Printer Dumper number (as passed in R1)
        268     Left Margin in Pixels
        272     Pointer to RMA block with extended string information
        276     Size of extended block

   * The PDumpers now output strings from either the standard printer strings
     or from the extended strings depending on the version of the PDF.


Ramifications:

   * All existing PDFs should continue to work with existing PDumpers.

   * New PDFs used with old PDumper modules will cause garbage output, but
     will not crash the the machine.

   * PDFs written with the new !PrintEdit application will require the new
     PDumpers (they give garbage with old ones).

   * Old versions of !Printers should fault new-style PDFs on loading, so
     unless people mix-n-match their modules there should be no problems.

   * Third-Party authors of PDFs must either accept that they can only be use
     with new-style PDumpers, or must carry on using an old PrintEdit.

   * Third-Party authors of PDumpers must either update their PDumpers
     (not that hard), or ensure that only old-style PDFs are used.


2) PARALLEL PORT ERROR DETECTION

A new feature has been added in the connections window. When you choose a
parallel connection, you also get to choose whether or not the frontend
should examine the error lines on the parallel port to check for error
conditions.

Some (very) old printers may not provide these lines, some cables may not be
fully wired, and some switchboxes etc may cause problems; hence the option to
turn it off. This option defaults to off to continue the old behaviour.

Feedback on how well this works would be greatly appreciated.


3) EXTERNAL CONFIG APPS

There has for a long time been a shortcut on !Printers whereby the
configuration window can be opened by shift-clicking a printers icon.

Now, if a printers icon is ctrl-clicked !Printers checks for the existence of
a system variable, of the form:

        Alias$@PrinterConfigRun_name

where name is the name given under the icon (with spaces, '<', '>' and other
undesirable characters replaced by '_'). If this doesn't exist, it tries
again with name replaced by the printer class (dp, lj etc).

If the alias exists, it is executed, followed by an 8 digit hex id number. If
not, the config window is opened as usual. So if an Epson FX-80 PDF is
installed, and the following alias is setup:

Set Alias$@PrinterConfigRun_FX-80 adfs::something.dir.!app

Then the following command line might be run:

adfs::something.dir.!app 00001234

This hex id can be used to identify the printer instantiation for which it
was invoked, using Message_PrintInterrogate (below).

It is intended that this be used to trigger external configuration
applications; for example Laserjets might have an application to set toner
density/economode etc, inkjets might have nozzle clearing utilities etc.

Please note that it is the responsibility of the external application to
ensure that only one copy is run at a time, and that if it is invoked twice
to pop any existing windows to the top of the window stack.


4) NEW WIMP MESSAGE: MESSAGE_PRINTCONFIGURE

A new WIMP message &8014A (Message_PrintConfigure) has been implemented. It
is intended that this be used by external applications to configure
!Printers. Currently only one reason code is defined, but this may grow in
future.

The message block is structured as follows:

        +20 Reason code
        +24 Reason code specific information

Reason code = 0: Load new paper size definitions

        +24 = Pointer to null terminated filename of paper size
        definitions (in the same format as PaperRO/PaperRW etc).

All other reason codes are currently reserved.


5) NEW WIMP MESSAGE: MESSAGE_PRINTINTERROGATE

A new WIMP message &8014B (Message_PrintInterrogate) has been implemented.
It is intended that this be used by external configuration applications to
read the state of a given printers setup. Currently only one reason code is
defined, but this may grow in future.

The message block is structured as follows:

        +20 Reason code
        +24 Reason code specific information

Reason code = 0: Read current config settings

        +24 = Printer id (as supplied in the external config invocation)

This message should be broadcast; if not replied to, then there is either no
!Printers running, that printer instantiation no longer exists, or that class
of printer does not support returning this information (DP and LJ do, PS does
not).

When !Printers receives such a message, it will first ack it, and then send a
reply back as follows:

        +12 ref (copied from +8 in the outgoing message)
        +20 0
        +24 Printer id
        +28 palette number
        +32 options word
        +36 x resolution
        +40 y resolution
        +44 flags
        +48 null terminated string (name of current mode - may be empty)
        [align to word boundary]

External applications should watch for Message_SetPrinter (&80147) being
broadcast, and should re-read their settings on this.

-- 
Comment: Printing technote 1.03
Part: 20000320-006
