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        interpretation_line: char,
147        interpretation_line_above: char,
148        data: &str,
149        reverse_print: bool,
150    ) -> ZplResult<()>;
151
152    /// Draws a diagonal line (`^GD`). `diagonal_orientation` is 'R' (`/`) or 'L' (`\`).
153    #[allow(clippy::too_many_arguments)]
154    fn draw_graphic_diagonal(
155        &mut self,
156        x: u32,
157        y: u32,
158        width: u32,
159        height: u32,
160        thickness: u32,
161        color: char,
162        custom_color: Option<String>,
163        diagonal_orientation: char,
164        reverse_print: bool,
165    ) -> ZplResult<()>;
166
167    /// Draws a Data Matrix (ECC 200) barcode.
168    ///
169    /// `module_size` is the side of each module cell in dots.
170    fn draw_datamatrix(
171        &mut self,
172        x: u32,
173        y: u32,
174        orientation: char,
175        module_size: u32,
176        data: &str,
177        reverse_print: bool,
178    ) -> ZplResult<()>;
179
180    /// Draws a PDF417 barcode.
181    ///
182    /// `row_height` is the bar height per matrix row and `module_width` the
183    /// narrow bar width, both in dots. `security_level` is the PDF417 error
184    /// correction level (0-8).
185    fn draw_pdf417(
186        &mut self,
187        x: u32,
188        y: u32,
189        orientation: char,
190        row_height: u32,
191        module_width: u32,
192        security_level: u32,
193        data: &str,
194        reverse_print: bool,
195    ) -> ZplResult<()>;
196
197    /// Draws a Code 39 barcode.
198    fn draw_code39(
199        &mut self,
200        x: u32,
201        y: u32,
202        orientation: char,
203        check_digit: char,
204        height: u32,
205        module_width: u32,
206        interpretation_line: char,
207        interpretation_line_above: char,
208        data: &str,
209        reverse_print: bool,
210    ) -> ZplResult<()>;
211
212    /// Finalizes the rendering process and returns the resulting data.
213    fn finalize(&mut self) -> ZplResult<Vec<u8>>;
214}
zpl_forge/engine/backend.rs

zpl_forge/engine/
backend.rs
