Portakal Flutter #

Flutter integration package for Portakal, the universal thermal and label printer SDK.

• Provides the LabelPreview widget to visually render and preview label layouts before sending command streams to physical hardware.
• Supports the Preview-Before-Print workflow: resolve a label once into an immutable ResolvedLabel, review the preview widget, and compile that exact same resolved job for printing.
• Re-exports the complete pure-Dart portakal_core engine — universal AST builder, 9 protocol compilers, 9 native protocol builders, 9 parsers, encodings, and dithering.
• Re-exports portakal_core with ReceiptColumn collision shielding (hide Column), ensuring zero namespace conflict with Flutter's built-in Column widget.

Installation #

flutter pub add portakal_flutter

Headline Workflow: Preview-Before-Print #

The canonical workflow guarantees that the exact logical job reviewed in the preview is the job compiled for printing:

import 'dart:typed_data';
import 'package:flutter/material.dart';
import 'package:portakal_flutter/portakal_flutter.dart';

class ShippingLabelScreen extends StatelessWidget {
  const ShippingLabelScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // 1. Define layout with fluent Universal LabelBuilder
    final builder = label(const LabelConfig(width: 80, height: 60))
      .text('EXPRESS DELIVERY', const TextOptions(x: 20, y: 20, size: 2, bold: true))
      .line(const LineOptions(x1: 20, y1: 50, x2: 600, y2: 50, thickness: 2))
      .barcode('TRACK-998877', const BarcodeOptions(x: 20, y: 70, type: '128', height: 60))
      .qrcode('https://track.example.com/998877', const QRCodeOptions(x: 20, y: 160, cellWidth: 4))
      .box(const BoxOptions(x: 10, y: 10, width: 620, height: 460, thickness: 2));

    // 2. Resolve once into canonical logical print job
    final ResolvedLabel job = builder.resolve();

    return Scaffold(
      appBar: AppBar(title: const Text('Label Preview')),
      body: Center(
        // 3. Render preview from the resolved job
        child: LabelPreview.resolved(
          job: job,
          showMeta: true, // Shows width, height, and DPI bar
        ),
      ),
      floatingActionButton: FloatingActionButton.extended(
        label: const Text('Confirm & Print'),
        icon: const Icon(Icons.print),
        onPressed: () {
          // 4. Compile that SAME resolved job directly to Uint8List bytes
          final Uint8List tscBytes = tsc.compileResolved(job);
          final Uint8List zplBytes = zpl.compileResolved(job);

          // 5. Pass bytes to your Bluetooth, USB, or Network transport
        },
      ),
    );
  }
}

Simple Mode (Non-Interactive) #

For automated background batch jobs or quick testing where visual preview is not required, tsc.compile(builder) remains fully supported.

Byte-Safe Contract & Transport Boundary #

Portakal produces Uint8List byte streams. Transmit raw bytes directly to your communication transport (Bluetooth Low Energy, USB, or TCP Socket). Never convert printer byte streams to strings.

🎨 20-Use-Case Practical Example Gallery #

Explore runnable real-world templates in the example/ directory covering:

• Retail: Price Labels (EAN-13), Discount & Promotion Tags
• Pharmacy: Prescription Usage Labels, Batch & Expiry Alert Tags
• Restaurant: Kitchen Order Tickets (KOT), Itemized Dining Receipts
• Warehouse: Location Bin Tags (Aisle/Rack), Inventory Lot Tags
• Logistics: Cross-Border Shipping Labels, Compact Courier Routing Tags
• Tickets & Badges: Event Admission Tickets, Queue Number Slips, Visitor Badges
• Asset Management: Enterprise IT Hardware Tags
• Advanced: Structured Multi-Column Tables, Commercial Invoices, 1-bit Monochrome Bitmaps, Multilingual Text

Preview Fidelity & Standards Conformance #

Receipt Formatting without Widget Collisions #

When formatting receipts, use ReceiptColumn to avoid symbol collisions with Flutter's Column widget:

import 'package:flutter/material.dart';
import 'package:portakal_flutter/portakal_flutter.dart';

Widget buildReceiptView() {
  return Column(
    children: [
      const Text('Receipt Header'),
      Builder(
        builder: (context) {
          final receiptRow = formatRow(
            [
              const ReceiptColumn(width: 20, align: 'left'),
              const ReceiptColumn(width: 12, align: 'right'),
            ],
            ['Espresso', '\$3.50'],
            32,
          );
          return Text(receiptRow, style: const TextStyle(fontFamily: 'monospace'));
        },
      ),
    ],
  );
}

Documentation & References #

• Getting Started Guide
• Architecture & Concepts
• Universal LabelBuilder Reference
• Native Protocol Builders
• Character Encodings & Code Pages
• Raw Bytes Passthrough
• Images & Raster Graphics
• Transport & Retries
• Hardware Validation Framework
• Hardware Compatibility Matrix
• Migration Guide (pre-1.0 to 1.0)
• Issue Tracker

License #

MIT License - see LICENSE.