IPCB_PrimitiveParameters interface

The parameters of a PCB primitive, such as a component, kept per project variant and per parameter set.

public interface IPCB_PrimitiveParameters

Namespace: PCB · Assembly: Altium.SDK.Interfaces

Remarks

A primitive, for example an IPCB_Component, can be cast to IPCB_PrimitiveParameters. The object obtained this way starts on the project's current variant and on the TParameterAppurtenance.paUser set; CreatePrimitiveParameters of IPCB_ParametersFactory returns one that is switched to the given variant.

The members read and change the parameters of the selected variant and the selected set: the switch methods (SwitchToDefaultVariant, SwitchToCurrentVariant, SwitchToVariantByName and the others) select the variant, SwitchAppurtenance selects the set. Changes are applied to the primitive at once. An IPCB_Parameter returned by GetParameterByIndex, GetParameterByName, FindParameterByName or ExportToList is a copy: changing it does not change the primitive.

Parameter names are unique within a set and are compared without regard to case.

A variant without parameters of its own (see IsFullyInherited) shows the parameters of the default variant, marked as inherited (IsInherited of IPCB_Parameter is true). The first change made in such a variant gives it its own parameters: a copy of the default variant's parameters, still marked as inherited, to which the change is applied; when the change fails, the variant is left without parameters of its own. A parameter of a variant that is marked as inherited reports the value of the default variant's parameter of the same name, or an empty value when the default variant has no such parameter. The default variant does not accept parameters marked as inherited.

Properties

Property	Type	Access	Description
IsFullyInherited	bool	get; set	Whether the selected variant has no parameters of its own and shows the default variant's parameters.
IsFullyInheritedAllVariants	bool	get; set	Whether no variant has parameters of its own for the primitive.
ValueByName	string	get; set	The value of the parameter with the given name in the selected variant and set.

IsFullyInherited

Whether the selected variant has no parameters of its own and shows the default variant's parameters.

bool GetIsFullyInherited();
void SetIsFullyInherited(bool argValue);

Type: bool · Access: read/write

Setting it to true removes the variant's own parameters. Setting it to false gives the variant its own parameters, a copy of the default variant's parameters marked as inherited, if it has none yet.

IsFullyInheritedAllVariants

Whether no variant has parameters of its own for the primitive.

bool GetIsFullyInheritedAllVariants();
void SetIsFullyInheritedAllVariants(bool argValue);

Type: bool · Access: read/write

Setting it to true removes the own parameters of every variant; the default variant's parameters stay. Setting it to false gives every variant of the project its own parameters, if it has none yet.

ValueByName

The value of the parameter with the given name in the selected variant and set.

string GetValueByName(string argName);
void SetValueByName(string argName, string argValue);

Type: string · Access: read/write · Index: argName (string): The parameter name.

Reading or assigning raises an error when there is no such parameter; SetOrNewValueByName adds a missing parameter.

Methods

