TonCut
Engine v24

Plugin Contract

This page covers ITcPlugin and ITcEnumExtensionsCallback, the two core interfaces that define the public TonCut Desktop plugin contract. It also captures host behavior inferred from the Desktop wrapper: .plg discovery, TcpInitializeV2 loading, engine compatibility checks, and extension registration.

Contract overview

ITcPlugin mixes metadata, lifecycle hooks, configuration, file handling, result export, and plot-related callbacks in a single COM-style interface. In practice, a plugin only implements the subset implied by its

set.

Key host-side expectations:

  1. The host scans Plugins\ recursively for .plg binaries.
  2. It resolves the exported TcpInitializeV2 symbol.
  3. It keeps the returned interface instance alive until shutdown.
  4. It considers the plugin compatible only when EngineVersion matches the current engine version shown in the header badge.
  5. It builds file handlers from EnumExtensions.

Core contract members

property Name: WideString read GetName;
property EngineVersion: Integer read GetEngineVersion;
property Features: TTcpFeatures read GetFeatures;

function Initialize(const aRegRoot: WideString; aLanguageId: Integer; aTonCut: ITonCut): TTcpResult; safecall;
function EnumExtensions(aType: TTcpExtensionType; aEnumCb: ITcEnumExtensionsCallback): TTcpResult; safecall;
function IsMyFile(const aFileName: WideString): TTcpResult; safecall;

The split C# starter keeps all of these members in its native shim. The managed CSV project does not declare or implement ITcPlugin.

Entrypoint rules

The entrypoint itself is not declared in a public interface unit, but the runtime rule is explicit:

TcpInitializeV2 signature

type
  TTcPluginInitialize = function(
    const aRegRoot: PChar;
    aLanguageId: Integer;
    aTonCut: ITonCut
  ): ITcPlugin; stdcall;

Your export must use the name TcpInitializeV2 and be callable through stdcall. Delphi sees it as returning an ITcPlugin, while native C++ implementations must accept that interface result as a hidden first ITcPlugin** parameter.

For the C# example, this exact native C++ entrypoint remains in the shim; no managed TcpInitializeV2 declaration is published.

Interfaces

ITcPlugin

Primary Desktop plugin interface. Implement this contract to register capabilities, react to host lifecycle events, and import or export data.

Source: SDK/include/pascal/uITcPlugin.pas

Properties

  • Property name
    EngineVersion
    Type
    Integer
    Description

    Desktop engine version targeted by the plugin.

    Declaration

    property EngineVersion: Integer read GetEngineVersion;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    Name
    Type
    WideString
    Description

    Stable internal name used by the host to identify the plugin.

    Declaration

    property Name: WideString read GetName;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    Version
    Type
    TTcpVersion
    Description

    Version value reported to the host.

    Declaration

    property Version: TTcpVersion read GetVersion;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    Title
    Type
    WideString
    Description

    Human-readable title shown to users.

    Declaration

    property Title: WideString read GetTitle;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    RegRoot
    Type
    WideString
    Description

    Plugin-specific registry root supplied by the host.

    Declaration

    property RegRoot: WideString read GetRegRoot;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    LanguageId
    Type
    Integer
    Description

    Current host language identifier.

    Declaration

    property LanguageId: Integer read GetLanguageId write SetLanguageId;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    Professional
    Type
    Boolean
    Description

    Whether the plugin targets professional functionality.

    Declaration

    property Professional: Boolean read GetProfessional;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    UiScale
    Type
    Single
    Description

    Current UI scaling factor supplied by the host.

    Declaration

    property UiScale: Single read GetUiScale write SetUiScale;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    TonCut
    Type
    ITonCut
    Description

    Host service object supplied during plugin initialization.

    Declaration

    property TonCut: ITonCut read GetTonCut;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    Features
    Type
    Description

    Feature flags advertising which plugin callbacks are implemented.

    Declaration

    property Features: TTcpFeatures read GetFeatures;

    Published SDK declaration languages: Pascal, C++.

  • Property name
    PlotterInfo
    Type
    ITcPlotterInfo
    Description

    Plotter capability descriptor returned for plot-capable plugins. TonCut can use it to constrain plugin-controlled device settings when a device Driver points at the plugin Name.

    Declaration

    property PlotterInfo: ITcPlotterInfo read GetPlotterInfo;

    Published SDK declaration languages: Pascal, C++.

