Skip to main content
View as Markdown

IPCB_Dimension interface

The base interface of the dimension objects of a PCB document, which show dimensional details of the board in imperial or metric units and can be placed on any layer.

public interface IPCB_Dimension : IPCB_Group

Namespace: PCB · Assembly: Altium.SDK.Interfaces

Inherits: IPCB_Primitive → IPCB_Group

Derived: IPCB_AngularDimension, IPCB_BaselineDimension, IPCB_CenterDimension, IPCB_DatumDimension, IPCB_LeaderDimension, IPCB_LinearDimension, IPCB_OriginalDimension, IPCB_RadialDimension

Remarks​

Altium Designer has several dimension styles: linear, angular, radial, leader, datum, baseline, center, linear diameter and radial diameter dimensions. IPCB_Dimension is the base interface of IPCB_OriginalDimension, IPCB_LinearDimension, IPCB_AngularDimension, IPCB_RadialDimension, IPCB_LeaderDimension, IPCB_DatumDimension, IPCB_BaselineDimension, IPCB_CenterDimension, IPCB_LinearDiameterDimension and IPCB_RadialDiameterDimension. Original dimensions (IPCB_OriginalDimension) are the dimension style of early versions.

The DimensionKind property tells which kind of dimension an object is.

A dimension is a group whose tracks, arcs and texts are generated from its references and its style properties. SetState_XSizeYSize regenerates them only when the dimension's location, X1Location, Y1Location, Layer, TextX or TextY has changed since the last regeneration. Moving or rotating the dimension with MoveByXY or RotateAroundXY also marks it for regeneration.

A dimension, especially a baseline or a leader dimension, has several references. A reference ties the dimension to a point on an object it measures; the distance between two reference points is the dimensional length.

Properties​

PropertyTypeAccessDescription
ArrowLengthintget; setThe length of the dimension's arrow lines, in internal units (10,000 per mil).
ArrowLineWidthintget; setThe line width of the arrowheads, in internal units (10,000 per mil).
ArrowPositionTDimensionArrowPositionget; setWhether the arrowheads are drawn inside or outside the measured span.
ArrowSizeintget; setThe length of the arrowheads, in internal units (10,000 per mil).
Boldboolget; setWhether the dimension text is bold when it uses a TrueType font (UseTTFonts).
DimensionKindTDimensionKindget; setThe kind of dimension, such as linear, angular or radial.
ExtensionLineWidthintget; setThe line width of the extension lines, in internal units (10,000 per mil).
ExtensionOffsetintget; setHow far the extension lines extend beyond the dimension line, in internal units (10,000 per mil).
ExtensionPickGapintget; setThe gap between a referenced object and the start of its extension line, in internal units (10,000 per mil).
FontNamestringget; setThe name of the TrueType font of the dimension text, used when UseTTFonts is true.
Italicboolget; setWhether the dimension text is italic when it uses a TrueType font (UseTTFonts).
LineWidthintget; setThe width of the lines drawn by center and original dimensions, in internal units (10,000 per mil).
ReferencesDimensionReferenceget; setThe reference at the given index, with its point and anchor.
References_CountintgetThe number of references of the dimension.
Sizeintget; setA size used by some dimension kinds, in internal units (10,000 per mil).
StyleTUnitStyleget; setHow an original dimension shows the unit of its value.
TextDimensionUnitTDimensionUnitget; setThe unit in which the measured value is shown.
TextFontshortget; setThe stroke font of the dimension text, used when UseTTFonts is false.
TextFormatstringget; setHow the measured value is formatted in the dimension text.
TextGapintget; setThe gap kept between the dimension text and the dimension lines, in internal units (10,000 per mil).
TextHeightintget; setThe height of the dimension text, in internal units (10,000 per mil).
TextLineWidthintget; setThe stroke width of the dimension text, in internal units (10,000 per mil).
TextPositionTDimensionTextPositionget; setWhere the dimension text is placed relative to the dimension line.
TextPrecisionintget; setThe number of digits after the decimal point in the measured value.
TextPrefixstringget; setText shown before the measured value.
TextSuffixstringget; setText shown after the measured value.
TextValuedoubleget; setThe measured value shown in the dimension text.
TextWidthintget; setThe stroke width of the text of an original dimension, in internal units (10,000 per mil).
TextXintget; setThe X coordinate of the dimension text position, in internal units (10,000 per mil).
TextYintget; setThe Y coordinate of the dimension text position, in internal units (10,000 per mil).
UseTTFontsboolget; setWhether the dimension text uses a TrueType font (FontName, Bold, Italic) instead of the stroke font TextFont.
X1Locationintget; setThe X coordinate of the dimension's second point, in internal units (10,000 per mil).
Y1Locationintget; setThe Y coordinate of the dimension's second point, in internal units (10,000 per mil).