Method	Returns	Description
AddOrSetParameter	void	Adds a parameter, or replaces the parameter of the same name, in the selected variant and set.
AddParameter	void	Adds a parameter to the selected variant and set.
Count	int	Returns the number of parameters in the selected variant and set.
ExportToList	IPCB_ParameterList	Returns a new list with copies of all parameters of the selected variant and set.
FindParameterByName	IPCB_Parameter	Returns a copy of the parameter with the given name in the selected variant and set, or null when there is none.
GetAppurtenance	TParameterAppurtenance	Returns the parameter set that the other members read and change, as selected by SwitchAppurtenance.
GetIsCurrentVariant	bool	Returns whether the selected variant is the project's current variant.
GetIsDefaultVariant	bool	Returns whether the selected variant is the default variant.
GetParameterByIndex	IPCB_Parameter	Returns a copy of the parameter at the given position in the selected variant and set.
GetParameterByName	IPCB_Parameter	Returns a copy of the parameter with the given name in the selected variant and set.
GetValueByNameDef	string	Returns the value of the parameter with the given name in the selected variant and set, or a default value when there is no such parameter.
GetVariantCount	int	Returns the number of variants that have parameters of their own for the primitive.
GetVariantIndex	int	Returns the position of the selected variant in the list of variants that have parameters of their own.
GetVariantName	string	Returns the name of the selected variant.
GetVariantUniqueID	string	Returns the unique ID of the selected variant.
ImportFromList	void	Replaces all parameters of the selected variant and set with the parameters of the given list.
NewValueByName	void	Adds a parameter with the given name and value to the selected variant and set.
RemoveAllParameters	void	Removes all parameters of the selected variant and set.
RemoveAllParametersAndVariants	void	Removes all parameters of the primitive, those of the default variant and of every variant, in every set.
RemoveByIndex	void	Removes the parameter at the given position in the selected variant and set.
RemoveByName	void	Removes the parameter with the given name from the selected variant and set.
SetOrNewValueByName	void	Sets the value of the parameter with the given name in the selected variant and set, or adds the parameter when there is none.
SetParameter	void	Replaces the parameter of the same name in the selected variant and set with the given parameter.
SwitchAppurtenance	void	Selects the parameter set that the other members read and change.
SwitchToCurrentVariant	void	Selects the project's current variant.
SwitchToDefaultVariant	void	Selects the default variant.
SwitchToVariantByIndex	void	Selects a variant by its position in the list of variants that have parameters of their own.
SwitchToVariantByName	void	Selects a variant of the project by its name.
SwitchToVariantByUniqueID	void	Selects a variant by its unique ID.
TryGetValueByName	bool	Gets the value of the parameter with the given name in the selected variant and set, and returns whether the parameter exists.
TryNewValueByName	bool	Adds a parameter with the given name and value to the selected variant and set, and returns whether it was added.
TryRemoveByName	bool	Removes the parameter with the given name from the selected variant and set, and returns whether it was removed.
TrySetValueByName	bool	Sets the value of the parameter with the given name in the selected variant and set, and returns whether it was set.
TrySwitchToNextVariant	bool	Selects the next variant that has parameters of its own, and returns whether a variant was selected.

AddOrSetParameter

Adds a parameter, or replaces the parameter of the same name, in the selected variant and set.

void AddOrSetParameter(IPCB_Parameter argParameter);
void AddOrSetParameter(object argParameter);

Parameter	Type	Passing	Description
argParameter	IPCB_Parameter	value	The parameter to add or to replace with.

Returns: nothing (void)

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

The name, the value and the inherited mark are taken from the given parameter.

AddParameter

Adds a parameter to the selected variant and set.

void AddParameter(IPCB_Parameter argParameter);
void AddParameter(object argParameter);

Parameter	Type	Passing	Description
argParameter	IPCB_Parameter	value	The parameter to add.

Returns: nothing (void)

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

Raises an error when a parameter of the same name already exists; use AddOrSetParameter to replace it.

Count

Returns the number of parameters in the selected variant and set.

int Count();

Returns: int

Returns 0 when the primitive has no parameters.

Examples: Extension_BOMManager

ExportToList

Returns a new list with copies of all parameters of the selected variant and set.

IPCB_ParameterList ExportToList();

Returns: IPCB_ParameterList

Extension method of IPCB_PrimitiveParametersHelper (using PCB;).

Changing the list or its parameters does not change the primitive. The list is empty when the primitive has no parameters.

FindParameterByName

Returns a copy of the parameter with the given name in the selected variant and set, or null when there is none.

IPCB_Parameter FindParameterByName(string argName);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.

Returns: IPCB_Parameter

Extension method of IPCB_PrimitiveParametersHelper (using PCB;).

GetAppurtenance

Returns the parameter set that the other members read and change, as selected by SwitchAppurtenance.

TParameterAppurtenance GetAppurtenance();

Returns: TParameterAppurtenance

