IPCB_Library interface

A PCB library document. A library document has a list of components (footprints), each an IPCB_LibComponent; the component in focus in the library is the current component.

public interface IPCB_Library

Namespace: PCB · Assembly: Altium.SDK.Interfaces

Remarks

The current PCB library is returned by IPCB_ServerInterface.GetCurrentPCBLibrary.

To obtain the settings of the library document, use its IPCB_Board (Board); to obtain the primitives of a footprint, obtain its IPCB_LibComponent, for example with the library iterator (LibraryIterator_Create).

All components of a library share the one board. The primitives of the current component are on that board: making another component current moves the primitives of the previous one off the board and the primitives of the new one onto it.

Properties

Property	Type	Access	Description
Board	IPCB_Board	get	The board of the PCB library document, on which the primitives of the current component reside.
CurrentComponent	IPCB_LibComponent	get; set	The current component (footprint), the one that is in focus or displayed in the PCB library document in Altium Designer.
FolderGUID	`string`	get; set	The GUID of the vault folder that the library document is linked to.
IsSingleComponentMode	`bool`	get	Whether the library is in single-component mode.
LibraryID	`int`	get	A number that identifies the library while Altium Designer runs.
LifeCycleDefinitionGUID	`string`	get; set	The GUID of the life cycle definition of the library document's vault link.
RevisionNamingSchemeGUID	`string`	get; set	The GUID of the revision naming scheme of the library document's vault link.
VaultGUID	`string`	get; set	The GUID of the vault that the library document is linked to.

Board

The board of the PCB library document, on which the primitives of the current component reside.

IPCB_Board GetState_Board();

Type: IPCB_Board · Access: read-only

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

The board also holds the settings of the library document, such as the grids and the output options.

CurrentComponent

The current component (footprint), the one that is in focus or displayed in the PCB library document in Altium Designer.

IPCB_LibComponent GetState_CurrentComponent();
void SetState_CurrentComponent(IPCB_LibComponent argComponent);

Type: IPCB_LibComponent · Access: read/write

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

Assigning a component moves the primitives of the previous current component off the library's Board and the primitives of the new one onto it. Assigning null, or a component that is not registered in this library, does nothing: when creating a new footprint programmatically, register it with RegisterComponent before making it the current component.

See also: IPCB_Group, IPCB_LibComponent

FolderGUID

The GUID of the vault folder that the library document is linked to.

string GetState_FolderGUID();
void SetState_FolderGUID(string argValue);

Type: string · Access: read/write

IsSingleComponentMode

Whether the library is in single-component mode.

bool GetState_IsSingleComponentMode();

Type: bool · Access: read-only

The mode is set from the library's file name when the file name is assigned; it is true when the document is a file-less model.

LibraryID

A number that identifies the library while Altium Designer runs.

int GetState_LibraryID();

Type: int · Access: read-only

Each library gets the next number when it is created.

LifeCycleDefinitionGUID

The GUID of the life cycle definition of the library document's vault link.

string GetState_LifeCycleDefinitionGUID();
void SetState_LifeCycleDefinitionGUID(string argValue);

Type: string · Access: read/write

RevisionNamingSchemeGUID

The GUID of the revision naming scheme of the library document's vault link.

string GetState_RevisionNamingSchemeGUID();
void SetState_RevisionNamingSchemeGUID(string argValue);

Type: string · Access: read/write

VaultGUID

The GUID of the vault that the library document is linked to.

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

Type: string · Access: read/write

Changing a non-empty value to a different one clears IPCB_LibComponent.ItemGUID and IPCB_LibComponent.ItemRevisionGUID of every component in the library.

Methods