Methods

  • Method name
    Initialize()
    Type
    Description

    Initialize the plugin with its registry root, current language, and host service object.

    Declaration

    function Initialize(const aRegRoot: WideString; aLanguageId: Integer; aTonCut: ITonCut): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aRegRootconst
    WideString
    Plugin-specific registry root supplied by the host.
    aLanguageId
    Integer
    Current host language identifier.
    aTonCut
    ITonCut
    Shared host service interface.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    Finalize()
    Type
    Description

    Release plugin-owned resources before unloading.

    Declaration

    function Finalize(): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    Configure()
    Type
    Description

    Show plugin configuration UI using the provided owner window.

    Declaration

    function Configure(aWindow: THandle): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    About()
    Type
    Description

    Show plugin information UI using the provided owner window.

    Declaration

    function About(aWindow: THandle): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    LoadConfig()
    Type
    Description

    Load plugin configuration from host-managed storage.

    Declaration

    function LoadConfig(const aKey: WideString; const aVersion: WideString): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aKeyconst
    WideString
    Configuration key selected by the host.
    aVersionconst
    WideString
    Configuration version tag supplied by the host.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    SaveConfig()
    Type
    Description

    Persist plugin configuration to host-managed storage.

    Declaration

    function SaveConfig(const aKey: WideString): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aKeyconst
    WideString
    Configuration key selected by the host.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    BackupConfig()
    Type
    Description

    Serialize plugin configuration into a backup payload.

    Declaration

    function BackupConfig(var aBackup: WideString): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aBackupvar
    WideString
    Serialized configuration backup payload. Passed by reference and may be updated by the callee.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    RestoreConfig()
    Type
    Description

    Restore plugin configuration from a backup payload for the selected scopes.

    Declaration

    function RestoreConfig(const aBackup: WideString; aScope: TConfigurationParts): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aBackupconst
    WideString
    Serialized configuration backup payload.
    aScope
    Configuration parts to restore from the backup payload.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    EnumExtensions()
    Type
    Description

    Enumerate the file extensions supported for the requested extension type. TonCut calls this for import, export, and result-export discovery; each callback invocation registers one visible file handler.

    Declaration

    function EnumExtensions(aType: TTcpExtensionType; aEnumCb: ITcEnumExtensionsCallback): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aType
    Extension category being enumerated.
    aEnumCb
    ITcEnumExtensionsCallback
    Callback to invoke once for each supported extension.

    Example

    function TTextPlugin.EnumExtensions(
  aType: TTcpExtensionType;
  aEnumCb: ITcEnumExtensionsCallback
): TTcpResult;
begin
  case aType of
    etImport:
      aEnumCb.Invoke(etImport, '.txt', 'Delimited text');
    etExport:
      aEnumCb.Invoke(etExport, '.txt', 'Delimited text');
    etExportResults:
      aEnumCb.Invoke(etExportResults, '.txt', 'Delimited text');
  end;

  Result := cprOK;
end;
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    IsMyFile()
    Type
    Description

    Check whether a file belongs to the plugin. Return cprOK for a confirmed match, cprNo for a clear miss, and cprMaybe for an ambiguous match. TonCut keeps searching after cprMaybe; the first cprOK wins, and a maybe-match is only used if no plugin confirms ownership.

    Declaration

    function IsMyFile(const aFileName: WideString): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aFileNameconst
    WideString
    Path of the file to inspect, load, or save.

    Example

    function TTextPlugin.IsMyFile(const aFileName: WideString): TTcpResult;
var
  lines: TStringList;
  firstLine: string;
begin
  if not SameText(ExtractFileExt(aFileName), '.txt') then
    Exit(cprNo);

  lines := TStringList.Create;
  try
    lines.LoadFromFile(aFileName, TEncoding.UTF8);
    if lines.Count = 0 then
      Exit(cprNo);

    firstLine := lines[0];

    if Pos(';', firstLine) > 0 then
      Exit(cprOK);

    if Pos(',', firstLine) > 0 then
      Exit(cprMaybe);

    Result := cprNo;
  finally
    lines.Free;
  end;
