The CPRI API
CPRI
A CGUI and Allegro addon for for formatted printing
by Christer Sandberg and Rasmus Myklebust
Email: christer.sandberg@mdh.se
Homepage: http://www.idt.mdh.se/~csg/cgui/cguix
The Manual of CPRI 0.9.4

Contents

Introduction

CPRI is a lib that let is useful for the following reasons: To be able to call the functions in the cpri lib you must #include in your C file(s), you must also initialize the lib by a call to `CpriInitPrinter' once before calling any other function.
Before starting any printout you also need to tell which queues that shall be used. You also need to start up any queue to be used, using `CpriPrintingProperties'
A certain printout starts with opening a queue entry. In return you get a handle that can be used when sending text or printer commands to the printer. When there are no more to print you have to close the queue entry. At once this is done the queue entry is finished and put onto the printout queue (waiting until all other printouts are finished).
For DOS systems there are some special features for printing queues:
CPRI can handle up 3 LPT ports in parallell for printouts in the background using CGUI's queue.
There are also some special queues. The "optimal queue" can be used to put printouts in for the case that you have more than one LPT printer connected. The entries in the "optimal queue" will be distributed to any of the LPT printers as soon as one get idle. A request queue will contain no more that one entry and lets the end user choose a certian queue. A "DOS print" queue will use the standard DOS LPR stream for the printout. A "network queue" let you pass a printout to any external program (which can be e.g. a "remote print" command).

Using

You can use CPRI to make formatted text printing and some minor graphic decorations is supposed to be useful along with text printing. There is no support for real graphics and no support for color printing.
Font face, style, size can be set to an extent supported by the target. When text is printed the print position advances to the end of the text. When CPRI commands are executed the print position is advanced in a manner explained in the description of the command in concern.
The print position can be moved explicitly by absolute or relative positioning commands. The behaviour of these are target dependent, and they are mainly intended for real printer rather than text and html-files.
An alternative to making printouts controlling the positioning yourself, you can instedaa define a tabular printout, and this is actually the main point with CPRI.
A tabular printout means that you let CPRI manage: Note that CPRI_MOVE_TO_NEXT_COLUMN must be used also to select the first "cell" on a new line for input. After a CPRI_NEW_LINE command and a CPRI_MOVE_TO_NEXT_COLUMN command there some commands can be issued that concerns the entire row. As mentiond above CPRI will calculate the height needed for the used font. Suppose that you like to use a larger font in a cell in a certain row. Then you can set that larger font befor the first CPRI_MOVE_TO_NEXT_COLUMN to inform CPRI about your needings. The font size can then be restored before adding commands and text into the cell (the font commands are all the time global settings affecting all printing until next font command is issued). There are lots of options to these basic behaviour. When being in tabular mode positioning commands are still allowed but you have to the responsibility for restoring the positioing yourself. The CPRI_MOVE_TO_NEXT_COLUMN and CPRI_NEW_LINE will always move the x-position correctly, but the y-pos will not be restored if you mess around the page, so if you are not careful the printout may be messy.

Functions


void CpriInitPrinter(void);

Initialises the CPRI printing. Shall be called once prior to other printing functions. The directory where the spooler puts the eventual spoolfiles is determined from the path the of environment variable TEMP or TMP If none of these are defined then the current directory will be used. Spooler files will be deleted automaticaly after printing is finished. If The program terminates abnormally while printouts are spooled to files, there may be files dropped left. This is probably a minor problem since file names are reused in next program session. CpriInitPrinter will try to load the settings from the current configuration file. These settings can be changed by use of `CpriPrinterPortDialogue' or `CpriPrintingProperties'.
See also: CpriPrinterPortDialogue, CpriPrintingProperties, CpriDeInitPrinter.
void CpriDeInitPrinter(void);

Releases memory allocated by the printer module. You don't need to call it since it will be executed automatically at exit.


void CpriPrintingProperties(int queue, int use, int brand, const char *cmd1, const char *cmd2);

CpriInitPrinter will load the printing properties from the current config file. `CpriPrintingProperties' can be used either to override or these values or to preset them if no config file is present. In addition the settings can be set directly by the user in the `CpriPrinterPortDialogue'.
Parameters:


void CpriPrinterPortDialogue(void);

This function starts a dialogue where the user may edit the properties for the CPRI printer queues. The initial values are the values loaded from current configuration file or set by CpriPrintingProperties. Currently the following properties are available: The dialogue also contains some buttons for: The dialogue will store the updated values into the current configuration file.


t_handle CpriOpenEntry(int qno, const char *print_name, int option, const char *destination);