ArrowLength​

The length of the dimension's arrow lines, in internal units (10,000 per mil).

int GetState_ArrowLength();
void SetState_ArrowLength(int argValue);

Type: int · Access: read/write

For linear dimensions with ArrowPosition set to TDimensionArrowPosition.eOutside, the arrows are drawn outside the measured span on lines of this length. The default is 100 mil.

ArrowLineWidth​

The line width of the arrowheads, in internal units (10,000 per mil).

int GetState_ArrowLineWidth();
void SetState_ArrowLineWidth(int argValue);

Type: int · Access: read/write

The default is 10 mil. Linear and radial dimensions also draw their dimension line with this width, and leader dimensions draw all their lines and their enclosure with it. Original dimensions do not use it: they draw all their tracks with LineWidth.

ArrowPosition​

Whether the arrowheads are drawn inside or outside the measured span.

TDimensionArrowPosition GetState_ArrowPosition();
void SetState_ArrowPosition(TDimensionArrowPosition argValue);

Type: TDimensionArrowPosition · Access: read/write

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

The default is TDimensionArrowPosition.eInside, and TDimensionArrowPosition.eOutside for radial and radial diameter dimensions.

ArrowSize​

The length of the arrowheads, in internal units (10,000 per mil).

int GetState_ArrowSize();
void SetState_ArrowSize(int argValue);

Type: int · Access: read/write

The default is 60 mil. Original dimensions do not use it: their arrowheads are TextHeight long.

Bold​

Whether the dimension text is bold when it uses a TrueType font (UseTTFonts).

bool GetState_Bold();
void SetState_Bold(bool argBold);

Type: bool · Access: read/write

The default is false.

DimensionKind​

The kind of dimension, such as linear, angular or radial.

TDimensionKind GetState_DimensionKind();
void SetState_DimensionKind(TDimensionKind argValue);

Type: TDimensionKind · Access: read/write

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

Each kind of dimension object sets this value when it is created. Read it to find out which derived interface, such as IPCB_LinearDimension or IPCB_AngularDimension, the object implements.

ExtensionLineWidth​

The line width of the extension lines, in internal units (10,000 per mil).

int GetState_ExtensionLineWidth();
void SetState_ExtensionLineWidth(int argValue);

Type: int · Access: read/write

The default is 10 mil.

ExtensionOffset​

How far the extension lines extend beyond the dimension line, in internal units (10,000 per mil).

int GetState_ExtensionOffset();
void SetState_ExtensionOffset(int argValue);

Type: int · Access: read/write

The default is 10 mil.

ExtensionPickGap​

The gap between a referenced object and the start of its extension line, in internal units (10,000 per mil).

int GetState_ExtensionPickGap();
void SetState_ExtensionPickGap(int argValue);

Type: int · Access: read/write

For a pad, via, track or arc the gap is measured from the object's edge: half the pad's larger size, half the via's size or half the line width is added to it. The default is 10 mil.

FontName​

The name of the TrueType font of the dimension text, used when UseTTFonts is true.

string GetState_FontName();
void SetState_FontName(string argFontName);

Type: string · Access: read/write

The default is "Arial".

Italic​

Whether the dimension text is italic when it uses a TrueType font (UseTTFonts).

bool GetState_Italic();
void SetState_Italic(bool argItalic);