end;
    Returns
    A file-match result. TonCut stops on the first cprOK; a plugin that returns cprMaybe stays in consideration while TonCut continues asking other import plugins, and is used only if no plugin returns cprOK. Return cprNo for a clear miss, or a failure status when detection cannot be completed.
  • Method name
    LoadFile()
    Type
    Description

    Import external data into the host-owned device, material, band, project, format, and sheet collections.

    Declaration

    function LoadFile(aWindow: THandle; const aFileName: WideString; aDevices: IDevices; aMaterials: IMaterials; aBands: IBands; aProjects: IProjects; aFormats: IFormats; aSheets: ISheets): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aFileNameconst
    WideString
    Path of the file to inspect, load, or save.
    aDevices
    IDevices
    Destination device collection supplied by the host.
    aMaterials
    IMaterials
    Destination material collection supplied by the host.
    aBands
    IBands
    Destination band collection supplied by the host.
    aProjects
    IProjects
    Destination project collection supplied by the host.
    aFormats
    IFormats
    Destination or source format collection supplied by the host.
    aSheets
    ISheets
    Destination or source sheet collection supplied by the host.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    SaveFile()
    Type
    Description

    Export input-side formats and sheets to an external target.

    Declaration

    function SaveFile(aWindow: THandle; const aFileName: WideString; const aFormats: IFormats; const aSheets: ISheets): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aFileNameconst
    WideString
    Path of the file to inspect, load, or save.
    aFormatsconst
    IFormats
    Destination or source format collection supplied by the host.
    aSheetsconst
    ISheets
    Destination or source sheet collection supplied by the host.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    SaveResult()
    Type
    Description

    Save a single solution sheet to an external target.

    Declaration

    function SaveResult(aWindow: THandle; const aFileName: WideString; const aSolutionSheet: ISolutionSheet): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aFileNameconst
    WideString
    Path of the file to inspect, load, or save.
    aSolutionSheetconst
    ISolutionSheet
    Solution sheet being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    BatchSaveResult()
    Type
    Description

    Save an entire solution in batch mode.

    Declaration

    function BatchSaveResult(aWindow: THandle; aSaveTarget: TTcpSaveTarget; const aPath: WideString; const aSolution: ISolution): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aSaveTarget
    Batch save target mode selected by the host.
    aPathconst
    WideString
    Output path selected by the user or host.
    aSolutionconst
    ISolution
    Entire solution being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    Plot()
    Type
    Description

    Run the plotting workflow for one solution sheet.

    Declaration

    function Plot(aWindow: THandle; const aSolutionSheet: ISolutionSheet): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aSolutionSheetconst
    ISolutionSheet
    Solution sheet being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    BatchPlot()
    Type
    Description

    Run the plotting workflow for an entire solution.

    Declaration

    function BatchPlot(aWindow: THandle; const aSolution: ISolution): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aSolutionconst
    ISolution
    Entire solution being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    SavePlot()
    Type
    Description

    Save plot output for one solution sheet.

    Declaration

    function SavePlot(aWindow: THandle; const aFileName: WideString; const aSolutionSheet: ISolutionSheet): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aFileNameconst
    WideString
    Path of the file to inspect, load, or save.
    aSolutionSheetconst
    ISolutionSheet
    Solution sheet being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.
  • Method name
    BatchSavePlot()
    Type
    Description

    Save plot output for an entire solution in batch mode.

    Declaration

    function BatchSavePlot(aWindow: THandle; aSaveTarget: TTcpSaveTarget; const aPath: WideString; const aSolution: ISolution): TTcpResult; safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aWindow
    THandle
    Owner window handle for any UI shown by the plugin.
    aSaveTarget
    Batch save target mode selected by the host.
    aPathconst
    WideString
    Output path selected by the user or host.
    aSolutionconst
    ISolution
    Entire solution being exported, saved, or plotted.
    Returns
    TonCut plugin result code used to report success, failure, cancellation, or file-match state.

ITcEnumExtensionsCallback

Callback sink used by TonCut while a plugin enumerates the file extensions it supports for import, export, or result export.

Source: SDK/include/pascal/uITcEnumExtensionsCallback.pas

Methods

  • Method name
    Invoke()
    Type
    procedure
    Description

    Invoke the callback or event with the current payload.

    Declaration

    procedure Invoke(aType: TTcpExtensionType; const aExtension: WideString; const aName: WideString); safecall;

    Published SDK declaration languages: Pascal, C++.

    Parameters
    aType
    Extension category being enumerated.
    aExtensionconst
    WideString
    Text value for extension.
    aNameconst
    WideString
    Text value for name.

Was this page helpful?