printer/lib/printer.dart

import 'enums/multi_byte_encoding.dart';
import 'enums/printer_alignment.dart';
import 'enums/serial_flow_control.dart';
import 'enums/serial_parity.dart';
import 'enums/serial_stop_bits.dart';
import 'models/printer_port_handle.dart';
import 'printer_platform_interface.dart';

/// Main entry point for the printer plugin.
///
/// Provides a thin wrapper around [PrinterPlatform] for port management
/// operations. All methods delegate to the platform interface.
class Printer {
  /// Returns the platform version string.
  Future<String?> getPlatformVersion() {
    return PrinterPlatform.instance.getPlatformVersion();
  }

  /// Opens a serial (COM) port with the specified parameters.
  ///
  /// Returns an integer handle on success.
  /// Throws [PrinterException] on failure.
  ///
  /// Example:
  /// ```dart
  /// final printer = Printer();
  /// final handle = await printer.openComPort(
  ///   portName: '/dev/ttyS0',
  ///   baudRate: 115200,
  /// );
  /// ```
  Future<int> openComPort({
    required String portName,
    required int baudRate,
    int dataBits = 8,
    SerialParity parity = SerialParity.none,
    SerialStopBits stopBits = SerialStopBits.one,
    SerialFlowControl flowControl = SerialFlowControl.none,
    bool autoReplyMode = true,
  }) {
    return PrinterPlatform.instance.openComPort(
      portName: portName,
      baudRate: baudRate,
      dataBits: dataBits,
      parity: parity,
      stopBits: stopBits,
      flowControl: flowControl,
      autoReplyMode: autoReplyMode,
    );
  }

  /// Opens a USB port with the specified parameters.
  ///
  /// Returns an integer handle on success.
  /// Throws [PrinterException] on failure.
  Future<int> openUsbPort({
    required String portName,
    bool autoReplyMode = true,
  }) {
    return PrinterPlatform.instance.openUsbPort(
      portName: portName,
      autoReplyMode: autoReplyMode,
    );
  }

  /// Closes a port by its integer handle.
  ///
  /// Returns true if successfully closed, false otherwise.
  Future<bool> closePort(int handle) {
    return PrinterPlatform.instance.closePort(handle);
  }

  /// Checks if a port is currently opened.
  ///
  /// Returns true if the port is open, false otherwise.
  Future<bool> isPortOpened(int handle) {
    return PrinterPlatform.instance.isPortOpened(handle);
  }

  /// Enumerates available serial (COM) ports.
  ///
  /// Returns a list of port name strings.
  Future<List<String>> enumComPorts() {
    return PrinterPlatform.instance.enumComPorts();
  }

  /// Enumerates available USB ports.
  ///
  /// Returns a list of port name strings.
  Future<List<String>> enumUsbPorts() {
    return PrinterPlatform.instance.enumUsbPorts();
  }

  /// Opens a serial port and returns a [PrinterPortHandle] for safe resource management.
  ///
  /// The returned handle can be closed via [PrinterPortHandle.close].
  Future<PrinterPortHandle> openComPortWithHandle({
    required String portName,
    required int baudRate,
    int dataBits = 8,
    SerialParity parity = SerialParity.none,
    SerialStopBits stopBits = SerialStopBits.one,
    SerialFlowControl flowControl = SerialFlowControl.none,
    bool autoReplyMode = true,
  }) async {
    final handle = await openComPort(
      portName: portName,
      baudRate: baudRate,
      dataBits: dataBits,
      parity: parity,
      stopBits: stopBits,
      flowControl: flowControl,
      autoReplyMode: autoReplyMode,
    );
    return PrinterPortHandle(
      handle: handle,
      closeCallback: closePort,
    );
  }

  /// Opens a USB port and returns a [PrinterPortHandle] for safe resource management.
  ///
  /// The returned handle can be closed via [PrinterPortHandle.close].
  Future<PrinterPortHandle> openUsbPortWithHandle({
    required String portName,
    bool autoReplyMode = true,
  }) async {
    final handle = await openUsbPort(
      portName: portName,
      autoReplyMode: autoReplyMode,
    );
    return PrinterPortHandle(
      handle: handle,
      closeCallback: closePort,
    );
  }

  /// Sets the printer to multi-byte encoding mode.
  ///
  /// Returns true on success.
  Future<bool> setMultiByteMode(int handle) {
    return PrinterPlatform.instance.setMultiByteMode(handle);
  }

  /// Sets the multi-byte character encoding.
  ///
  /// Returns true on success.
  Future<bool> setMultiByteEncoding(int handle, MultiByteEncoding encoding) {
    return PrinterPlatform.instance.setMultiByteEncoding(handle, encoding);
  }

  /// Prints text using UTF-8 encoding.
  ///
  /// The caller should ensure multi-byte mode is set to UTF-8 before calling:
  /// ```dart
  /// await printer.setMultiByteMode(handle);
  /// await printer.setMultiByteEncoding(handle, MultiByteEncoding.utf8);
  /// await printer.printText(handle, 'Hello 中文');
  /// ```
  ///
  /// Returns true on success.
  Future<bool> printText(int handle, String text) {
    return PrinterPlatform.instance.printText(handle, text);
  }

  /// Sets text alignment.
  ///
  /// Returns true on success.
  Future<bool> setAlignment(int handle, PrinterAlignment alignment) {
    return PrinterPlatform.instance.setAlignment(handle, alignment);
  }

  /// Sets text scale (width and height magnification).
  ///
  /// Both scales must be between 1 and 8.
  /// Returns true on success.
  Future<bool> setTextScale(int handle, {required int widthScale, required int heightScale}) {
    return PrinterPlatform.instance.setTextScale(
      handle,
      widthScale: widthScale,
      heightScale: heightScale,
    );
  }

  /// Sets text bold on or off.
  ///
  /// Returns true on success.
  Future<bool> setTextBold(int handle, bool bold) {
    return PrinterPlatform.instance.setTextBold(handle, bold);
  }

  /// Sets text underline level.
  ///
  /// 0 = no underline, 1 = 1-dot underline, 2 = 2-dot underline.
  /// Returns true on success.
  Future<bool> setTextUnderline(int handle, int underline) {
    return PrinterPlatform.instance.setTextUnderline(handle, underline);
  }

  /// Feeds paper by specified number of lines.
  ///
  /// Returns true on success.
  Future<bool> feedLine(int handle, int numLines) {
    return PrinterPlatform.instance.feedLine(handle, numLines);
  }

  /// Feeds paper by specified number of dots.
  ///
  /// Returns true on success.
  Future<bool> feedDot(int handle, int numDots) {
    return PrinterPlatform.instance.feedDot(handle, numDots);
  }

  /// Performs a half cut of the paper.
  ///
  /// Returns true on success.
  Future<bool> halfCutPaper(int handle) {
    return PrinterPlatform.instance.halfCutPaper(handle);
  }

  /// Performs a full cut of the paper.
  ///
  /// Returns true on success.
  Future<bool> fullCutPaper(int handle) {
    return PrinterPlatform.instance.fullCutPaper(handle);
  }
}