Extension method of IPCB_PrimitiveParametersHelper (using PCB;).

GetIsCurrentVariant

Returns whether the selected variant is the project's current variant.

bool GetIsCurrentVariant();

Returns: bool

When the board has no project or the project has no current variant, the default variant counts as the current one.

GetIsDefaultVariant

Returns whether the selected variant is the default variant.

bool GetIsDefaultVariant();

Returns: bool

GetParameterByIndex

Returns a copy of the parameter at the given position in the selected variant and set.

IPCB_Parameter GetParameterByIndex(int argIndex);

Parameter	Type	Passing	Description
argIndex	int	value	The zero-based position, less than Count.

Returns: IPCB_Parameter

Extension method of IPCB_PrimitiveParametersHelper (using PCB;).

Raises an error when the index is out of range.

Examples: Extension_BOMManager

GetParameterByName

Returns a copy of the parameter with the given name in the selected variant and set.

IPCB_Parameter GetParameterByName(string argName);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.

Returns: IPCB_Parameter

Extension method of IPCB_PrimitiveParametersHelper (using PCB;).

Raises an error when there is no such parameter; FindParameterByName returns null instead.

GetValueByNameDef

Returns the value of the parameter with the given name in the selected variant and set, or a default value when there is no such parameter.

string GetValueByNameDef(string argName, string argDefault);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.
argDefault	string	value	The value returned when there is no parameter with that name.

Returns: string

GetVariantCount

Returns the number of variants that have parameters of their own for the primitive.

int GetVariantCount();

Returns: int

The default variant is not counted. SwitchToVariantByIndex and GetVariantIndex use positions in this list.

GetVariantIndex

Returns the position of the selected variant in the list of variants that have parameters of their own.

int GetVariantIndex();

Returns: int

Returns -1 for the default variant and for a variant without parameters of its own.

GetVariantName

Returns the name of the selected variant.

string GetVariantName();

Returns: string

Returns [No Variations] for the default variant. When no variant of the project has the selected unique ID, or the board has no project, it returns the unique ID.

GetVariantUniqueID

Returns the unique ID of the selected variant.

string GetVariantUniqueID();

Returns: string

The default variant's unique ID is the empty string.

ImportFromList

Replaces all parameters of the selected variant and set with the parameters of the given list.

void ImportFromList(IPCB_ParameterList argParameters);
void ImportFromList(object argParameters);

Parameter	Type	Passing	Description
argParameters	IPCB_ParameterList	value	The parameters to store.

Returns: nothing (void)

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

The existing parameters are removed first, then each parameter of the list is added. Raises an error when the list contains two parameters of the same name.

NewValueByName

Adds a parameter with the given name and value to the selected variant and set.

void NewValueByName(string argName, string argValue);

Parameter	Type	Passing	Description
argName	string	value	The name of the new parameter.
argValue	string	value	The value of the new parameter.

Returns: nothing (void)

Raises an error when a parameter of that name already exists; TryNewValueByName returns false instead.

RemoveAllParameters

Removes all parameters of the selected variant and set.

void RemoveAllParameters();

Returns: nothing (void)

RemoveAllParametersAndVariants

Removes all parameters of the primitive, those of the default variant and of every variant, in every set.

void RemoveAllParametersAndVariants();

Returns: nothing (void)

RemoveByIndex

Removes the parameter at the given position in the selected variant and set.

void RemoveByIndex(int argIndex);

Parameter	Type	Passing	Description
argIndex	int	value	The zero-based position, less than Count.

Returns: nothing (void)

Raises an error when the index is out of range.

RemoveByName

Removes the parameter with the given name from the selected variant and set.

void RemoveByName(string argName);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.

Returns: nothing (void)

Raises an error when there is no such parameter; TryRemoveByName returns false instead.

SetOrNewValueByName

Sets the value of the parameter with the given name in the selected variant and set, or adds the parameter when there is none.

void SetOrNewValueByName(string argName, string argValue);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.
argValue	string	value	The new value.

