|
| 1 | +# Barcodes and QR codes |
| 2 | + |
| 3 | +A barcode is a first-class canonical node: `addBarcode` lives on |
| 4 | +`AbstractFlowBuilder`, so codes drop into `pageFlow`, `module`, and |
| 5 | +`section` containers — and combine with rows, cards, layer stacks, and |
| 6 | +tables — like any other block. The builder is `BarcodeBuilder`; the |
| 7 | +result is a `BarcodeNode` carrying `DocumentBarcodeOptions`. |
| 8 | + |
| 9 | +## Quick start: a QR code |
| 10 | + |
| 11 | +```java |
| 12 | +document.pageFlow() |
| 13 | + .addBarcode(barcode -> barcode |
| 14 | + .name("RepoQr") |
| 15 | + .qrCode() |
| 16 | + .data("https://github.com/DemchaAV/GraphCompose") |
| 17 | + .size(150, 150)) |
| 18 | + .build(); |
| 19 | +``` |
| 20 | + |
| 21 | +`data(...)` sets the encoded content; `size(width, height)` (or the |
| 22 | +separate `width(...)` / `height(...)` setters) fixes the drawn box in |
| 23 | +points. |
| 24 | + |
| 25 | +## Symbologies |
| 26 | + |
| 27 | +Five formats have fluent shortcuts — each is a single call: |
| 28 | + |
| 29 | +```java |
| 30 | +barcode.qrCode(); // QR code (2D) |
| 31 | +barcode.code128(); // Code 128 — invoice numbers, logistics ids |
| 32 | +barcode.code39(); // Code 39 — alphanumeric asset tags |
| 33 | +barcode.ean13(); // EAN-13 — 13-digit retail |
| 34 | +barcode.ean8(); // EAN-8 — 8-digit compact retail |
| 35 | +``` |
| 36 | + |
| 37 | +The full `DocumentBarcodeType` enum also covers `UPC_A`, `PDF_417`, |
| 38 | +and `DATA_MATRIX` — select those through the generic setter: |
| 39 | + |
| 40 | +```java |
| 41 | +import com.demcha.compose.document.node.DocumentBarcodeType; |
| 42 | + |
| 43 | +barcode.type(DocumentBarcodeType.DATA_MATRIX) |
| 44 | + .data("LOT-2026-04-001"); |
| 45 | +``` |
| 46 | + |
| 47 | +## Brand tinting and quiet zone |
| 48 | + |
| 49 | +Foreground and background take any `DocumentColor`, so a QR code can |
| 50 | +match the document palette instead of shipping in black-on-white. |
| 51 | +`quietZone(n)` adds the symbology's blank margin, measured in barcode |
| 52 | +modules: |
| 53 | + |
| 54 | +```java |
| 55 | +import com.demcha.compose.document.style.DocumentColor; |
| 56 | + |
| 57 | +section.addBarcode(barcode -> barcode |
| 58 | + .qrCode() |
| 59 | + .data("https://demcha.io/graphcompose") |
| 60 | + .foreground(DocumentColor.rgb(20, 80, 95)) // brand teal |
| 61 | + .background(DocumentColor.rgb(232, 244, 245)) // soft tint |
| 62 | + .quietZone(2) |
| 63 | + .size(150, 150)); |
| 64 | +``` |
| 65 | + |
| 66 | +Keep the foreground much darker than the background — scanners need |
| 67 | +the contrast. |
| 68 | + |
| 69 | +## Clickable codes |
| 70 | + |
| 71 | +A barcode accepts the same link and bookmark metadata as paragraphs |
| 72 | +and images, so the printed QR can double as a clickable area in the |
| 73 | +PDF viewer: |
| 74 | + |
| 75 | +```java |
| 76 | +import com.demcha.compose.document.node.DocumentLinkOptions; |
| 77 | + |
| 78 | +barcode.qrCode() |
| 79 | + .data("https://github.com/DemchaAV/GraphCompose") |
| 80 | + .link(new DocumentLinkOptions("https://github.com/DemchaAV/GraphCompose")) |
| 81 | + .size(150, 150); |
| 82 | +``` |
| 83 | + |
| 84 | +## Centring a barcode in a card |
| 85 | + |
| 86 | +Barcodes have fixed sizes, so inside a card they sit at the leading |
| 87 | +edge by default. Wrap the built node in a shape container sized to the |
| 88 | +card's content width with `CENTER` alignment — `OVERFLOW_VISIBLE` |
| 89 | +skips clipping (see the |
| 90 | +[shape-as-container recipe](shape-as-container.md)): |
| 91 | + |
| 92 | +```java |
| 93 | +import com.demcha.compose.document.dsl.BarcodeBuilder; |
| 94 | +import com.demcha.compose.document.node.BarcodeNode; |
| 95 | +import com.demcha.compose.document.style.ClipPolicy; |
| 96 | + |
| 97 | +BarcodeNode code = new BarcodeBuilder() |
| 98 | + .ean13() |
| 99 | + .data("5901234123457") |
| 100 | + .size(190, 90) |
| 101 | + .build(); |
| 102 | + |
| 103 | +section |
| 104 | + .softPanel(DocumentColor.WHITE, 8, 14) |
| 105 | + .addContainer(card -> card |
| 106 | + .name("Ean13_Center") |
| 107 | + .rectangle(228, code.height()) // card content width |
| 108 | + .clipPolicy(ClipPolicy.OVERFLOW_VISIBLE) |
| 109 | + .center(code)); |
| 110 | +``` |
| 111 | + |
| 112 | +The container's rectangle spans the available slot; the barcode lands |
| 113 | +at the visual midline regardless of its natural aspect ratio. |
| 114 | + |
| 115 | +## See also |
| 116 | + |
| 117 | +- [Shape-as-container](shape-as-container.md) — the centring pattern |
| 118 | + above, plus clipped circles and rounded cards. |
| 119 | +- [PDF chrome](pdf-chrome.md) — links and bookmarks on any node, |
| 120 | + including barcodes. |
| 121 | + |
| 122 | +Runnable showcase: |
| 123 | +[`BarcodeShowcaseExample`](../../examples/src/main/java/com/demcha/examples/features/barcodes/BarcodeShowcaseExample.java) |
| 124 | +([rendered PDF](../../assets/readme/examples/barcode-showcase.pdf)) — |
| 125 | +all five fluent symbologies plus a brand-tinted QR, each centred in a |
| 126 | +two-column card grid. |
0 commit comments