print

/* Copyright 1996 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*
 * Title: print.h
 * Purpose: access to printer driver facilities
 *
 */

#ifndef print__h
#define print__h

typedef enum
{
  print_PostScript     = 0,
  print_FX80compatible = 1
} print_identity;


typedef enum
{
  print_colour      = 0x0000001,  /* colour                               */
  print_limited     = 0x0000002,  /* if print_COLOUR bit set, full colour */
                                  /* range not available                  */
  print_discrete    = 0x0000004,  /* only a discrete colour set supported */

  print_NOFILL      = 0x0000100,  /* cannot handle filled shapes well     */
  print_NOTHICKNESS = 0x0000200,  /* cannot handle thick lines well       */
  print_NOOVERWRITE = 0x0000400,  /* cannot overwrite colours properly    */

  print_SCREENDUMP  = 0x1000000,  /* supports PDriver_ScreenDump          */
  print_TRANSFORM   = 0x2000000   /* supports arbitrary transformations   */
                                  /* (else only axis-preserving ones).    */
} print_features;


typedef struct print_infostr
  { short int version;     /* version number *100                       */
    short int identity;    /* driver identity (eg 0=Postscript,1=FX80)  */
    int xres, yres;        /* x, y resolution (pixels/inch)             */
    int features;          /* see print_features                        */
    char *description;     /* printers supported, <=20chars + null      */
    int xhalf, yhalf;      /* halftone resolution (repeats/inch)        */
    int number;            /* configured printer number                 */
  } print_infostr;



typedef struct
  { int x0, y0, x1, y1;
  } print_box;


typedef struct print_pagesizestr
  { int xsize, ysize;  /* size of page, including margins (1/72000 inch)   */
    print_box bbox;    /* bounding box of printable portion (1/72000 inch) */
  } print_pagesizestr;


typedef struct print_transmatstr
  { int xx, xy, yx, yy;
  } print_transmatstr;

typedef struct print_positionstr
  { int dx, dy;
  } print_positionstr;

/* ----------------------------- print_info ----------------------------
 * Description:  Read details of current printer driver (version,
 *               resolution, features etc).
 *
 * Parameters:   Pointer to print_infostr structure to be filled in.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_info(print_infostr*);


/* ----------------------------- print_setinfo -------------------------
 * Description:  Reconfigure current printer driver.
 *
 * Parameters:   Pointer to the print_infostr structure to be used to
 *               update the printer driver configuration.
 * Returns:      Any error returned from the system call.
 * Other Info:   The version, identity and description fields are not
 *               used. Leave bit 0 clear in the features field for
 *               monochrome, set bit 0 for colour.
 */

os_error * print_setinfo(print_infostr *i);


/* ----------------------------- print_checkfeatures -------------------
 * Description:  Checks the features of a printer, returning an error if
 *               the current printer does not have the specified
 *               features.
 *
 * Parameters:   int mask  -- set bits correspond to the features
 *                            of interest (bits as print_features)
 *               int value -- required values of the bits of interest
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_checkfeatures(int mask, int value);


/* ----------------------------- print_pagesize ------------------------
 * Description:  Find how large paper and print area is.
 *
 * Parameters:   Pointer to the print_pagesizestr structure to be
 *               filled in.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_pagesize(print_pagesizestr*);


/* ----------------------------- print_setpagesize ---------------------
 * Description:  Set how large paper and print size is.
 *
 * Parameters:   Pointer to the print_pagesizestr structure to be
 *               used to update the printer driver.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_setpagesize(print_pagesizestr *p);


/* ----------------------------- print_selectjob -----------------------
 * Description:  Make a given print job the current one.
 *
 * Parameters:   int job      -- file handle for selected job, or 0
 *                               to leave no print job selected
 *               char *title  -- title string for job
 *               int *oldjobp -- pointer to integer to fill in with
 *                               file handle of previously active job
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_selectjob(int job, char *title, int *oldjobp);


/* ----------------------------- print_currentjob ----------------------
 * Description:  Get the file handle of the current print job.
 *
 * Parameters:   Pointer to integer to be filled in with the
 *               file handle of the current print job.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_currentjob(int *curjobp);


/* ----------------------------- print_endjob --------------------------
 * Description:  End a print job normally.
 *
 * Parameters:   File handle of print job to be ended.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_endjob(int job);


/* ----------------------------- print_abortjob ------------------------
 * Description:  End a print job without any further output.
 *
 * Parameters:   File handle of print job to be aborted.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_abortjob(int job);


/* ----------------------------- print_canceljob -----------------------
 * Description:  Stops a specified print job from printing.
 *
 * Parameters:   File handle of print job to be cancelled.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_canceljob(int job);


/* ----------------------------- print_reset ---------------------------
 * Description:  Abort all print jobs.
 *
 * Parameters:   void
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_reset(void);

/* ----------------------------- print_selectillustration --------------
 * Description:  Makes the specified print job the current one,
 *               and treats it as an illustration.
 *
 * Parameters:   int job      -- file handle for selected job, or 0
 *                               to leave no print job selected
 *               char *title  -- title string for job
 *               int *oldjobp -- pointer to integer to fill in with
 *                               file handle of previously active job
 * Returns:      Any error returned from the system call.
 * Other Info:   The difference with print_selectjob is that an
 *               error is generated if the job does not contain
 *               one page, and certain printer drivers (such as
 *               the PostScript printer driver) generate
 *               different output for illustrations.
 */


os_error * print_selectillustration(int job, char *title, int *oldjobp);


/* ----------------------------- print_giverectangle -------------------
 * Description:  Specify a rectangle to be printed.
 *
 * Parameters:   ident -- rectangle identification word
 *               Pointer to structure specifying rectangle to be
 *                   plotted (OS coordinates)
 *               Pointer to structure specifying transformation
 *                   matrix (fixed point, 16 binary places)
 *               Pointer to structure containing  the position of
 *                   bottom left of rectangle on page (1/72000 inch)
 *               bgcol -- background colour for this rectangle, &BBGGRRXX
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error *print_giverectangle(int, print_box*, print_transmatstr*,
                              print_positionstr*, int);


/* ----------------------------- print_drawpage ------------------------
 * Description:  This should be called after specifying all rectangles
 *               to be plotted on the current page with
 *               print_giverectangle.
 *
 * Parameters:   copies -- number of copies
 *               sequ   -- zero or pages sequence number within document
 *               page   -- zero or a string containing a textual page number
 *                         (no spaces)
 *               Pointer to structure to be filled in with the rectangle
 *               to print
 *               more   -- pointer to integer to be filled in with the
 *                         number of copies left to print
 *               ident  -- pointer to integer to be filled in with the
 *                         rectangle identification word
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_drawpage(int copies, int sequ, char *page,
                          print_box *clip, int *more, int *ident);


/* ----------------------------- print_getrectangle --------------------
 * Description:  Get the next print rectangle.
 *
 * Parameters:   Pointer to the structure to be filled in with the clip
 *                   rectangle
 *               more  -- pointer to integer to be filled in with the number
 *                        of rectangles left to print
 *               ident -- pointer to integer to be filled in with the
 *                        rectangle identification word
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_getrectangle(print_box *clip, int *more, int *ident);


/* ----------------------------- print_screendump ----------------------
 * Description:  Output a screen dump to the printer.
 *
 * Parameters:   File handle of file to receive the dump.
 * Returns:      Any error returned from the system call.
 * Other Info:   none.
 */

os_error * print_screendump(int job);

#endif