Skip to main content
View as Markdown

IPCB_Component interface

A component on a PCB document, a footprint from a PCB library (or an integrated library) placed with a designator and an optional comment. A footprint can be linked to a schematic component.

public interface IPCB_Component : IPCB_Group

Namespace: PCB · Assembly: Altium.SDK.Interfaces

Inherits: IPCB_Primitive → IPCB_Group

Remarks​

Components are defined by footprints, which are stored in a PCB library. When a footprint is placed in the workspace, it is assigned a designator (and optional comment). It is then referred to as a component. A component is composed of primitives (normally tracks, arcs, and pads). The origin in the library editor defines the reference point of a footprint.

The reference point of a component is set by XLocation and YLocation, inherited from IPCB_Group. You can obtain the bounding rectangle of the component and calculate its mid point to rotate the component about its center if desired.

Rotation rotates the component about its reference point, therefore assigning Rotation and calling RotateAroundXY are equivalent only if the point you pass to RotateAroundXY is the reference point of the component.

A component is a group object and therefore composes of child objects such as arcs and tracks. You use a group iterator (GroupIterator_Create) to fetch the child objects for that component.

Properties​

PropertyTypeAccessDescription
AxisIPCB_AxisgetThe axis of the component at the given index.
AxisCountintgetThe number of axes of the component.
ChannelOffsetintget; setThe ChannelOffset represents the Channel Offset parameter for the component.
CommentIPCB_TextgetThe comment text object of the component.
CommentAutoPosTTextAutopositionget; setThe position of the comment text relative to the component.
CommentOnboolget; setWhether the comment text of the component is visible.
ComponentKindTComponentKindget; setThe kind of the component, which decides how it takes part in synchronization, electrical checks and the BOM.
DefaultPCB3DModelstringget; setThe name of the default PCB 3D model linked to this component.
EnablePartSwappingboolget; setThe property denotes the part swapping.
EnablePinSwappingboolget; setThe property denotes the pin swapping for the pins of this component.
FlippedOnLayerboolget; setNot supported; reading always returns false, and assigning a value has no effect.
FootprintConfigurableParameters_Encodedstringget; set
FootprintConfiguratorNamestringget; set
FootprintDescriptionstringget; setThe description of the component's footprint.
FPGADisplayModeTFPGADisplayModeget; set
GroupNumintget; setThis property is not used internally.
Heightintget; setThe height of the component, in internal units (10,000 per mil).
IsBGAboolgetWhether the component has been recognized as a ball grid array (BGA) package.
ItemGUIDstringget; set
ItemRevisionGUIDstringget; set
JumpersVisibleboolget; set
LockStringsboolget; setWhether the component's name and comment texts are locked, so that they cannot be moved independently of the component.
ModelHashstringgetA hash of the 3D models in the component's bodies.
NameIPCB_TextgetThe designator text object of the component.
NameAutoPosTTextAutopositionget; setThe position of the name (designator) text relative to the component.
NameOnboolget; setWhether the name (designator) text of the component is visible.
PackageSpecificHashstringgetA hash value computed from the component's primitives.
Patternstringget; setThe name of the component's footprint.
Rotationdoubleget; setThe angle of the component with respect to the horizontal axis, in degrees.
SourceCompDesignItemIDstringget; setThe design item ID of the source component; SourceLibReference reads and assigns the same value.
SourceComponentLibrarystringget; setThis source library field denotes the integrated library where the PCB component comes from.
SourceDescriptionstringget; setThis property can include a descriptive account of the reference link to a source component or a device name.
SourceDesignatorstringget; setThis property represents the current designator of the source component from the corresponding schematic.
SourceFootprintLibrarystringget; setThe library the component's footprint comes from.
SourceHierarchicalPathstringget; setThis property uniquely identifies the source reference path to the PCB component.
SourceLibReferencestringget; setThe same value as SourceCompDesignItemID; reading and assigning this property reads and assigns SourceCompDesignItemID.
SourceUniqueIdstringget; setUnique IDs (UIDs) are used to match each schematic component to the corresponding PCB component.
VaultGUIDstringget; set

