Printing

Printers, print jobs, label layouts, printer languages and the fallback for labels.

The printer registry

A printer registry keeps the printers of the app in a file, with one default printer. Each printer has a name, a transport (network, usb, bluetooth, ble or system), a host and a language. A job names its printer, or goes to the default one.

// Dart / Flutter
final printers = await PrinterRegistry.open('${dir.path}/printers.json');
await printers.save(const TargetPrinter(name: 'Labels', host: '192.168.1.40', language: Languages.zpl));
await printers.setDefault('Labels');
final result = await printers.print(PrintJob(type: JobTypes.label, label: LabelJob.parse(labelJson)));
if (!result.ok) print('${result.reason}: ${result.message}');

Print jobs

A print job has a type and the content of that type, and can ask for several copies.

# Python
printers.print(PrintJob(type=JobTypes.PDF, data=open("invoice.pdf", "rb").read()))
printers.print(PrintJob(type=JobTypes.HTML, html="<h1>Packing slip</h1>", printer="Office"))
printers.print(PrintJob(type=JobTypes.RAW, data=b"^XA^FO50,50^ADN,36,20^FDHello^FS^XZ"))
printers.print(PrintJob(type=JobTypes.TEST))

Label layouts

A label is JSON with its width and height in millimetres and a list of elements: text, barcode, qr, box and image. Positions and sizes are in millimetres from the top left corner, so one layout prints the same on printers of any resolution.

{"version": 1, "width_mm": 50, "height_mm": 30, "elements": [
  {"type": "text", "x": 2, "y": 2, "w": 46, "h": 6, "text": "PLD-01J2XYZ", "size_pt": 10, "bold": true},
  {"type": "barcode", "x": 2, "y": 10, "w": 46, "h": 14, "value": "PLD01J2XYZ", "show_value": true},
  {"type": "qr", "x": 36, "y": 2, "side": 8, "value": "https://example.com/t/PLD01J2XYZ"},
  {"type": "box", "x": 0, "y": 0, "w": 50, "h": 30, "border_mm": 0.3}
]}

Printer languages

The language of a printer decides how a label is encoded.

Working out the language

sPrint works out a printer's language without using paper: from its device ID, the model table, IPP for a network document printer and the printer's status reply, in that order. When the printer does not answer, the language detection prints one test line per language and reports what it sent.

// Dart / Flutter
final identity = await SPrint.identifyPrinter(printer);   // device ID, model table, IPP, status reply; no paper
final probe = await SPrint.probeLanguage(printer);         // the printer's status reply only; no paper
final log = await SPrint.detectLanguage(printer);          // asks first, else one test line per language

// C# / .NET
var identity = SPrint.Identify(new PrinterKeys { Names = ["Zebra ZD420"] });
var probe = SPrint.ProbeLanguage(printer);

Fallback for labels

The fallback is off by default. When it is switched on, a label that cannot be printed one way tries the next: the printer's language, the print queue, the printer driver, then the label's HTML. A way that fails twice is closed for that printer until the printer is back.

// Dart / Flutter             // Swift                     // Kotlin
await printers.setFallback(true);   printers.setFallback(true)   printers.fallback = true
# Python                      // C# / .NET                 /* C */
printers.set_fallback(True)   printers.Fallback = true;    sprint_registry_set_fallback(registry, 1);

The fallback state of a printer shows which way is closed, why and since when, and can be reset.

The result

Every print returns a result: whether it printed, and otherwise a stable reason and a message. Act on the reason, never on the message. A print in progress can be stopped.