Type: bool · Access: read/write

The default is false.

LineWidth​

The width of the lines drawn by center and original dimensions, in internal units (10,000 per mil).

int GetState_LineWidth();
void SetState_LineWidth(int argValue);

Type: int · Access: read/write

The default is 10 mil.

References​

The reference at the given index, with its point and anchor.

DimensionReference GetState_References(int argI);
void SetState_References(int argI, DimensionReference argValue);

Type: DimensionReference · Access: read/write · Index: argI (int): The zero-based index of the reference, from 0 to References_Count - 1.

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

References_Count​

The number of references of the dimension.

int GetState_References_Count();

Type: int · Access: read-only

Size​

A size used by some dimension kinds, in internal units (10,000 per mil).

int GetState_Size();
void SetState_Size(int argValue);

Type: int · Access: read/write

A center dimension uses it as the size of its cross, a leader dimension as the size of the circle or square at its end, and an original dimension as the distance its end marks extend on each side of the dimension line. The default is 10 mil, 60 mil for center and 500 mil for leader dimensions.

Style​

How an original dimension shows the unit of its value.

TUnitStyle GetState_Style();
void SetState_Style(TUnitStyle argValue);

Type: TUnitStyle · Access: read/write

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

TUnitStyle.eNoUnits shows the value only, TUnitStyle.eYesUnits the value with its unit and TUnitStyle.eParenthUnits the value followed by the unit in parentheses. The value is shown in the board's display unit. A new original dimension uses TUnitStyle.eParenthUnits. Other dimension kinds format their text with TextFormat, TextDimensionUnit and TextPrecision.

TextDimensionUnit​

The unit in which the measured value is shown.

TDimensionUnit GetState_TextDimensionUnit();
void SetState_TextDimensionUnit(TDimensionUnit argValue);

Type: TDimensionUnit · Access: read/write

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

Distances are shown in TDimensionUnit.eMils, TDimensionUnit.eInches, TDimensionUnit.eMillimeters or TDimensionUnit.eCentimeters; TDimensionUnit.eAutomaticUnit uses millimeters when the board's display unit is metric and mils otherwise. Angles are shown in radians when the unit is TDimensionUnit.eRadians and in degrees otherwise. The default is TDimensionUnit.eMils, and TDimensionUnit.eDegrees for angular dimensions.

TextFont​

The stroke font of the dimension text, used when UseTTFonts is false.

short GetState_TextFont();
void SetState_TextFont(short argValue);

Type: short · Access: read/write

TextFormat​

How the measured value is formatted in the dimension text.

string GetState_TextFormat();
void SetState_TextFormat(string argValue);

Type: string · Access: read/write

For a distance, an empty string shows no value, "10" shows the value only, "10mil" the value followed by the unit abbreviation and "10 (mil)" the value followed by the unit in parentheses. For an angle in degrees, "10" shows whole degrees, "1010" degrees and minutes, and "101010**" degrees, minutes and seconds; any other string shows whole degrees followed by a degree sign, which is the default of angular dimensions. The default for distances is "10". A leader dimension shows this string itself as its label; its default is "String".

TextGap​

The gap kept between the dimension text and the dimension lines, in internal units (10,000 per mil).

int GetState_TextGap();
void SetState_TextGap(int argValue);

Type: int · Access: read/write

The default is 10 mil. Original dimensions do not use it: they keep a fixed gap of 10 mil on each side of their text.

TextHeight​

The height of the dimension text, in internal units (10,000 per mil).

int GetState_TextHeight();
void SetState_TextHeight(int argValue);

Type: int · Access: read/write

The default is 60 mil.

TextLineWidth​

The stroke width of the dimension text, in internal units (10,000 per mil).

int GetState_TextLineWidth();
void SetState_TextLineWidth(int argValue);

Type: int · Access: read/write

The default is 6 mil. Original dimensions use TextWidth instead.

TextPosition​

Where the dimension text is placed relative to the dimension line.

TDimensionTextPosition GetState_TextPosition();
void SetState_TextPosition(TDimensionTextPosition argValue);

