Label
public sealed class LabelLabel designer object model: describe a label with items in physical units, then generate ZPL (Label.ToZpl), render a preview through the ZPL renderer (Label.Render) or save it as JSON. Rendering always goes through the generated ZPL, so the preview equals what the printer gets.
Constructors
Properties
| Property | Type | Description |
|---|---|---|
Contour { get; set; } | LabelContour | Outline of the label stock. LabelContour.Ellipse = round/oval label inscribed in Width × Height: previews (Label.Render, LabelBinding.Render, PDF, HTML) show the outline and tint the area outside it, Label.Validate reports items with ink outside it. Printing is unchanged (native). |
Culture { get; set; } | string | Culture used to resolve {t:key} placeholders (e.g. "de-DE"; null = current UI culture). |
CutAfterLastLabel { get; set; } | bool | Cut only after the last label of a job printed with records (Label.ToZpl, Label.For`): the default of LabelBinding.CutAfterLastLabel. |
CutAfterPrinting { get; set; } | bool | Cut after each label (^MMC). |
Darkness { get; set; } | int? | 0–30 (^MD relative darkness is -30..30, ~SD absolute 0..30). |
DownloadFonts { get; set; } | bool | Send Label.Fonts to the printer (disable if they are already stored there). |
Duplex { get; set; } | bool | Duplex label: pages are printed as front/back pairs. Convention for the generated ZPL: every side is its own consecutive ^XA…^XZ format — front (page 1 = Label.Items), then back (page 2 = Label.Pages[0]), then front/back of further pages. Each side starts with a ^FXDUPLEX FRONT / ^FXDUPLEX BACK comment; a missing back side is emitted as an empty format so the sequence keeps its parity. With several copies the pairs are repeated (front, back, front, back …) instead of using ^PQ, so a duplex printer receives them in order. |
Expressions { get; } | ExpressionEngine | Expression engine for item expressions (add custom functions/variables here). |
FontAsGraphicThreshold { get; set; } | int | Fonts in Label.Fonts larger than this many bytes are not downloaded; text items using them are sent as ^GFA graphic instead (0 = always download). |
Fonts { get; set; } | Dictionary<string, byte[]> | TrueType fonts used by this label (name like "ARIAL.TTF" → file bytes, base64 in JSON). They are downloaded to the printer with ~DY in the first format and used via TextItem.Font = "E:ARIAL.TTF", and also used for preview and LabelItem.PrintAsGraphic. |
GapLength { get; set; } | double | Gap between labels (media setting, emitted as ^LL/^MN only). |
GraphicCompression { get; set; } | GraphicCompression? | With ZplOptimization.Aggressive: re-encode ^GFA graphic data in this encoding (null = keep). |
Height { get; set; } | double | |
Items { get; set; } | List<LabelItem> | |
LabelShift { get; set; } | double | Shifts the printed image horizontally, in label units (^LS; positive = left). 0 = not emitted. |
LabelTop { get; set; } | double | Shifts the printed image vertically, in label units (^LT; positive = down). 0 = not emitted. |
Optimization { get; set; } | ZplOptimization | Optimisation applied to the generated ZPL (see ZplOptimizer). The printed result is identical. |
PageCount { get; } | int | |
Pages { get; set; } | List<LabelPage> | Additional pages after the first one (Label.Items = page 1), e.g. the back side for duplex printers. Each page becomes its own format in order. |
PrintInverted { get; set; } | bool | Rotate the whole label by 180° (^PO I). |
PrintMirror { get; set; } | bool | Mirror the label (^PM Y). |
PrintSpeed { get; set; } | int? | Print speed in inches per second (^PR). |
Rotation { get; set; } | ItemRotation | Turns the whole printed label clockwise (e.g. a label designed upright that is fed sideways): for 90°/270° the printed format is Label.Height wide and Label.Width long, and every item is turned with it (position and own rotation; the output stays native). The design itself is not changed. Raw ZPL items print as written; repeaters are not supported. |
SchemaVersion { get; set; } | int | Schema version of the JSON template (1 = files written before the field existed, migrated on load). Always Label.CurrentSchemaVersion after loading. |
Strings { get; set; } | Dictionary<string, Dictionary<string, string>> | Localizable strings: culture name ("" = fallback) → key → text. Item texts, expressions results and table cells may contain {t:key} placeholders, resolved for Label.Culture (or the binding's culture) with fallback to the parent culture ("de-CH" → "de"), then "", then the key itself. |
Tag { get; set; } | string | Free user data stored with the label (e.g. an id or notes of the application that manages it). It is saved in the label JSON and has no effect on printing. |
Unit { get; set; } | LabelUnit | |
Width { get; set; } | double |
Fields & Constants
| Field | Type | Description |
|---|---|---|
const CurrentSchemaVersion = 4 | int | Version of the JSON template schema written by this library. |
Methods
| Method Signature | Returns | Description |
|---|---|---|
# Add(LabelItem item) | Label | |
# AddFont(string name, byte[] ttf) | Label | |
# AddFontFile(string path, string? name = default) | Label | |
# AddPage(string? name = default) | LabelPage | Adds a page (page 2 = back side on duplex printers) and returns it. |
# AddString(string culture, string key, string text) | Label | Adds a localized string. |
# CheckReadability(IReadOnlyDictionary<string, object>? record = default, int dpi = 203) | List<BarcodeItemReadability> | Readability of every visible artistic barcode (module/finder shapes, logo, halftone image, bar motif) with BarcodeItem.VerifyReadability on, rendered for record at dpi (see Barcode.CheckReadability; findings carry stable codes for translation). Items whose data cannot be resolved or encoded are left out (Label.Validate reports expressions that fail with a record). |
# Clone() | Label | |
# ConvertToUnit(LabelUnit unit, int dpi = 203) | Label | Converts the label size and every item without own LabelItem.Unit to unit. |
# FontDownloadZpl(FontDownloadCommand command = FontDownloadCommand.DY) | string | Only the font download commands (~DY, or ~DU) for Label.Fonts, e.g. to install the fonts once and then print with Label.DownloadFonts = false. Fonts above Label.FontAsGraphicThreshold are left out. |
# For<T>() | LabelBinding<T> | Starts a strongly typed, streaming data binding (EF Core / LINQ / any IEnumerable or IAsyncEnumerable). |
static # FromJson(string json) | Label | Loads a JSON template of any schema version (older versions are migrated). |
static # FromJson(string json, bool strict) | Label | Loads a JSON template of any schema version (older versions are migrated). With strict, properties the model does not know (typos, names of an outdated schema) throw a JsonException instead of being skipped – use it where JSON comes from outside (APIs, generated templates). |
static # FromZpl(string zpl, ImportOptions? options = default) | LabelImportResult | Imports existing ZPL (legacy labels, exports of label design software, carrier templates) into editable label models: one Label per printed format (^XA…^XZ), one per stored format (^DF) with ^FN fields bound as LabelItem.DataFields. Element positions and all resolved parameters (^CF, ^FW, ^BY, ^MU, ^LH, ^CI …) come from the zplCore renderer. Fields the model can express are imported as typed items (text, barcode, shapes, images) after checking pixel by pixel that they print identically; the rest is kept as exact RawZplItem (see ImportOptions.Fallback). The result reports a round-trip fidelity score (FromZpl(z).Label.ToZpl() rendered against the original) and warnings with source positions. |
# Localize(string text, string? culture = default) | string | Replaces {t:key} placeholders for culture (null = Label.Culture). |
# Render(int dpi = 203, ZplOutputFormat format = ZplOutputFormat.Png, IEnumerable<IReadOnlyDictionary<string, object>>? records = default) | List<byte[]> | Renders the label(s) through the ZPL renderer. Returns one encoded image per label. |
# RenderPdf(int dpi = 203) | byte[] | |
# RenderPng(int dpi = 203) | byte[] | |
# ToHtml(int dpi = 203, IEnumerable<IReadOnlyDictionary<string, object>>? records = default, string title = "Labels") | string | HTML page with the rendered label(s) embedded as PNG (for previews, e-mails, web views). |
# ToJson() | string | |
# ToZpl(int dpi = 203, int copies = 1) | string | Generates ZPL for one label (no data binding). |
# ToZpl(IEnumerable<IReadOnlyDictionary<string, object>> records, int dpi = 203, int copiesPerRecord = 1) | string | One label per dictionary record (keys = LabelItem.DataField names). |
# ToZpl<T>(IEnumerable<T> data, int dpi = 203, int copiesPerRecord = 1) | string | One label per object; data fields are property paths like "Customer.Address.City". |
# ToZplAt(int index, int dpi = 203) | string | ZPL of the unbound label as the index-th printed label (counters advanced). |
# Validate(IReadOnlyDictionary<string, object>? record = default) | List<string> | Checks the label: item names must be unique (they are referenced by [Name] in expressions, TextItem.OverflowItemName and Label.FindItem), and text items against TextItem.ValidationRegex/TextItem.InputMask for one record. Messages are English. |
# Validate(IReadOnlyDictionary<string, object> record, int dpi) | List<string> | Label.Validate, with artistic barcodes (module/finder shapes, logo, halftone image, bar motif) decoded after rendering at dpi: codes that do not read, were weakened to read, or have low contrast or small shaped modules are reported (BarcodeItem.VerifyReadability switches it off per item, BarcodeItem.ValidationErrorMessage replaces the messages). |