Method	Returns	Description
AddComponent	IPCB_LibComponent	Does nothing and returns null.
ComponentCount	`int`	Returns the number of components (footprints) in the library.
CreateNewComponent	IPCB_LibComponent	Creates a new component (footprint) and adds it to the library.
DeRegisterComponent	`bool`	De-registers a component from the library, so that the library no longer recognizes it.
GetComponent	IPCB_LibComponent	Returns the component (footprint) at the given position in the library's component list.
GetComponentByName	IPCB_LibComponent	Returns the component (footprint) with the given name, or null when the library has no component of that name.
GetUniqueCompName	`string`	Returns a component name that is not yet used in the library, based on the given name.
HasServerDocument	`bool`	Returns whether the library has a `Board` and that board is attached to a server document.
LibraryIterator_Create	IPCB_LibraryIterator	Creates an iterator that fetches the footprints (`IPCB_LibComponent`) of the library.
LibraryIterator_Destroy	`void`	Destroys a library iterator created by `LibraryIterator_Create`.
LibraryLoaderSaver_Create	IPCB_LibraryLoaderSaver	Creates a library loader-saver (`IPCB_LibraryLoaderSaver`).
LibraryLoaderSaver_Destroy	`void`	Destroys a library loader-saver created by `LibraryLoaderSaver_Create`.
LinkDocumentToReleaseVault	`bool`	Links the library document to a vault folder and item, and returns whether this succeeded.
Navigate_FirstComponent	`void`	Navigates to the first component of the library and sets the focus to it.
RefreshView	`void`	Does nothing.
RegisterComponent	`bool`	Registers a new footprint in the library.
ReleaseDocument	`bool`	Releases the library document to the vault, and returns whether the release succeeded.
RemoveComponent	`void`	Removes a component from the library.
SaveComponentWithLibrary	`bool`	Saves one component of the library to a new PCB library file, and returns whether this succeeded.
SaveEmptyLibrary	`bool`	Saves a PCB library file that has the library's settings and no components, and returns whether this succeeded.
SetBoardToComponentByName	`bool`	Makes the component with the given name the current component, and returns whether this succeeded.
SetCurrentComponentReference	`void`	Sets the origin of the library's board, the reference point of the component in focus.
SplitIntoComponents	`void`	Saves each component of the library to its own PCB library file in a folder.

AddComponent

Does nothing and returns null.

IPCB_LibComponent AddComponent(string argName);

Parameter	Type	Passing
`argName`	`string`	value

Returns: IPCB_LibComponent

Extension method of IPCB_LibraryHelper (using PCB;).

To add a footprint, use CreateNewComponent, or create one with IPCB_ServerInterface.CreatePCBLibComp and add it with RegisterComponent.

ComponentCount

Returns the number of components (footprints) in the library.

int ComponentCount();

Returns: int

CreateNewComponent

Creates a new component (footprint) and adds it to the library.

IPCB_LibComponent CreateNewComponent();

Returns: IPCB_LibComponent

Extension method of IPCB_LibraryHelper (using PCB;).

The new component is named PCBComponent_1. When the library already has a component of that name, the name gets " - duplicate" appended, then a number that is increased until the name is unique.

See also: IPCB_LibComponent

DeRegisterComponent

De-registers a component from the library, so that the library no longer recognizes it.

bool DeRegisterComponent(IPCB_LibComponent argComponent);
bool DeRegisterComponent(object argComponent);

Parameter	Type	Passing
`argComponent`	IPCB_LibComponent	value

Returns: bool

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

Returns false, and does nothing, when the component is null or does not belong to this library. Otherwise the component is removed from the library's list and returns true; when it was the current component, the library has no current component afterwards. The component object itself is not destroyed (compare RemoveComponent).

See also: IPCB_LibComponent

GetComponent

Returns the component (footprint) at the given position in the library's component list.

IPCB_LibComponent GetComponent(int argI);

Parameter	Type	Passing	Description
`argI`	`int`	value	The zero-based position of the component, from 0 to `ComponentCount` - 1.

Returns: IPCB_LibComponent

Extension method of IPCB_LibraryHelper (using PCB;).

GetComponentByName

Returns the component (footprint) with the given name, or null when the library has no component of that name.

IPCB_LibComponent GetComponentByName(string argCompName);

Parameter	Type	Passing	Description
`argCompName`	`string`	value	The name of the component to find.