Type: TDimensionTextPosition · Access: read/write

The accessors are extension methods of IPCB_DimensionHelper (using PCB;).

With TDimensionTextPosition.eTextManual the text is not repositioned when the dimension is regenerated; with any other value its position and rotation are calculated from the dimension line. The default is TDimensionTextPosition.eTextAuto, and TDimensionTextPosition.eTextUniDirectional for radial, radial diameter, leader and datum dimensions. Original dimensions do not use it: they always reposition their text.

TextPrecision​

The number of digits after the decimal point in the measured value.

int GetState_TextPrecision();
void SetState_TextPrecision(int argValue);

Type: int · Access: read/write

For an angle shown as degrees, minutes and seconds it applies to the seconds. The default is 2.

TextPrefix​

Text shown before the measured value.

string GetState_TextPrefix();
void SetState_TextPrefix(string argValue);

Type: string · Access: read/write

Assigning a value calls ResetPrefixIfNeeded, so on linear diameter and radial diameter dimensions a prefix that does not start with the diameter symbol is replaced by the symbol followed by a space. The default is empty, "R " for radial dimensions and a diameter symbol followed by a space for linear diameter and radial diameter dimensions.

TextSuffix​

Text shown after the measured value.

string GetState_TextSuffix();
void SetState_TextSuffix(string argValue);

Type: string · Access: read/write

TextValue​

The measured value shown in the dimension text.

double GetState_TextValue();
void SetState_TextValue(double argValue);

Type: double · Access: read/write

Linear, angular, radial, datum, baseline and linear diameter dimensions set it to the measured value each time their primitives are regenerated, so an assigned value can be overwritten. Original dimensions do not use it: their text shows the distance between their two points.

TextWidth​

The stroke width of the text of an original dimension, in internal units (10,000 per mil).

int GetState_TextWidth();
void SetState_TextWidth(int argValue);

Type: int · Access: read/write

The default is 6 mil. Other dimension kinds use TextLineWidth.

TextX​

The X coordinate of the dimension text position, in internal units (10,000 per mil).

int GetState_TextX();
void SetState_TextX(int argValue);

Type: int · Access: read/write

TextY​

The Y coordinate of the dimension text position, in internal units (10,000 per mil).

int GetState_TextY();
void SetState_TextY(int argValue);

Type: int · Access: read/write

UseTTFonts​

Whether the dimension text uses a TrueType font (FontName, Bold, Italic) instead of the stroke font TextFont.

bool GetState_UseTTFonts();
void SetState_UseTTFonts(bool argUseTTFonts);

Type: bool · Access: read/write

The default is false.

X1Location​

The X coordinate of the dimension's second point, in internal units (10,000 per mil).

int GetState_X1Location();
void SetState_X1Location(int argValue);

Type: int · Access: read/write

For an original dimension, the measured length is the distance from (XLocation, YLocation) to (X1Location, Y1Location). Moving, rotating or mirroring an original dimension moves this point with it.

Y1Location​

The Y coordinate of the dimension's second point, in internal units (10,000 per mil).

int GetState_Y1Location();
void SetState_Y1Location(int argValue);

Type: int · Access: read/write

For an original dimension, the measured length is the distance from (XLocation, YLocation) to (X1Location, Y1Location). Moving, rotating or mirroring an original dimension moves this point with it.

Methods​

MethodReturnsDescription
MoveTextByXYvoidMoves the dimension text by an offset, changing TextX and TextY.
MoveTextToXYvoidMoves the dimension text to a new position, setting TextX and TextY.
References_AddvoidAdds a reference at the end of the dimension's references.
References_DeletevoidDetaches the reference at the given index from the object it refers to.
References_DeleteLastvoidRemoves the last reference of the dimension, reducing References_Count by one.
References_IndexOfintSearches the dimension's references for one that refers to the given primitive.
References_ValidateboolChecks that each reference still matches a point on the object it refers to, and reattaches the references that do not.
ResetPrefixIfNeededvoidMakes the text prefix of a diameter dimension start with a diameter symbol.
RotateAroundXYvoidRotates the dimension around a point.