Axis​

The axis of the component at the given index.

IPCB_Axis GetState_Axis(int argI);

Type: IPCB_Axis · Access: read-only · Index: argI (int): The zero-based index of the axis, less than AxisCount.

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

AxisCount​

The number of axes of the component.

int GetState_AxisCount();

Type: int · Access: read-only

ChannelOffset​

The ChannelOffset represents the Channel Offset parameter for the component. A channel offset denotes where the component is in a room especially when a room is being copied and a copy is created on the same document. The copies of rooms containing components are created based on their offsets.

int GetState_ChannelOffset();
void SetState_ChannelOffset(int argValue);

Type: int · Access: read/write

Comment​

The comment text object of the component.

IPCB_Text GetState_Comment();

Type: IPCB_Text · Access: read-only

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

See also: IPCB_Text

Examples: Extension_BOMManager

CommentAutoPos​

The position of the comment text relative to the component.

TTextAutoposition GetState_CommentAutoPos();
void SetState_CommentAutoPos(TTextAutoposition argValue);

Type: TTextAutoposition · Access: read/write

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

Assigning a value does not move the text; ChangeCommentAutoposition sets the position and moves the text.

See also: TTextAutoposition

CommentOn​

Whether the comment text of the component is visible.

bool GetState_CommentOn();
void SetState_CommentOn(bool argValue);

Type: bool · Access: read/write

ComponentKind​

The kind of the component, which decides how it takes part in synchronization, electrical checks and the BOM.

TComponentKind GetState_ComponentKind();
void SetState_ComponentKind(TComponentKind argValue);

Type: TComponentKind · Access: read/write

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

EDP.TComponentKind.eComponentKind_Standard: these components possess standard electrical properties, are always synchronized and are the type most commonly used on a board.

EDP.TComponentKind.eComponentKind_Mechanical: these components do not have electrical properties and will appear in the BOM. They are synchronized if the same components exist on both the schematic and PCB documents. An example is a heatsink.

EDP.TComponentKind.eComponentKind_Graphical: these components are not used during synchronization or checked for electrical errors. These components are used, for example, when adding company logos to documents.

EDP.TComponentKind.eComponentKind_NetTie_BOM: these components short two or more different nets for routing; they appear in the BOM and are maintained during synchronization.

EDP.TComponentKind.eComponentKind_NetTie_NoBOM: these components short two or more different nets for routing; they do not appear in the BOM and are maintained during synchronization.

Examples: Extension_BOMManager

DefaultPCB3DModel​

The name of the default PCB 3D model linked to this component.

string GetState_DefaultPCB3DModel();
void SetState_DefaultPCB3DModel(string argValue);

Type: string · Access: read/write

EnablePartSwapping​

The property denotes the part swapping. Components can have multi-parts and in this case, these multi parts can be swapped if the EnablePartSwapping is set to true.

bool GetState_EnablePartSwapping();
void SetState_EnablePartSwapping(bool argValue);

Type: bool · Access: read/write

EnablePinSwapping​

The property denotes the pin swapping for the pins of this component. In this case, these pins can be swapped if the EnablePinSwapping is set to true.

bool GetState_EnablePinSwapping();
void SetState_EnablePinSwapping(bool argValue);

Type: bool · Access: read/write

FlippedOnLayer​

Not supported; reading always returns false, and assigning a value has no effect.

bool GetState_FlippedOnLayer();
void SetState_FlippedOnLayer(bool argValue);

Type: bool · Access: read/write

FootprintConfigurableParameters_Encoded​

No description yet.

string GetState_FootprintConfigurableParameters_Encoded();
void SetState_FootprintConfigurableParameters_Encoded(string argValue);

Type: string · Access: read/write