Returns: IPCB_LibComponent

Extension method of IPCB_LibraryHelper (using PCB;).

The name is compared with each component's IPCB_LibComponent.Pattern, ignoring case.

See also: IPCB_LibComponent

GetUniqueCompName

Returns a component name that is not yet used in the library, based on the given name.

string GetUniqueCompName(string argTestCompName);

Parameter	Type	Passing	Description
`argTestCompName`	`string`	value	The proposed component name.

Returns: string

When no component has the given name, the name is returned unchanged. Otherwise " - duplicate" is appended; when that name is taken too, a number is appended and increased until the name is unique. Names are compared ignoring case.

See also: IPCB_LibComponent

HasServerDocument

Returns whether the library has a Board and that board is attached to a server document.

bool HasServerDocument();

Returns: bool

LibraryIterator_Create

Creates an iterator that fetches the footprints (IPCB_LibComponent) of the library.

IPCB_LibraryIterator LibraryIterator_Create();

Returns: IPCB_LibraryIterator

Extension method of IPCB_LibraryHelper (using PCB;).

Destroy the iterator with LibraryIterator_Destroy when you no longer need it.

See also: IPCB_LibraryIterator, IPCB_LibComponent

Examples: Extension_PcbLibComponentToSTEP, Extension_PcbLibToImage

LibraryIterator_Destroy

Destroys a library iterator created by LibraryIterator_Create.

void LibraryIterator_Destroy(ref IPCB_LibraryIterator argIterator);
void LibraryIterator_Destroy(ref object argIterator);

Parameter	Type	Passing	Description
`argIterator`	IPCB_LibraryIterator	ref	The iterator created by `LibraryIterator_Create`; set to null on return.

Returns: nothing (void)

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

See also: IPCB_LibComponent, IPCB_LibraryIterator

Examples: Extension_PcbLibComponentToSTEP, Extension_PcbLibToImage

LibraryLoaderSaver_Create

Creates a library loader-saver (IPCB_LibraryLoaderSaver).

IPCB_LibraryLoaderSaver LibraryLoaderSaver_Create();

Returns: IPCB_LibraryLoaderSaver

Extension method of IPCB_LibraryHelper (using PCB;).

Destroy it with LibraryLoaderSaver_Destroy when you no longer need it.

LibraryLoaderSaver_Destroy

Destroys a library loader-saver created by LibraryLoaderSaver_Create.

void LibraryLoaderSaver_Destroy(ref IPCB_LibraryLoaderSaver argLoaderSaver);
void LibraryLoaderSaver_Destroy(ref object argLoaderSaver);

Parameter	Type	Passing	Description
`argLoaderSaver`	IPCB_LibraryLoaderSaver	ref	The loader-saver to destroy; set to null on return.

Returns: nothing (void)

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

LinkDocumentToReleaseVault

Links the library document to a vault folder and item, and returns whether this succeeded.

bool LinkDocumentToReleaseVault(string argParameters, ref string argErrorMsg);

Parameter	Type	Passing	Description
`argParameters`	`string`	value	The parameter string with the vault link settings.
`argErrorMsg`	`string`	ref	Receives an error message when a required GUID is missing; empty otherwise.

Returns: bool

The method acts only when the parameters set RunSilent to True; otherwise it does nothing and returns false. The parameters must then give the vault, folder, item and revision GUIDs; when one is missing, the method returns false with an error message. On success the library's VaultGUID and FolderGUID take the given values and its LifeCycleDefinitionGUID and RevisionNamingSchemeGUID become empty; when the library has exactly one component, that component's IPCB_LibComponent.ItemGUID and IPCB_LibComponent.ItemRevisionGUID take the given item and revision GUIDs.

Navigate_FirstComponent

Navigates to the first component of the library and sets the focus to it.

void Navigate_FirstComponent();

Returns: nothing (void)

Uses the library editor's navigation panel; does nothing when the library has no editor window with that panel.

See also: IPCB_LibComponent

RefreshView

Does nothing.

