zpl_forge/engine/
backend.rs

1use crate::engine::common::Barcode1DKind;
2use crate::{FontManager, ZplResult};
3
4/// Defines the interface for rendering ZPL instructions.
5///
6/// Implementing this trait allows `zpl-forge` to output label formats to
7/// different targets such as images (PNG, JPG), PDF documents, or raw byte streams.
8#[allow(clippy::too_many_arguments)]
9pub trait ZplForgeBackend {
10    /// Initializes the rendering surface with the specified dimensions.
11    fn setup_page(&mut self, width: f64, height: f64, resolution: f32);
12
13    /// Starts a new page, called between consecutive `^XA...^XZ` blocks.
14    ///
15    /// Multi-page backends (PDF) finish the current page and begin a fresh
16    /// one with the same dimensions. The default implementation is a no-op,
17    /// which keeps single-surface backends (PNG) drawing on the same canvas.
18    fn new_page(&mut self) -> ZplResult<()> {
19        Ok(())
20    }
21
22    /// Configures the font manager used for text rendering.
23    fn setup_font_manager(&mut self, font_manager: &FontManager);
24
25    /// Renders a single line of text.
26    ///
27    /// `orientation` follows `^A`: 'N' (normal), 'R' (rotated 90° clockwise),
28    /// 'I' (inverted 180°), 'B' (read from bottom up, 270° clockwise).
29    /// `(x, y)` is always the top-left corner of the rendered (rotated) cell.
30    fn draw_text(
31        &mut self,
32        x: u32,
33        y: u32,
34        font: char,
35        height: Option<u32>,
36        width: Option<u32>,
37        orientation: char,
38        text: &str,
39        reverse_print: bool,
40        color: Option<String>,
41    ) -> ZplResult<()>;
42
43    /// Draws a rectangular box.
44    fn draw_graphic_box(
45        &mut self,
46        x: u32,
47        y: u32,
48        width: u32,
49        height: u32,
50        thickness: u32,
51        color: char,
52        custom_color: Option<String>,
53        rounding: u32,
54        reverse_print: bool,
55    ) -> ZplResult<()>;
56
57    /// Draws a circle.
58    fn draw_graphic_circle(
59        &mut self,
60        x: u32,
61        y: u32,
62        radius: u32,
63        thickness: u32,
64        color: char,
65        custom_color: Option<String>,
66        reverse_print: bool,
67    ) -> ZplResult<()>;
68
69    /// Draws an ellipse.
70    fn draw_graphic_ellipse(
71        &mut self,
72        x: u32,
73        y: u32,
74        width: u32,
75        height: u32,
76        thickness: u32,
77        color: char,
78        custom_color: Option<String>,
79        reverse_print: bool,
80    ) -> ZplResult<()>;
81
82    /// Renders a raw graphic field (bitmap data).
83    fn draw_graphic_field(
84        &mut self,
85        x: u32,
86        y: u32,
87        width: u32,
88        height: u32,
89        data: &[u8],
90        reverse_print: bool,
91    ) -> ZplResult<()>;
92
93    /// Renders a custom color image from base64 data.
94    ///
95    /// If width and height are 0, natural size is used.
96    /// If one is 0, the other is scaled proportionally.
97    fn draw_graphic_image_custom(
98        &mut self,
99        x: u32,
100        y: u32,
101        width: u32,
102        height: u32,
103        data: &str,
104    ) -> ZplResult<()>;
105
106    /// Draws a Code 128 barcode.
107    fn draw_code128(
108        &mut self,
109        x: u32,
110        y: u32,
111        orientation: char,
112        height: u32,
113        module_width: u32,
114        interpretation_line: char,
115        interpretation_line_above: char,
116        check_digit: char,
117        mode: char,
118        data: &str,
119        reverse_print: bool,
120    ) -> ZplResult<()>;
121
122    /// Draws a QR Code.
123    fn draw_qr_code(
124        &mut self,
125        x: u32,
126        y: u32,
127        orientation: char,
128        model: u32,
129        magnification: u32,
130        error_correction: char,
131        mask: u32,
132        data: &str,
133        reverse_print: bool,
134    ) -> ZplResult<()>;
135
136    /// Draws a generic 1-D barcode (EAN-13, UPC-A, Interleaved 2 of 5, Code 93).
137    #[allow(clippy::too_many_arguments)]
138    fn draw_barcode_1d(
139        &mut self,
140        kind: Barcode1DKind,
141        x: u32,
142        y: u32,
143        orientation: char,
144        height: u32,
145        module_width: u32,
146        ratio: f32,
147        check_digit: char,
148        interpretation_line: char,
149        interpretation_line_above: char,
150        data: &str,
151        reverse_print: bool,
152    ) -> ZplResult<()>;
153
154    /// Draws a diagonal line (`^GD`). `diagonal_orientation` is 'R' (`/`) or 'L' (`\`).
155    #[allow(clippy::too_many_arguments)]
156    fn draw_graphic_diagonal(
157        &mut self,
158        x: u32,
159        y: u32,
160        width: u32,
161        height: u32,
162        thickness: u32,
163        color: char,
164        custom_color: Option<String>,
165        diagonal_orientation: char,
166        reverse_print: bool,
167    ) -> ZplResult<()>;
168
169    /// Draws a Data Matrix (ECC 200) barcode.
170    ///
171    /// `module_size` is the side of each module cell in dots.
172    fn draw_datamatrix(
173        &mut self,
174        x: u32,
175        y: u32,
176        orientation: char,
177        module_size: u32,
178        data: &str,
179        reverse_print: bool,
180    ) -> ZplResult<()>;
181
182    /// Draws a PDF417 barcode.
183    ///
184    /// `row_height` is the bar height per matrix row and `module_width` the
185    /// narrow bar width, both in dots. `security_level` is the PDF417 error
186    /// correction level (0-8).
187    fn draw_pdf417(
188        &mut self,
189        x: u32,
190        y: u32,
191        orientation: char,
192        row_height: u32,
193        module_width: u32,
194        security_level: u32,
195        data: &str,
196        reverse_print: bool,
197    ) -> ZplResult<()>;
198
199    /// Draws a Code 39 barcode.
200    fn draw_code39(
201        &mut self,
202        x: u32,
203        y: u32,
204        orientation: char,
205        check_digit: char,
206        height: u32,
207        module_width: u32,
208        ratio: f32,
209        interpretation_line: char,
210        interpretation_line_above: char,
211        data: &str,
212        reverse_print: bool,
213    ) -> ZplResult<()>;
214
215    /// Draws a MicroPDF417 barcode.
216    fn draw_micropdf417(
217        &mut self,
218        _x: u32,
219        _y: u32,
220        _orientation: char,
221        _height: u32,
222        _mode: u32,
223        _data: &str,
224        _reverse_print: bool,
225    ) -> ZplResult<()> {
226        Ok(())
227    }
228
229    /// Draws an Aztec Code barcode.
230    fn draw_aztec_code(
231        &mut self,
232        _x: u32,
233        _y: u32,
234        _orientation: char,
235        _magnification: u32,
236        _data: &str,
237        _reverse_print: bool,
238    ) -> ZplResult<()> {
239        Ok(())
240    }
241
242    /// Finalizes the rendering process and returns the resulting data.
243    fn finalize(&mut self) -> ZplResult<Vec<u8>>;
244}
zpl_forge/engine/backend.rs

zpl_forge/engine/
backend.rs