FootprintConfiguratorName​

No description yet.

string GetState_FootprintConfiguratorName();
void SetState_FootprintConfiguratorName(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

FootprintDescription​

The description of the component's footprint.

string GetState_FootprintDescription();
void SetState_FootprintDescription(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

FPGADisplayMode​

No description yet.

TFPGADisplayMode GetState_FPGADisplayMode();
void SetState_FPGADisplayMode(TFPGADisplayMode argValue);

Type: TFPGADisplayMode · Access: read/write

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

GroupNum​

This property is not used internally. Can use for specific purposes such as a tag or an index.

int GetState_GroupNum();
void SetState_GroupNum(int argValue);

Type: int · Access: read/write

Height​

The height of the component, in internal units (10,000 per mil). It is used for the 3D viewer which works out the heights of components before displaying components in a 3D view.

int GetState_Height();
void SetState_Height(int argValue);

Type: int · Access: read/write

Examples: Extension_BOMManager

IsBGA​

Whether the component has been recognized as a ball grid array (BGA) package.

bool GetState_IsBGA();

Type: bool · Access: read-only

ItemGUID​

No description yet.

string GetState_ItemGUID();
void SetState_ItemGUID(string argValue);

Type: string · Access: read/write

ItemRevisionGUID​

No description yet.

string GetState_ItemRevisionGUID();
void SetState_ItemRevisionGUID(string argValue);

Type: string · Access: read/write

JumpersVisible​

No description yet.

bool GetState_JumpersVisible();
void SetState_JumpersVisible(bool argValue);

Type: bool · Access: read/write

LockStrings​

Whether the component's name and comment texts are locked, so that they cannot be moved independently of the component.

bool GetState_LockStrings();
void SetState_LockStrings(bool argValue);

Type: bool · Access: read/write

ModelHash​

A hash of the 3D models in the component's bodies.

string GetState_ModelHash();

Type: string · Access: read-only

The hash covers each model with its origin, rotations and vertical offset. It is an empty string when no component body of the component has a 3D model.

Name​

The designator text object of the component.

IPCB_Text GetState_Name();

Type: IPCB_Text · Access: read-only

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

See also: IPCB_Text

NameAutoPos​

The position of the name (designator) text relative to the component.

TTextAutoposition GetState_NameAutoPos();
void SetState_NameAutoPos(TTextAutoposition argValue);

Type: TTextAutoposition · Access: read/write

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

Assigning a value does not move the text; ChangeNameAutoposition sets the position and moves the text.

See also: TTextAutoposition

NameOn​

Whether the name (designator) text of the component is visible.

bool GetState_NameOn();
void SetState_NameOn(bool argValue);

Type: bool · Access: read/write

PackageSpecificHash​

A hash value computed from the component's primitives.

string GetState_PackageSpecificHash();

Type: string · Access: read-only

Pattern​

The name of the component's footprint.

string GetState_Pattern();
void SetState_Pattern(string argValue);

Type: string · Access: read/write

Leading and trailing spaces are removed from an assigned value.

Rotation​

The angle of the component with respect to the horizontal axis, in degrees.

double GetState_Rotation();
void SetState_Rotation(double argValue);

Type: double · Access: read/write

Assigning a different value rotates the component, with its primitives, about its reference point (XLocation, YLocation) by the difference.

SourceCompDesignItemID​

The design item ID of the source component; SourceLibReference reads and assigns the same value.

string GetState_SourceCompDesignItemID();
void SetState_SourceCompDesignItemID(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

SourceComponentLibrary​

This source library field denotes the integrated library where the PCB component comes from. Note: When a schematic is transferred to a blank PCB using the Update command, the source reference links for each PCB footprint is populated with source library path names.

string GetState_SourceComponentLibrary();
void SetState_SourceComponentLibrary(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

SourceDescription​

This property can include a descriptive account of the reference link to a source component or a device name.

string GetState_SourceDescription();
void SetState_SourceDescription(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

SourceDesignator​

This property represents the current designator of the source component from the corresponding schematic.

string GetState_SourceDesignator();
void SetState_SourceDesignator(string argValue);

Type: string · Access: read/write

Examples: Extension_BOMManager

SourceFootprintLibrary​

The library the component's footprint comes from.

string GetState_SourceFootprintLibrary();
void SetState_SourceFootprintLibrary(string argValue);

Type: string · Access: read/write

Footprints are stored in PCB library files or integrated libraries, which can be edited using the PCB Library Editor to create new footprints or edit existing ones. LoadCompFromLibrary reads the footprint from this library when Pattern is a plain footprint name.

Examples: Extension_BOMManager

SourceHierarchicalPath​

This property uniquely identifies the source reference path to the PCB component. The path can be multi-level depending on whether it is a multi channel (sheet symbols) or a normal design (schematic sheets).

string GetState_SourceHierarchicalPath();
void SetState_SourceHierarchicalPath(string argValue);

Type: string · Access: read/write

SourceLibReference​

The same value as SourceCompDesignItemID; reading and assigning this property reads and assigns SourceCompDesignItemID.

string GetState_SourceLibReference();
void SetState_SourceLibReference(string argValue);

Type: string · Access: read/write

SourceUniqueId​

Unique IDs (UIDs) are used to match each schematic component to the corresponding PCB component.

string GetState_SourceUniqueId();
void SetState_SourceUniqueId(string argValue);

Type: string · Access: read/write

The Unique Identifier (UID) is a system generated value that uniquely identifies the source component.

VaultGUID​

No description yet.

string GetState_VaultGUID();
void SetState_VaultGUID(string argValue);

Type: string · Access: read/write

Methods​

MethodReturnsDescription
AddAxisIPCB_AxisAdds a new axis to the component and returns it.
AutoPosition_NameCommentvoidPlaces the name and the comment of the component at their automatic positions.
AutoPosition_NameComment_APILikevoid
BoundingRectangleNoNameCommentCoordRectReturns the bounding rectangle of the component without its name and comment texts.
BoundingRectangleNoNameCommentForSignalsCoordRectReturns the bounding rectangle of the component's tracks, arcs, pads and regions, without its name and comment texts.
ChangeAutopositionNameCommentvoidPlaces the name and the comment again at their automatic positions (NameAutoPos, CommentAutoPos).
ChangeCommentAutopositionboolSets CommentAutoPos to the given position and moves the comment text there.
ChangeNameAutopositionboolSets NameAutoPos to the given position and moves the name text there.
ClearAxesvoidRemoves all axes from the component.
FlipComponentvoidMoves the component from the top layer to the bottom layer, or from the bottom layer to the top layer.
Getstate_PadByNameIPCB_PrimitiveReturns the first pad of the component with the given name, or null when the component has no such pad.
IsConfigurableFootprintbool
IsFittedboolReturns whether the component is fitted in the current variant of the board.
IsPackageEqualboolReturns whether the given component has the same package as this component, comparing their primitives.
IsPackageEqualExboolReturns whether the given component has the same package as this component, using the given comparison options.
LoadCompFromLibraryboolReloads the component's primitives from the library footprint named by Pattern.
LoadFromLibraryboolLoads the component's primitives from the library footprint described by a parameter string.
RebuildvoidReloads the component from the library footprint named by Pattern and applies the component's rotation again.
ResetDisplacementvoidResets the component's displacement to the identity transformation.
RotateAroundXYvoidRotates the component about a point.
SaveModelToFileboolSaves the component's 3D model to a file.
SaveModelToFileAsPartboolSaves the component's 3D model to a file as a part.
SaveModelToOccDocboolWrites the component's 3D model into the given document.
SetState_XSizeYSize_1bool

AddAxis​

Adds a new axis to the component and returns it.

IPCB_Axis AddAxis();

Returns: IPCB_Axis

Extension method of IPCB_ComponentHelper (using PCB;).

AutoPosition_NameComment​

Places the name and the comment of the component at their automatic positions.

void AutoPosition_NameComment();

Returns: nothing (void)

A name or comment whose position (NameAutoPos, CommentAutoPos) is TTextAutoposition.eAutoPos_Manual is placed at the top left and keeps its manual setting.

AutoPosition_NameComment_APILike​

No description yet.

void AutoPosition_NameComment_APILike();

Returns: nothing (void)

BoundingRectangleNoNameComment​

Returns the bounding rectangle of the component without its name and comment texts.

CoordRect BoundingRectangleNoNameComment();

Returns: CoordRect

Extension method of IPCB_ComponentHelper (using PCB;).

BoundingRectangleNoNameCommentForSignals​

Returns the bounding rectangle of the component's tracks, arcs, pads and regions, without its name and comment texts.

CoordRect BoundingRectangleNoNameCommentForSignals();

Returns: CoordRect

Extension method of IPCB_ComponentHelper (using PCB;).

A pad contributes its shapes on the top and the bottom layer. When the component has none of these primitives, the rectangle is a 10 mil square centered on the reference point.

ChangeAutopositionNameComment​

Places the name and the comment again at their automatic positions (NameAutoPos, CommentAutoPos).

void ChangeAutopositionNameComment();

Returns: nothing (void)

A name or comment whose position is TTextAutoposition.eAutoPos_Manual is left where it is.

ChangeCommentAutoposition​

Sets CommentAutoPos to the given position and moves the comment text there.

bool ChangeCommentAutoposition(TTextAutoposition argValue);
bool ChangeCommentAutoposition(int argValue);
ParameterTypePassingDescription
argValueTTextAutopositionvalueThe position of the comment text relative to the component.

Returns: bool

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

While CommentOn is false the position is only stored and the text is not moved. Returns false when the text could not be placed, or when the comment is hidden and the position is TTextAutoposition.eAutoPos_Manual.

ChangeNameAutoposition​

Sets NameAutoPos to the given position and moves the name text there.

bool ChangeNameAutoposition(TTextAutoposition argValue);
bool ChangeNameAutoposition(int argValue);
ParameterTypePassingDescription
argValueTTextAutopositionvalueThe position of the name text relative to the component.

Returns: bool

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

While NameOn is false the position is only stored and the text is not moved. Returns false when the text could not be placed, or when the name is hidden and the position is TTextAutoposition.eAutoPos_Manual.

ClearAxes​

Removes all axes from the component.

void ClearAxes();

Returns: nothing (void)

FlipComponent​

Moves the component from the top layer to the bottom layer, or from the bottom layer to the top layer.

void FlipComponent();

Returns: nothing (void)

A component on any other layer is left unchanged.

Getstate_PadByName​

Returns the first pad of the component with the given name, or null when the component has no such pad.

IPCB_Primitive Getstate_PadByName(string argS);
ParameterTypePassingDescription
argSstringvalueThe pad name to look for; the comparison is case-sensitive.

Returns: IPCB_Primitive

Extension method of IPCB_ComponentHelper (using PCB;).

IsConfigurableFootprint​

No description yet.

bool IsConfigurableFootprint();

Returns: bool

IsFitted​

Returns whether the component is fitted in the current variant of the board.

bool IsFitted();

Returns: bool

IsPackageEqual​

Returns whether the given component has the same package as this component, comparing their primitives.

bool IsPackageEqual(IPCB_Component argComp);
bool IsPackageEqual(object argComp);
ParameterTypePassingDescription
argCompIPCB_ComponentvalueThe component to compare with.

Returns: bool

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

Returns false when the given component is null.

IsPackageEqualEx​

Returns whether the given component has the same package as this component, using the given comparison options.

bool IsPackageEqualEx(IPCB_Component argComp, TPackageCompareOptionSet argOptions);
bool IsPackageEqualEx(object argComp, ITransportSet argOptions);
ParameterTypePassingDescription
argCompIPCB_ComponentvalueThe component to compare with.
argOptionsTPackageCompareOptionSetvalueThe comparison options.

Returns: bool

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

Returns false when the given component is null. IsPackageEqual compares with no options.

See also: TPackageCompareOption

LoadCompFromLibrary​

Reloads the component's primitives from the library footprint named by Pattern.

bool LoadCompFromLibrary();

Returns: bool

Returns true when it succeeds.

When Pattern is a plain footprint name, the footprint is read from the library file in SourceFootprintLibrary; when it cannot be loaded from there, the open library documents are searched. The component keeps its location, layer and rotation. It takes SourceFootprintLibrary, FootprintDescription, DefaultPCB3DModel, VaultGUID, ItemGUID, ItemRevisionGUID and ComponentKind from the library footprint, and Height when the footprint's height is not 0.

LoadFromLibrary​

Loads the component's primitives from the library footprint described by a parameter string.

bool LoadFromLibrary(string argParams);
ParameterTypePassingDescription
argParamsstringvalueThe parameters that identify the library and the footprint, as Name=Value pairs separated by |, for example FileName=<library path>|Footprint=<footprint name>.

Returns: bool

Returns true when it succeeds.

The SDK examples create a component with IPCB_ServerInterface.PCBObjectFactory, assign its Board, call this method with FileName=<library path>|Footprint=<footprint name>, then set its layer and location and add it to the board with IPCB_Board.AddPCBObject.

Examples: Extension_PcbLibComponentToSTEP, Extension_PlaceAndMovePcbComponent

Rebuild​

Reloads the component from the library footprint named by Pattern and applies the component's rotation again.

void Rebuild();

Returns: nothing (void)

ResetDisplacement​

Resets the component's displacement to the identity transformation.

void ResetDisplacement();

Returns: nothing (void)

RotateAroundXY​

Rotates the component about a point.

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

Returns: nothing (void)

The component's primitives, its reference point (XLocation, YLocation) and its Rotation change by the rotation. To rotate the component in place, pass its reference point, or assign Rotation.

See also: IPCB_Component.Rotation

SaveModelToFile​

Saves the component's 3D model to a file.

bool SaveModelToFile(string argFullPath);
ParameterTypePassingDescription
argFullPathstringvalueThe full path of the file to write.

Returns: bool

Whether the model is saved as a part depends on a PCB editor setting; use SaveModelToFileAsPart to always save it as a part.

The SDK examples load a footprint with LoadFromLibrary, add the component to a board and call this method with a .stp path to write a STEP file.

Examples: Extension_PcbLibComponentToSTEP

SaveModelToFileAsPart​

Saves the component's 3D model to a file as a part.

bool SaveModelToFileAsPart(string argFullPath);
ParameterTypePassingDescription
argFullPathstringvalueThe full path of the file to write.

Returns: bool

SaveModelToOccDoc​

Writes the component's 3D model into the given document.

bool SaveModelToOccDoc(IOCCDocument argOccDoc);
bool SaveModelToOccDoc(object argOccDoc);
ParameterTypePassingDescription
argOccDocIOCCDocumentvalueThe document that receives the model.

Returns: bool

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

SetState_XSizeYSize_1​

No description yet.

bool SetState_XSizeYSize_1();

Returns: bool

Inherited members​

Returned by​

IPCB_Board.GetPcbComponentByRefDes, IPCB_FullComponent.GetFootprint, IPCB_Primitive.Component

Accepted by​

IPCB_ComponentPainterView.SetComponentByHandle, IFootprintConfigurator.CreateFootprint

Examples​

Used in the SDK examples: Extension_BOMManager, Extension_BOMManager, Extension_PCBUndoRedo, Extension_PcbLibComponentToSTEP, Extension_PlaceAndMovePcbComponent.