void RefreshView();

Returns: nothing (void)

RegisterComponent

Registers a new footprint in the library.

bool RegisterComponent(IPCB_LibComponent argComponent);
bool RegisterComponent(object argComponent);

Parameter	Type	Passing	Description
`argComponent`	IPCB_LibComponent	value	The component to add to the library.

Returns: bool

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

Returns false, and does nothing, when the component is null, its name (IPCB_LibComponent.Pattern) is empty, or the library already has a component of that name (compared ignoring case); use GetUniqueCompName to get a free name. Otherwise the component is added to the library, belongs to it from then on, and the method returns true. Registering does not make the component current.

When creating a new footprint programmatically, for example with IPCB_ServerInterface.CreatePCBLibComp, register it before making it the current component (CurrentComponent or SetBoardToComponentByName).

Example: Add a new footprint to the current PCB library and make it the current one.

using PCB;

IPCB_ServerInterface pcbServer = PCB.GlobalVars.PCBServer;
if (pcbServer == null)
    return;
IPCB_Library currentLib = pcbServer.GetCurrentPCBLibrary();
if (currentLib == null)
    return;
IPCB_LibComponent newPCBLibComp = pcbServer.CreatePCBLibComp();
newPCBLibComp.SetState_Pattern("ANewComponent");
currentLib.RegisterComponent(newPCBLibComp);
currentLib.SetState_CurrentComponent(newPCBLibComp);

See also: IPCB_LibComponent

Examples: Extension_CreatePCBLib

ReleaseDocument

Releases the library document to the vault, and returns whether the release succeeded.

bool ReleaseDocument(string argParameters, ref string argErrorMsg);

Parameter	Type	Passing	Description
`argParameters`	`string`	value
`argErrorMsg`	`string`	ref	Set to an empty string.

Returns: bool

RemoveComponent

Removes a component from the library.

void RemoveComponent(ref IPCB_LibComponent argComponent);
void RemoveComponent(ref object argComponent);

Parameter	Type	Passing	Description
`argComponent`	IPCB_LibComponent	ref	The component to remove; set to null on return.

Returns: nothing (void)

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

Does nothing when the component does not belong to this library. Otherwise the component is removed from the library editor's component list (when the editor is open) and from the library, and is destroyed; when it was the current component, the library has no current component afterwards. To remove a component from the library without destroying it, use DeRegisterComponent.

See also: IPCB_LibComponent

SaveComponentWithLibrary

Saves one component of the library to a new PCB library file, and returns whether this succeeded.

bool SaveComponentWithLibrary(string argComponentName, string argFileName);

Parameter	Type	Passing	Description
`argComponentName`	`string`	value	The name (`IPCB_LibComponent.Pattern`) of the component to save.
`argFileName`	`string`	value	The full path of the PCB library file to write.

Returns: bool

The file contains the library's settings and only the named component; the library itself is not changed. Missing folders of the path are created. Returns false when the library has no component of that name (compared ignoring case), when the folder cannot be created, or when saving fails.

SaveEmptyLibrary

Saves a PCB library file that has the library's settings and no components, and returns whether this succeeded.

bool SaveEmptyLibrary(string argFileName);

Parameter	Type	Passing	Description
`argFileName`	`string`	value	The full path of the PCB library file to write.

Returns: bool

Missing folders of the path are created. Returns false when the folder cannot be created or saving fails.

SetBoardToComponentByName

Makes the component with the given name the current component, and returns whether this succeeded.

bool SetBoardToComponentByName(string argCompName);

Parameter	Type	Passing	Description
`argCompName`	`string`	value	The name (`IPCB_LibComponent.Pattern`) of the component to make current.

Returns: bool

The primitives of the previous current component are moved off the library's Board and the primitives of the named component onto it. Returns false, and does nothing, when the library has no component of that name (compared ignoring case, as in GetComponentByName).

See also: IPCB_LibComponent

Examples: Extension_CreatePCBLib

SetCurrentComponentReference

Sets the origin of the library's board, the reference point of the component in focus.

