Pieces
This page covers IFormat, IFormats, IFormatChangeEvent, and IFormatChangeEventHandler. In TonCut Desktop, format is the public piece model: geometry, quantity, material, orientation, edging, grind metadata, project grouping, and commercial metadata all live here. Grind fields are part of the ABI, but TonCut currently ignores them.
Each IFormat also owns mutable ITcAlgorithmData that must travel with that piece. Its payload is opaque and implementation-defined; no public key/value schema or compatibility guarantee is provided.
If you come from the TonCut Engine terminology, read
IFormat as “piece”. The interface name stays IFormat
because that is the published Desktop ABI.
IFormat.PreviewColor is the color used when the piece is drawn in a
preview, as a TTcColor: a $RRGGBB value, clTcNone (no
preview color, the default) or clTcRandom (the host derives a stable color
from the piece's Id). GetPreviewColor and SetPreviewColor are vtable
slots appended at the end of the interface, after EndUpdate, under the same
interface GUID, so no existing slot moves; every class that implements
IFormat must add both methods. Engine version 24 carries these slots, and
the host refuses a plugin whose EngineVersion does not match.
Interfaces
IFormat
Piece definition used by Desktop importers. It combines project assignment, geometry, material, edging, grind metadata, and planning fields. Grind data is part of the ABI, but TonCut currently ignores it.
Source: SDK/include/pascal/uIFormat.pas
Properties
- Property name
- Id
- Type
- Int64
- Description
Persistent numeric identifier used by TonCut to track the object.
Declaration
property Id: Int64 read GetId write SetId;Published SDK declaration languages: Pascal, C++.
- Property name
- Project
- Type
- IProject
- Description
Project linked to the object.
Declaration
property Project: IProject read GetProject write SetProject;Published SDK declaration languages: Pascal, C++.
- Property name
- Length
- Type
- Cardinal
- Description
Length value stored on the object.
Declaration
property Length: Cardinal read GetLength write SetLength;Published SDK declaration languages: Pascal, C++.
- Property name
- Width
- Type
- Cardinal
- Description
Width value stored on the object.
Declaration
property Width: Cardinal read GetWidth write SetWidth;Published SDK declaration languages: Pascal, C++.
- Property name
- Quantity
- Type
- Cardinal
- Description
Quantity associated with the current object.
Declaration
property Quantity: Cardinal read GetQuantity write SetQuantity;Published SDK declaration languages: Pascal, C++.
- Property name
- ProcessedQuantity
- Type
- Cardinal
- Description
Quantity already processed by TonCut.
Declaration
property ProcessedQuantity: Cardinal read GetProcessedQuantity write SetProcessedQuantity;Published SDK declaration languages: Pascal, C++.
- Property name
- Ornament
- Type
- Description
Grain or ornament direction associated with the stock item.
Declaration
property Ornament: TOrnaments read GetOrnament write SetOrnament;Published SDK declaration languages: Pascal, C++.
- Property name
- Identifier
- Type
- WideString
- Description
External or user-facing identifier stored with the object.
Declaration
property Identifier: WideString read GetIdentifier write SetIdentifier;Published SDK declaration languages: Pascal, C++.
- Property name
- Description
- Type
- WideString
- Description
Longer descriptive text stored with the object.
Declaration
property Description: WideString read GetDescription write SetDescription;Published SDK declaration languages: Pascal, C++.
- Property name
- Shape
- Type
- IShape
- Description
Shape object linked to the current entity.
Declaration
property Shape: IShape read GetShape write SetShape;Published SDK declaration languages: Pascal, C++.
- Property name
- RotationStep
- Type
- TRotation
- Description
Allowed rotation step for the current object.
Declaration
property RotationStep: TRotation read GetRotationStep write SetRotationStep;Published SDK declaration languages: Pascal, C++.
- Property name
- Rotation
- Type
- TRotation
- Description
Current rotation value.
Declaration
property Rotation: TRotation read GetRotation write SetRotation;Published SDK declaration languages: Pascal, C++.
- Property name
- Mirror
- Type
- Boolean
- Description
Mirror state for the current object.
Declaration
property Mirror: Boolean read GetMirror write SetMirror;Published SDK declaration languages: Pascal, C++.
- Property name
- Material
- Type
- IMaterial
- Description
Material linked to the object.
Declaration
property Material: IMaterial read GetMaterial write SetMaterial;Published SDK declaration languages: Pascal, C++.
- Property name
- Surplus
- Type
- Cardinal
- Description
Surplus allowance stored on the object.
Declaration
property Surplus: Cardinal read GetSurplus write SetSurplus;Published SDK declaration languages: Pascal.
- Property name
- Margin
- Type
- Cardinal
- Description
Margin allowance stored on the object.
Declaration
property Margin: Cardinal read GetMargin write SetMargin;Published SDK declaration languages: Pascal.
- Property name
- Banding
- Type
- IBanding
- Description
Gets the linked banding interface.
Declaration
property Banding: IBanding read GetBanding;Published SDK declaration languages: Pascal.
- Property name
- Grinds
- Type
- IGrinds
- Description
Associated grinds collection or helper interface.
Declaration
property Grinds: IGrinds read GetGrinds;Published SDK declaration languages: Pascal.
- Property name
- Color
- Type
- WideString
- Description
Color information stored with the object.
Declaration
property Color: WideString read GetColor write SetColor;Published SDK declaration languages: Pascal.
- Property name
- Priority
- Type
- Integer
- Description
Priority level assigned to the project.
Declaration
property Priority: Integer read GetPriority write SetPriority;Published SDK declaration languages: Pascal.
- Property name
- Weight
- Type
- Double
- Description
Weight value stored on the object.
Declaration
property Weight: Double read GetWeight write SetWeight;Published SDK declaration languages: Pascal.
- Property name
- WeightModifier
- Type
- Double
- Description
Weight multiplier or correction factor.
Declaration
property WeightModifier: Double read GetWeightModifier write SetWeightModifier;Published SDK declaration languages: Pascal.
- Property name
- Group
- Type
- Word
- Description
Gets or sets group.
Declaration
property Group: Word read GetGroup write SetGroup;Published SDK declaration languages: Pascal.
- Property name
- Order
- Type
- Word
- Description
Gets or sets order.
Declaration
property Order: Word read GetOrder write SetOrder;Published SDK declaration languages: Pascal.
- Property name
- SellingPrice
- Type
- TTcPrice
- Description
Selling price assigned to the object.
Declaration
property SellingPrice: TTcPrice read GetSellingPrice write SetSellingPrice;Published SDK declaration languages: Pascal.
- Property name
- StorageCost
- Type
- TTcPrice
- Description
Gets or sets storage cost.
Declaration
property StorageCost: TTcPrice read GetStorageCost write SetStorageCost;Published SDK declaration languages: Pascal.
- Property name
- PreviewColor
- Type
- TTcColor
- Description
Gets or sets the color used when this piece is drawn in a preview, as a
TTcColor: a 24-bit RGB value packed as$RRGGBB(not the VCLTColorbyte order),clTcNone(-1, no preview color; the default) orclTcRandom(-2, the host derives a stable color from the item’sId).GetPreviewColor/SetPreviewColorare vtable slots appended at the end of the interface, afterEndUpdate, under the same interface GUID, so no existing slot moves; every implementer must add both methods. Engine version 24 carries these slots.Declaration
property PreviewColor: TTcColor read GetPreviewColor write SetPreviewColor;Published SDK declaration languages: Pascal.
- Property name
- CustomData
- Type
- WideString
- Description
Opaque custom text payload stored with the object.
Declaration
property CustomData: WideString read GetCustomData write SetCustomData;Published SDK declaration languages: Pascal.
- Property name
- AlgorithmData
- Type
- ITcAlgorithmData
- Description
Mutable access to opaque, implementation-defined algorithm data owned by the current device, material, piece, or stock sheet. No public payload schema or compatibility guarantee is provided.
Declaration
property AlgorithmData: ITcAlgorithmData read GetAlgorithmData;Published SDK declaration languages: Pascal.
- Property name
- EffectivePriority
- Type
- Integer
- Description
Gets effective priority.
Declaration
property EffectivePriority: Integer read GetEffectivePriority;Published SDK declaration languages: Pascal.
- Property name
- LeftQuantity
- Type
- Cardinal
- Description
Gets left quantity.
Declaration
property LeftQuantity: Cardinal read GetLeftQuantity;Published SDK declaration languages: Pascal.
- Property name
- TotalSurplus
- Type
- Cardinal
- Description
Combined surplus value used by the current object.
Declaration
property TotalSurplus: Cardinal read GetTotalSurplus;Published SDK declaration languages: Pascal.
- Property name
- TotalMargin
- Type
- Cardinal
- Description
Combined margin value used by the current object.
Declaration
property TotalMargin: Cardinal read GetTotalMargin;Published SDK declaration languages: Pascal.
- Property name
- TotalLength
- Type
- Cardinal
- Description
Gets total length.
Declaration
property TotalLength: Cardinal read GetTotalLength;Published SDK declaration languages: Pascal.
- Property name
- TotalWidth
- Type
- Cardinal
- Description
Total width after TonCut applies edge and surplus adjustments.
Declaration
property TotalWidth: Cardinal read GetTotalWidth;Published SDK declaration languages: Pascal.
- Property name
- TotalField
- Type
- TField
- Description
Gets total field.
Declaration
property TotalField: TField read GetTotalField;Published SDK declaration languages: Pascal.
- Property name
- GrossLength
- Type
- Cardinal
- Description
Gets gross length.
Declaration
property GrossLength: Cardinal read GetGrossLength;Published SDK declaration languages: Pascal.
- Property name
- GrossWidth
- Type
- Cardinal
- Description
Gets gross width.
Declaration
property GrossWidth: Cardinal read GetGrossWidth;Published SDK declaration languages: Pascal.
- Property name
- OnChange
- Type
- INotifyEvent
- Description
Event fired when the object or collection changes.
Declaration
property OnChange: INotifyEvent read GetOnChange;Published SDK declaration languages: Pascal.
- Property name
- OnIdChange
- Type
- IIdChangeEvent
- Description
Event fired when an identifier changes.
Declaration
property OnIdChange: IIdChangeEvent read GetOnIdChange;Published SDK declaration languages: Pascal.
Methods
- Method name
- GetShapePathAsString()
- Type
- WideString
- Description
Return an SVG-compatible path string for the current shape outline.
Declaration
function GetShapePathAsString(aRotation: Double; aMirror: Boolean; aWithOffset: Boolean; aBBoxOrigin: Boolean): WideString; safecall;Published SDK declaration languages: Pascal.
ParametersaRotationDoubleValue for rotation.aMirrorBooleanBooleanflag controlling mirror.aWithOffsetBooleanBooleanflag controlling with offset.aBBoxOriginBooleanBooleanflag controlling bbox origin.ReturnsThe SVG-compatible path string for the current shape outline.
- Method name
- GetShapeOffsetInsideBoundingBox()
- Type
- procedure
- Description
Return or populate shape offset inside bounding box.
Declaration
procedure GetShapeOffsetInsideBoundingBox(aRotation: Double; aMirror: Boolean; var aX: Double; var aY: Double); safecall;Published SDK declaration languages: Pascal.
ParametersaRotationDoubleValue for rotation.aMirrorBooleanBooleanflag controlling mirror.aXvarDoubleX coordinate value. Passed by reference and may be updated by the callee.aYvarDoubleY coordinate value. Passed by reference and may be updated by the callee.
- Method name
- Assign()
- Type
- procedure
- Description
Copy values from another object of the same type.
Declaration
procedure Assign(const aOther: IFormat; aProject: IProject); safecall;Published SDK declaration languages: Pascal.
- Method name
- UpdateEffectivePriority()
- Type
- procedure
- Description
Update effective priority.
Declaration
procedure UpdateEffectivePriority(aTriggerChange: Boolean); safecall;Published SDK declaration languages: Pascal.
ParametersaTriggerChangeBooleanBooleanflag controlling trigger change.
- Method name
- BeginUpdate()
- Type
- procedure
- Description
Start a batched update so change notifications can be delayed.
Declaration
procedure BeginUpdate(); safecall;Published SDK declaration languages: Pascal.
- Method name
- EndUpdate()
- Type
- procedure
- Description
Finish a batched update and allow deferred notifications to resume.
Declaration
procedure EndUpdate(); safecall;Published SDK declaration languages: Pascal.
IFormats
Collection interface used to create, enumerate, query, and reload a shared Desktop object set.
Source: SDK/include/pascal/uIFormats.pas
Properties
- Property name
- Count
- Type
- Integer
- Description
Number of items currently exposed by the interface.
Declaration
property Count: Integer read GetCount;Published SDK declaration languages: Pascal, C++.
- Property name
- Items
- Type
- IFormat
- Description
Indexed property used to read one item from the collection.
Declaration
property Items[aIndex: Cardinal]: IFormat read GetByIndex; default;Published SDK declaration languages: Pascal, C++.
Index ParametersaIndexCardinalZero-based position within a collection.ValueThe collection item located at the supplied index.
- Property name
- Field
- Type
- TField
- Description
Area-like value stored on the object.
Declaration
property Field: TField read GetField;Published SDK declaration languages: Pascal.
- Property name
- Quantity
- Type
- Cardinal
- Description
Quantity associated with the current object.
Declaration
property Quantity: Cardinal read GetQuantity;Published SDK declaration languages: Pascal.
- Property name
- Loading
- Type
- Boolean
- Description
Whether the project or collection is currently loading data.
Declaration
property Loading: Boolean read GetLoading write SetLoading;Published SDK declaration languages: Pascal.
- Property name
- OnAdd
- Type
- IFormatChangeEvent
- Description
Event fired when an item is added.
Declaration
property OnAdd: IFormatChangeEvent read GetOnAdd;Published SDK declaration languages: Pascal.
- Property name
- OnRemove
- Type
- IFormatChangeEvent
- Description
Event fired when an item is removed.
Declaration
property OnRemove: IFormatChangeEvent read GetOnRemove;Published SDK declaration languages: Pascal.
- Property name
- OnChange
- Type
- INotifyEvent
- Description
Event fired when the object or collection changes.
Declaration
property OnChange: INotifyEvent read GetOnChange;Published SDK declaration languages: Pascal.
Methods
- Method name
- Assign()
- Type
- procedure
- Description
Copy values from another object of the same type.
Declaration
procedure Assign(const aOther: IFormats); safecall;Published SDK declaration languages: Pascal, C++.
Parameters
- Method name
- Clear()
- Type
- procedure
- Description
Remove all items from the collection.
Declaration
procedure Clear(); safecall;Published SDK declaration languages: Pascal, C++.
- Method name
- Reload()
- Type
- procedure
- Description
Reload the underlying data from the host or storage layer.
Declaration
procedure Reload(); safecall;Published SDK declaration languages: Pascal, C++.
- Method name
- CreateFormat()
- Type
- IFormat
- Description
Create a new format instance.
Declaration
function CreateFormat(): IFormat; safecall;Published SDK declaration languages: Pascal, C++.
ReturnsA new format interface instance.
- Method name
- Add()
- Type
- procedure
- Description
Add an item or handler.
Declaration
procedure Add(aFormat: IFormat); safecall;Published SDK declaration languages: Pascal, C++.
Parameters
- Method name
- DeleteByIndex()
- Type
- procedure
- Description
Delete the item at the specified zero-based index.
Declaration
procedure DeleteByIndex(aIndex: Cardinal); safecall;Published SDK declaration languages: Pascal, C++.
ParametersaIndexCardinalZero-based position within a collection.
- Method name
- DeleteById()
- Type
- procedure
- Description
Delete the item with the specified TonCut identifier.
Declaration
procedure DeleteById(aId: Int64); safecall;Published SDK declaration languages: Pascal, C++.
ParametersaIdInt64TonCut object identifier.
- Method name
- Remove()
- Type
- procedure
- Description
Remove an item or handler.
Declaration
procedure Remove(const aFormat: IFormat); safecall;Published SDK declaration languages: Pascal, C++.
Parameters
- Method name
- IndexOf()
- Type
- Integer
- Description
Return the zero-based index of the matching item.
Declaration
function IndexOf(const aFormat: IFormat): Integer; overload; safecall;Published SDK declaration languages: Pascal.
ParametersReturnsZero-based index of the matching item, or-1when no match exists.
- Method name
- IndexOf()
- Type
- Integer
- Description
Return the zero-based index of the matching item.
Declaration
function IndexOf(aId: Int64): Integer; overload; safecall;Published SDK declaration languages: Pascal.
ParametersaIdInt64TonCut object identifier.ReturnsZero-based index of the matching item, or-1when no match exists.
- Method name
- IndexOf()
- Type
- Integer
- Description
Return the zero-based index of the matching item.
Declaration
function IndexOf(aList: array of Int64; const aMaterial: IMaterial; aLength: Cardinal; aWidth: Cardinal; aOrnament: TOrnament; var aRotated: Boolean; var aListIndex: Integer): Integer; overload; safecall;Published SDK declaration languages: Pascal.
ParametersaListarray of Int64Value for list.aLengthCardinalLength value in TonCut units.aWidthCardinalWidth value in TonCut units.aOrnamentValue for ornament.aRotatedvarBooleanBooleanflag controlling rotated. Passed by reference and may be updated by the callee.aListIndexvarIntegerValue for list index. Passed by reference and may be updated by the callee.ReturnsZero-based index of the matching item, or-1when no match exists.
- Method name
- IndexOf()
- Type
- Integer
- Description
Return the zero-based index of the matching item.
Declaration
function IndexOf(const aOtherFormat: IFormat; aSkipId: Int64; var aRotated: Boolean): Integer; overload; safecall;Published SDK declaration languages: Pascal.
ParametersaSkipIdInt64skip id value used to identify an object.aRotatedvarBooleanBooleanflag controlling rotated. Passed by reference and may be updated by the callee.ReturnsZero-based index of the matching item, or-1when no match exists.
- Method name
- Find()
- Type
- IFormat
- Description
Find an item matching the supplied criteria.
Declaration
function Find(aLength: Cardinal; aWidth: Cardinal; var aRotated: Boolean): IFormat; safecall;Published SDK declaration languages: Pascal, C++.
ParametersaLengthCardinalLength value in TonCut units.aWidthCardinalWidth value in TonCut units.aRotatedvarBooleanBooleanflag controlling rotated. Passed by reference and may be updated by the callee.ReturnsThe matching format interface instance, ornullwhen not found.
- Method name
- GetById()
- Type
- IFormat
- Description
Return the item stored under the specified TonCut identifier.
Declaration
function GetById(aId: Int64): IFormat; safecall;Published SDK declaration languages: Pascal.
ParametersaIdInt64TonCut object identifier.ReturnsThe matching format interface instance.
- Method name
- LoadByProject()
- Type
- procedure
- Description
Load by project.
Declaration
procedure LoadByProject(aProject: IProject; aFormats: IFormats); overload; safecall;Published SDK declaration languages: Pascal.
- Method name
- LoadByProject()
- Type
- procedure
- Description
Load by project.
Declaration
procedure LoadByProject(aProject: IProject); overload; safecall;Published SDK declaration languages: Pascal.
Parameters
- Method name
- GetByProject()
- Type
- IFormats
- Description
Return or populate by project.
Declaration
function GetByProject(aProject: IProject): IFormats; safecall;Published SDK declaration languages: Pascal.
ParametersReturnsThe matching formats interface instance.
- Method name
- UnloadByProject()
- Type
- procedure
- Description
Perform unload by project.
Declaration
procedure UnloadByProject(const aProject: IProject); safecall;Published SDK declaration languages: Pascal.
Parameters
- Method name
- UnloadFormat()
- Type
- procedure
- Description
Perform unload format.
Declaration
procedure UnloadFormat(const aFormat: IFormat); safecall;Published SDK declaration languages: Pascal.
Parameters
- Method name
- CalcMaxLength()
- Type
- Cardinal
- Description
Calculate max length.
Declaration
function CalcMaxLength(): Cardinal; safecall;Published SDK declaration languages: Pascal.
ReturnsThe calculated max length value.
- Method name
- BeginUpdate()
- Type
- procedure
- Description
Start a batched update so change notifications can be delayed.
Declaration
procedure BeginUpdate(); safecall;Published SDK declaration languages: Pascal.
- Method name
- EndUpdate()
- Type
- procedure
- Description
Finish a batched update and allow deferred notifications to resume.
Declaration
procedure EndUpdate(); safecall;Published SDK declaration languages: Pascal.
- Method name
- IsUpdating()
- Type
- Boolean
- Description
Report whether the interface is currently inside an update batch.
Declaration
function IsUpdating(): Boolean; safecall;Published SDK declaration languages: Pascal.
ReturnsReturnstruewhile the interface is inside aBeginUpdate/EndUpdatebatch.
IFormatChangeEventHandler
Callback sink consumed by the matching change-event interface.
Source: SDK/include/pascal/uIFormatChangeEvent.pas
Methods
- Method name
- Invoke()
- Type
- procedure
- Description
Handle the event callback when the owning event interface invokes it.
Declaration
procedure Invoke(aSender: IUnknown; aFormat: IFormat; aIndex: Integer); safecall;Published SDK declaration languages: Pascal.
ParametersaSenderIUnknownObject that raised the event.aIndexIntegerZero-based position within a collection.
IFormatChangeEvent
Event interface with Add, Remove, and Invoke hooks for collection or entity change notifications.
Source: SDK/include/pascal/uIFormatChangeEvent.pas
Methods
- Method name
- Add()
- Type
- procedure
- Description
Add an item or handler.
Declaration
procedure Add(aHandler: IFormatChangeEventHandler); safecall;Published SDK declaration languages: Pascal.
Parameters
- Method name
- Remove()
- Type
- procedure
- Description
Remove an item or handler.
Declaration
procedure Remove(aHandler: IFormatChangeEventHandler); safecall;Published SDK declaration languages: Pascal.
Parameters
- Method name
- Invoke()
- Type
- procedure
- Description
Raise the typed change event for the current payload.
Declaration
procedure Invoke(aSender: IUnknown; aFormat: IFormat; aIndex: Integer); safecall;Published SDK declaration languages: Pascal.
ParametersaSenderIUnknownObject that raised the event.aIndexIntegerEvent payload field for index.