OpenEntry opens a queue entry for storing text to print and Cpri printer commands. The return value is a pointer to a handle to be used when subsequently adding text and commands to the entry. The queue number is used in DOS only. must be to an active printer port. The job will be put into that queue when CpriCloseEntry is called.
Parameters: Return value: the handle to use when printing text and commands.


int CpriCloseEntry(t_handle hnd);

CpriCloseEntry Has to be called to close the queue entry. The job is moved from the pending queue to the queue of printer jobs. If the queue processor is idle at the time of the call to CpriCloseEntry it will will immediately start printing in the backgroud.
Parameters: Return value: 0 if fail (i.e. hnd has not been opened).


int CpriCommand(t_handle hnd, t_command cmd, ...);

Adds a command to an opened queue entry. This is a printf style function, i.e. the command may need additional parameters.
Parameters: Return value: 0 if fail (i.e. hnd has not been opened).


int CpriText(t_handle hnd, char *string);

Adds normal text to an opened queue entry.
Parameters: Return value: 0 if fail (i.e. hnd has not been opened).


void CpriPrinterQueueMonitor(void);

Opens a queue monintor window. The window is of type "floating", i.e. previously openened windows will still be accessible for the user, but the monitor window will float on top.


int CpriIsSpooling(void);

If no printing is in progress (and no printouts is in queues) this function will return 0, otherwise 1


const char * const cpri_typeface_names[];

typeface_names contains text strings with the names corresponding to the typeface-acronyms specified in 'CPRI_FONT_TYPEFACE'


void const char *const*CpriGetQueueNames(void);

Returns pointers to text labels used for the display of printer queues.


void const char *const*CpriGetDriverNames(void);

Returns pointers to text labels used for the display of printer drivers.


void const char *const*CpriGetTypefaceNames(void);

Returns pointers to text labels used for the display of typeface names.

Print commands


const char* CPRI_MANUAL_FEED

Forces the printer to feed papers from the manual tray (can be used e.g for OH:s)
Parameter: None


const char* CPRI_CASETTE_FEED

Normal paper cassette
Parameter: None


const char* CPRI_PORTRAIT

Forces the print direction to portrait (default)
Parameter: none


const char* CPRI_LANDSCAPE

Forces the print direction to landscape (portrait is default)
Parameter: none


const char* CPRI_END_START_SEQUENCE

The "end of start sequence" command is used to notify the driver that no more inialization commands will come, and starts to build the page.
Parameter: none


const char* CPRI_NR_OF_COPIES

The "number of copies" command specifies the number of copies of the current printing that is to b eprinted. (The default is one copy) Parameter: The number of copies


const char* CPRI_TABLE

Specifies a table. This is a conventient way to specify pretty prints of when need report like printouts.
The height of rows will adapt to the current font, you can later move ahead in the table using the CPRI_MOVE_TO_NEXT_COLUMN and CPRI_NEW_LINE. The driver will control paper feed and proper ending and start of pages. You can specify the table cells top be outlined by use of a single grid command. You can also specify different alignments of text in the cells.

The width of a table is implicit by the sum of the widths of the columns.
Parameters:


const char* CPRI_END_TABLE

End of the table. After this command the behaviour of of table related commands are undefined, until a new CPRI_TABLE command is sent.


const char* CPRI_CREATE_COLUMN

The "create column" command will create a new column in a table. It doesn't affect the the printout instantly but prepares the driver to know what to do when received subsequent CPRI_MOVE_TO_NEXT_COLUMN.
Parameter: The column width in mm


const char* CPRI_MOVE_TO_NEXT_COLUMN

The "move to next column" moves the printing position to the next column in a table (i.e. to the beginning of next "cell") on the current row. The new position will always be at the bginning of next cell, so in case the print-position incidently passed ahead the border of the previous cell, there may occure overwrited text.
Note! You have to use this command also to move into the first cell after a CPRI_NEW_LINE command.
Parameter: none


const char* CPRI_MERGE_ALL_COLUMNS

This command will temporary merge all cells of a table into one single cell. This may be useful e.g. for headers. The columns can be activated again with a single CPRI_ACTIVE_COLUMNS command.
Parameter: none


const char* CPRI_DEACTIVATE_COLUMN

The "deactivate column" deactivates a specific column. This simply means that it will be concatenated with the one to the left. I.e.: Deactivated column(s) may be re-activated with the CPRI_ACTIVATE_COLUMNS command.
Parameter: the column index (the first one has index 0)


const char* CPRI_ACTIVATE_COLUMNS