void SetCurrentComponentReference(int argX, int argY);

Parameter	Type	Passing	Description
`argX`	`int`	value	The X coordinate of the origin, in internal units (10,000 per mil).
`argY`	`int`	value	The Y coordinate of the origin, in internal units (10,000 per mil).

Returns: nothing (void)

The method assigns the coordinates to IPCB_Board.XOrigin and IPCB_Board.YOrigin of the library's Board; it does not move the component's primitives.

See also: IPCB_LibComponent

SplitIntoComponents

Saves each component of the library to its own PCB library file in a folder.

void SplitIntoComponents(string argOutputDirectoryPath, bool argOverwriteExistingFile, bool argRemoveBadCharactersFromName);

Parameter	Type	Passing	Description
`argOutputDirectoryPath`	`string`	value	The folder to write the files to.
`argOverwriteExistingFile`	`bool`	value	True to overwrite existing files of the same name; false to give the new file a different, unused name instead.
`argRemoveBadCharactersFromName`	`bool`	value	True to also remove characters that are not allowed in file names from the component's name inside the new library; false to keep the name.

Returns: nothing (void)

Each file is named after the component's IPCB_LibComponent.Pattern, with characters that are not allowed in file names removed, and has the extension .PcbLib. The vault GUIDs of the library (VaultGUID, FolderGUID, LifeCycleDefinitionGUID, RevisionNamingSchemeGUID) are copied to the new libraries. The library itself is not changed.

Returned by

IPCB_ServerInterface.CreatePCBLibrary, IPCB_ServerInterface.GetCurrentPCBLibrary, IPCB_ServerInterface.GetPCBLibraryByLibraryID, IPCB_ServerInterface.GetPCBLibraryByPath, IPCB_ServerInterface.LoadPCBLibraryByPath, IPCB_ServerInterface.LoadPCBLibraryFromFile

Accepted by

IPCB_LibraryLoaderSaver.LoadFromFile, IPCB_LibraryLoaderSaver.SaveToFile, IPCB_ServerInterface.DestroyPCBLibrary

Examples

Used in the SDK examples: Extension_CreatePCBLib, Extension_PcbLibComponentToSTEP, Extension_PcbLibToImage.

Remarks​

Properties​

Board​

CurrentComponent​

FolderGUID​

IsSingleComponentMode​

LibraryID​

LifeCycleDefinitionGUID​

RevisionNamingSchemeGUID​

VaultGUID​

Methods​

AddComponent​

ComponentCount​

CreateNewComponent​

DeRegisterComponent​

GetComponent​

GetComponentByName​

GetUniqueCompName​

HasServerDocument​

LibraryIterator_Create​

LibraryIterator_Destroy​

LibraryLoaderSaver_Create​

LibraryLoaderSaver_Destroy​

LinkDocumentToReleaseVault​

Navigate_FirstComponent​

RefreshView​

RegisterComponent​

ReleaseDocument​

RemoveComponent​

SaveComponentWithLibrary​

SaveEmptyLibrary​

SetBoardToComponentByName​

SetCurrentComponentReference​

SplitIntoComponents​

Returned by​

Accepted by​

Examples​

Remarks

Properties

Board

CurrentComponent

FolderGUID

IsSingleComponentMode

LibraryID

LifeCycleDefinitionGUID

RevisionNamingSchemeGUID

VaultGUID

Methods

AddComponent

ComponentCount

CreateNewComponent

DeRegisterComponent

GetComponent

GetComponentByName

GetUniqueCompName

HasServerDocument

LibraryIterator_Create

LibraryIterator_Destroy

LibraryLoaderSaver_Create

LibraryLoaderSaver_Destroy

LinkDocumentToReleaseVault

Navigate_FirstComponent

RefreshView

RegisterComponent

ReleaseDocument

RemoveComponent

SaveComponentWithLibrary

SaveEmptyLibrary

SetBoardToComponentByName

SetCurrentComponentReference

SplitIntoComponents

Returned by

Accepted by

Examples