MoveTextByXY​

Moves the dimension text by an offset, changing TextX and TextY.

void MoveTextByXY(int argX, int argY);
ParameterTypePassingDescription
argXintvalueThe horizontal offset, in internal units (10,000 per mil).
argYintvalueThe vertical offset, in internal units (10,000 per mil).

Returns: nothing (void)

MoveTextToXY​

Moves the dimension text to a new position, setting TextX and TextY.

void MoveTextToXY(int argX, int argY);
ParameterTypePassingDescription
argXintvalueThe X coordinate of the new text position, in internal units (10,000 per mil).
argYintvalueThe Y coordinate of the new text position, in internal units (10,000 per mil).

Returns: nothing (void)

For an angular dimension, the radius and the sector of the dimension are recalculated from the new position. For a center dimension, Size is set to twice the distance from the dimension's location to the new position.

References_Add​

Adds a reference at the end of the dimension's references.

void References_Add(DimensionReference argR);
void References_Add(IDimensionReference argR);
ParameterTypePassing
argRDimensionReferencevalue

Returns: nothing (void)

The first overload is an extension method of IPCB_DimensionHelper (using PCB;) with typed parameters; the second is declared by the interface.

Does nothing when the dimension already has PCBConstant.MaxReferenceCount (200) references. A leader dimension also adds a line for each reference after the first, and a datum dimension adds a text and an extension line for each reference.

References_Delete​

Detaches the reference at the given index from the object it refers to.

void References_Delete(int argIndex);
ParameterTypePassingDescription
argIndexintvalueThe zero-based index of the reference.

Returns: nothing (void)

The reference is not removed and References_Count does not change: the reference keeps the current coordinates of its point but no longer refers to the object. References_DeleteLast removes a reference.

References_DeleteLast​

Removes the last reference of the dimension, reducing References_Count by one.

void References_DeleteLast();

Returns: nothing (void)

A leader dimension also deletes the line that belonged to the reference, and a datum dimension deletes the text and the extension line that belonged to it.

References_IndexOf​

Searches the dimension's references for one that refers to the given primitive.

int References_IndexOf(IPCB_Primitive argP, int argIndex);
int References_IndexOf(object argP, int argIndex);
ParameterTypePassingDescription
argPIPCB_PrimitivevalueThe primitive to look for.
argIndexintvalueThe index of the first reference to check.

Returns: int

The first overload is an extension method of IPCB_DimensionHelper (using PCB;) with typed parameters; the second is declared by the interface.

References_Validate​

Checks that each reference still matches a point on the object it refers to, and reattaches the references that do not.

bool References_Validate();

Returns: bool

References with an anchor of -1 are skipped. A reference whose stored point no longer matches its object, at its anchor or at another anchor of the same object, is attached to the object found at the stored point on the board, or detached when no object there matches the point. Returns true when no reference had to be reattached.

ResetPrefixIfNeeded​

Makes the text prefix of a diameter dimension start with a diameter symbol.

void ResetPrefixIfNeeded();

Returns: nothing (void)

For dimensions of kind TDimensionKind.eLinearDiameterDimension or TDimensionKind.eRadialDiameterDimension a prefix that is empty or does not start with the diameter symbol is replaced by the diameter symbol followed by a space. For other kinds the prefix is left unchanged.

RotateAroundXY​

Rotates the dimension around a point.

void RotateAroundXY(int argX, int argY, double argngle);
ParameterTypePassingDescription
argXintvalueThe X coordinate of the rotation center, in internal units (10,000 per mil).
argYintvalueThe Y coordinate of the rotation center, in internal units (10,000 per mil).
argngledoublevalueThe rotation angle.

Returns: nothing (void)

When every object the dimension refers to is selected, or the dimension refers to no object, the reference points and the text position are rotated as well. Otherwise the reference points are not moved, and angular, radial and leader dimensions are not rotated at all. An original dimension always rotates both of its points together with its primitives.

Inherited members​

Returned by​

IPCB_Primitive.Dimension