This command enables all previously deactivated columns. This command should be sent in between a CPRI_NEW_LINE command and the first `CPRI_MOVE_TO_NEXT_COLUMN' of next line.
Parameter: none


const char* CPRI_NEW_LINE

This command moves to left side of the next row of the current table. Note: You have to also send a CPRI_MOVE_TO_NEXT_COLUMN command to actually move into the first column. The height of the new line can optionally vary between different rows. The height will be calculated not when the CPRI_NEW_LINE is read, but when the CPRI_MOVE_TO_NEXT_COLUMN is read, so in between modifications can be done.
If a newline command should lead to a row that does not entirely fit into the current page as specified by the CPRI_TABLE command, there will be an automatic paper feed sent to the printer. The following actions will be taken: Parameter: None


const char* CPRI_START_GRID

The "start grid" command can be used e.g. if you want a previously defined table to have all its cells outlined. To accompish this it is necessary that all tabs are generated prior to the "start grid" command. The aoutogrid mode will be reset when the command cleartabs is received. Parameter: none


const char* CPRI_END_GRID

The command "end grid" marks that the "auto grid" mode are to be turned off. Parameter: none


const char* CPRI_BEGIN_TO_BE_REPEATED

This command will bring the driver to record all commands and text up to next CPRI_END_TO_REPEAT command. The commands and text will be repeated at the top of subsequent pages.
This can be useful e.g. if you want to print something like column headers and want these to be automatically printed on next page. The command is only meaningful if you have defined a table, and the repeated section is within this table. Other usage is undefined. Note that this command does not work like "recording macros" usually soed, i.e. it will print the commands at the same time as recording.
Normally you will want the repeated row(s) to be from the beginning of the table. The command has to be sent after the table is defined.

Parameter: none.


const char* CPRI_END_TO_BE_REPEATED

If data is printed in recorded mode (started by CPRI_BEGIN_TO_REPEAT) this command will stop the recording.
The right point to send this cammand is after a CPRI_NEW_LINE command; the driver will only record whole lines properly.
Parameter: none


const char* CPRI_LINE_HEIGHT

The "line height" command specifies the relative height of a newline-command and is closely connected to that. The height specification should be given in % of the font height. The default setting of CPRI_LINE_HEIGHT is 100%, meaing "normal height". To be more precise: With a font size of 12 a newline will be 6 lpi or 4.2mm when default CPRI_LINE_HEIGHT is set.

Parameter: the height in % of "font height"


const char* CPRI_TEXT_TO_VLINE_SPACE

const char* CPRI_TEXT_TO_HLINE_SPACE

The "set 'text to horizontal line' spacing" command sets the distance of the automatically printed horizontal line (used for each newline when autogrid is specified). The default spacing is to the middle of the 2 text-rows (50%)
The "set 'text to vertical line' spacing" works similar, i.e. defines the spacing around the vertical lines when auto-grid is turned on. Parameter (CPRI_TEXT_TO_VLINE_SPACE): The level of the line in % (valid interval: 0-100)
Parameter (CPRI_TEXT_TO_VLINE_SPACE): The distance between the text and line in mm


const char* CPRI_STRIKE

Draws a line across a textstring. The string must contain no escape- sequences.
Parameter: The text-string to be striked


const char* CPRI_SUP_RALIGN_CELL

const char* CPRI_SUP

const char* CPRI_SUP_RALIGN

const char* CPRI_SUP_LALIGN

The CPRI_SUP* commands will print a string superscipted. The current font settings will be used, except that the size will be 2/3 of the current size and printing position will be moved up to half the current font height relative to the current y-pos.
After the string has been printed the y-position is restored to the normal base line of the cell, but the x-position is undefined. The different commands can be combined in the same cell. E.g.
   ------------------------------------------------------
   |42            13             99         -24         |
   |                Centered base              R.a. base|
   ------------------------------------------------------
   
Parameter: The text to be printed superscripted.


const char* CPRI_FONT_SIZE

Specifies the size of subsequent text (12 is the default). In tables the font height being in use when the first CPRI_MOVE_TO_NEXT_COLUMN of a row is received will also affect the hight of that row.

Parameter: The size of the font


const char* CPRI_NEW_PAGE

The newline command will automatically detect end of paper so when printing in table mode you don't need to worry about pages. This command can be used if you do all the positioning explicitly.
Parameter: none


const char* CPRI_PUSH_POS

const char* CPRI_POP_POS

"push position" saves the current print position for later restoring with the "pop position" command. Only intended for "free text drawing", not in tables (however they may occasionally also work in tables).
Parameter: none


const char* CPRI_FONT_TYPEFACE

The "font typeface" command specifies the typeface of the text. Times is usually the default. The drivers are dependent on the capabilities of target.
Parameters:


const char* CPRI_UNDERLINE

The "underline" command controls start and end of underlined text. Parameter: 1=on 0=off


const char* CPRI_START_RECORD_MACRO

const char* CPRI_STOP_RECORD_MACRO

The "start record macro" command forces all subsequent commands up to next "stop record macro" command to not be printed, but instead stored to be executed later on. The command is intended for usage in free text drawing mode, but may also be used in tables.
Parameter: none


const char* CPRI_EXECUTE_MACRO

Executes the macro specified by the lates "macro id" command.
Parameter: none


const char* CPRI_DELETE_MACROS

Forces all stored macros to be forgotten.
Parameter: none


const char* CPRI_MACROID

The "macro id" command specifies a macro-id to be used in subsequent macro commands of other types.
Parameter: the macro id


const char* CPRI_FIX_ROW_HEIGHT

Set the row height to a fixed number of mm in a table (independent of the font size used).
Parameter: the size in mm


const char* CPRI_HORIZONTAL_BAR

const char* CPRI_END_BAR_LABEL

The "horizontal bar" command draws a horizontal bar with a black frame. The bar has several possibilities to be filled. The behviour of this command is only defined within a table. The bar is intended to be combined with a text label, specially text can be embedded in the bar. The horizontal bar is a table related command. It is of course most intuitive to make a single column table without frame. The CPRI_HORIZONTAL_BAR commnad is intended to send as the sole content of a cell in such a table, but occasionally other usages may work. You will need to use CPRI_FIX_ROW_HEIGHT to be able to set the height correctly, at least if non-embedded text label is used. The end marker of the text, CPRI_END_EMBEDDED_TEXT, is supposed to be in the same cell as the bar, if not the behaviour is undefined. This command is intended to be used in a single column table, but may occationally work with more.
Parameters:


const char* CPRI_DOSTEXT

The "dos text" command informs the driver that text should be converted to PC-850 symbol set format. The HP-driver ignore this command. It is primary intended for text files.
Parameter: 0=no; 1=yes


const char* CPRI_HTML_TAG

The "html tag" command sends a link address to the driver. It will generate a <a href= "address"> link in the output. Only the html-driver will recognise this command.
Parameter: the address


const char* CPRI_END_HTML_TAG

The "html end tag" command generates a </a> in the output. Only the html-driver will recognise this command.
Parameter: none


const char* CPRI_CHECK

The "check" command draws prints a check-mark using some target specific shape.
Parameter: none


const char* CPRI_SINGLE_ROW

The "single row" command prints the grid of a single row of a table using the current set of tabs and all other current settings. The printing includes all lines (top, bottom, left, right and intermediate edges) Parameter: none


const char* CPRI_ALIGN

The "align" command aligns a certain text as specified. The current print position after printing is finished is undefined meaning that additional printing in the same cell needs some other alignment (in case of html there can only be one alignment in a cell).
Parameters:


const char* CPRI_ABS_MOVEX

const char* CPRI_ABS_MOVEY

const char* CPRI_REL_MOVEX

const char* CPRI_REL_MOVEY

These are positioning-commands that uses mm as unit (not implemented in html and text-drivers)
Parameter: the new position or the movement


const char* CPRI_RECTANGLE

The "rectangle" command draws a rectangle. The top-left corner will be drawn at current position. When printing is finished, the new position will be at the upper right corner of the rectangle.
Parameters:


const char* CPRI_BAR_CODE

The "bar code" command creates a barcode using the interleaved 2/5 symbology. It will be printed at the current position (lower left corner at current position). When finished the current x-position has advanced to the length of the barcode.
Parameter: The digits to encode. NOTE: as a string of EVEN NUMBER of digits


const char* CPRI_BAR_CODE_W

Specifies the width of narrow bars/spaces of the bar codes (the wide bars/spaces will be automatically adjusted for correct proportions). The setting will remain throughout the current print out. Narrow bars will make the entire code shorter and therefore less error prone when read, and also it will consume less space on the paper.
Parameter: The width as an integer value expressed in 1/100 of mm. The actual resolution is dependent of the printer properties. Typically a printer may have a resolution of 0.1mm or 0.03mm. The default setting is 7 (mm/100).


const char* CPRI_BAR_CODE_H

Specifies the height of the bars codes. The setting will remain throughout the current print out. A high barcode is more fault tolerant for holding the reader oblique, the longer barcode to print the higher it needs to be, if it is important with robust reading.
Parameter: The height as an integer value in millimeter, the default setting is 8 mm.


const char* CPRI_SCALING

The "scaling" command changes the current scaling. Some measurements like positions and sizes are interpreted according to the current scaling.
Parameter: 0- sizes should be expressed in nr of "character boxes" in the default fix text size 1-(default) sizes should be expressed in mm


const char* CPRI_RESET

The "reset" command resets the driver state to the initial state, and if possible, send a reset command to the driver
Parameter: none

Index