Returns: nothing (void)

The parameter is no longer marked as inherited.

SetParameter

Replaces the parameter of the same name in the selected variant and set with the given parameter.

void SetParameter(IPCB_Parameter argParameter);
void SetParameter(object argParameter);

Parameter	Type	Passing	Description
argParameter	IPCB_Parameter	value	The parameter whose name selects the parameter to replace.

Returns: nothing (void)

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

The value and the inherited mark are taken from the given parameter. Raises an error when there is no parameter of that name.

SwitchAppurtenance

Selects the parameter set that the other members read and change.

void SwitchAppurtenance(TParameterAppurtenance argValue);
void SwitchAppurtenance(int argValue);

Parameter	Type	Passing	Description
argValue	TParameterAppurtenance	value	The parameter set.

Returns: nothing (void)

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

The parameters themselves are not changed.

SwitchToCurrentVariant

Selects the project's current variant.

void SwitchToCurrentVariant();

Returns: nothing (void)

When the board has no project or the project has no current variant, the default variant is selected.

SwitchToDefaultVariant

Selects the default variant.

void SwitchToDefaultVariant();

Returns: nothing (void)

SwitchToVariantByIndex

Selects a variant by its position in the list of variants that have parameters of their own.

void SwitchToVariantByIndex(int argIndex);

Parameter	Type	Passing	Description
argIndex	int	value	The zero-based position, less than GetVariantCount.

Returns: nothing (void)

Raises an error when the index is out of range or the primitive has no parameters.

SwitchToVariantByName

Selects a variant of the project by its name.

void SwitchToVariantByName(string argVariantName);

Parameter	Type	Passing	Description
argVariantName	string	value	The variant name. [No Variations] (exactly) selects the default variant and an empty string the project's current variant; other names are compared with the project's variant names without regard to case.

Returns: nothing (void)

Raises an error when the project has no variant of that name, or when the board has no project and the name is neither [No Variations] nor empty.

SwitchToVariantByUniqueID

Selects a variant by its unique ID.

void SwitchToVariantByUniqueID(string argUniqueID);

Parameter	Type	Passing	Description
argUniqueID	string	value	The variant's unique ID; the empty string selects the default variant.

Returns: nothing (void)

The ID is not checked against the project's variants.

TryGetValueByName

Gets the value of the parameter with the given name in the selected variant and set, and returns whether the parameter exists.

bool TryGetValueByName(string argName, out string argValue);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.
argValue	string	out	Receives the value, or an empty string when there is no such parameter.

Returns: bool

TryNewValueByName

Adds a parameter with the given name and value to the selected variant and set, and returns whether it was added.

bool TryNewValueByName(string argName, string argValue);

Parameter	Type	Passing	Description
argName	string	value	The name of the new parameter.
argValue	string	value	The value of the new parameter.

Returns: bool

Returns false when a parameter of that name already exists.

TryRemoveByName

Removes the parameter with the given name from the selected variant and set, and returns whether it was removed.

bool TryRemoveByName(string argName);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.

Returns: bool

Returns false when there is no such parameter.

TrySetValueByName

Sets the value of the parameter with the given name in the selected variant and set, and returns whether it was set.

bool TrySetValueByName(string argName, string argValue);

Parameter	Type	Passing	Description
argName	string	value	The parameter name.
argValue	string	value	The new value.

Returns: bool

Returns false when there is no such parameter. A parameter that is set is no longer marked as inherited.

TrySwitchToNextVariant

Selects the next variant that has parameters of its own, and returns whether a variant was selected.

bool TrySwitchToNextVariant();

Returns: bool

From the default variant it selects the first variant in the list. Returns false, and keeps the selection, when no variant has parameters of its own, when the selected variant is the last one, or when the selected variant is not in the list.

Returned by

IPCB_ParametersFactory.CreatePrimitiveParameters

Examples

Used in the SDK examples: Extension_BOMManager.