# IPCB_PrimitiveParameters interface

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

```csharp
public interface IPCB_PrimitiveParameters
```

**Namespace:** PCB · **Assembly:** Altium.SDK.Interfaces

## Remarks

A primitive, for example an [`IPCB_Component`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Component.md), 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`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_ParametersFactory.md) 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`](#switchtodefaultvariant), [`SwitchToCurrentVariant`](#switchtocurrentvariant), [`SwitchToVariantByName`](#switchtovariantbyname) and the others) select the variant, [`SwitchAppurtenance`](#switchappurtenance) selects the set. Changes are applied to the primitive at once. An [`IPCB_Parameter`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) returned by [`GetParameterByIndex`](#getparameterbyindex), [`GetParameterByName`](#getparameterbyname), [`FindParameterByName`](#findparameterbyname) or [`ExportToList`](#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`](#isfullyinherited)) shows the parameters of the default variant, marked as inherited (`IsInherited` of [`IPCB_Parameter`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) 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](#isfullyinherited) | `bool` | get; set | Whether the selected variant has no parameters of its own and shows the default variant's parameters. |
| [IsFullyInheritedAllVariants](#isfullyinheritedallvariants) | `bool` | get; set | Whether no variant has parameters of its own for the primitive. |
| [ValueByName](#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.

```csharp
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.

```csharp
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.

```csharp
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`](#setornewvaluebyname) adds a missing parameter.

## Methods

| Method | Returns | Description |
| --- | --- | --- |
| [AddOrSetParameter](#addorsetparameter) | `void` | Adds a parameter, or replaces the parameter of the same name, in the selected variant and set. |
| [AddParameter](#addparameter) | `void` | Adds a parameter to the selected variant and set. |
| [Count](#count) | `int` | Returns the number of parameters in the selected variant and set. |
| [ExportToList](#exporttolist) | [IPCB_ParameterList](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_ParameterList.md) | Returns a new list with copies of all parameters of the selected variant and set. |
| [FindParameterByName](#findparameterbyname) | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | Returns a copy of the parameter with the given name in the selected variant and set, or null when there is none. |
| [GetAppurtenance](#getappurtenance) | [TParameterAppurtenance](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/TParameterAppurtenance.md) | Returns the parameter set that the other members read and change, as selected by [`SwitchAppurtenance`](#switchappurtenance). |
| [GetIsCurrentVariant](#getiscurrentvariant) | `bool` | Returns whether the selected variant is the project's current variant. |
| [GetIsDefaultVariant](#getisdefaultvariant) | `bool` | Returns whether the selected variant is the default variant. |
| [GetParameterByIndex](#getparameterbyindex) | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | Returns a copy of the parameter at the given position in the selected variant and set. |
| [GetParameterByName](#getparameterbyname) | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | Returns a copy of the parameter with the given name in the selected variant and set. |
| [GetValueByNameDef](#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](#getvariantcount) | `int` | Returns the number of variants that have parameters of their own for the primitive. |
| [GetVariantIndex](#getvariantindex) | `int` | Returns the position of the selected variant in the list of variants that have parameters of their own. |
| [GetVariantName](#getvariantname) | `string` | Returns the name of the selected variant. |
| [GetVariantUniqueID](#getvariantuniqueid) | `string` | Returns the unique ID of the selected variant. |
| [ImportFromList](#importfromlist) | `void` | Replaces all parameters of the selected variant and set with the parameters of the given list. |
| [NewValueByName](#newvaluebyname) | `void` | Adds a parameter with the given name and value to the selected variant and set. |
| [RemoveAllParameters](#removeallparameters) | `void` | Removes all parameters of the selected variant and set. |
| [RemoveAllParametersAndVariants](#removeallparametersandvariants) | `void` | Removes all parameters of the primitive, those of the default variant and of every variant, in every set. |
| [RemoveByIndex](#removebyindex) | `void` | Removes the parameter at the given position in the selected variant and set. |
| [RemoveByName](#removebyname) | `void` | Removes the parameter with the given name from the selected variant and set. |
| [SetOrNewValueByName](#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](#setparameter) | `void` | Replaces the parameter of the same name in the selected variant and set with the given parameter. |
| [SwitchAppurtenance](#switchappurtenance) | `void` | Selects the parameter set that the other members read and change. |
| [SwitchToCurrentVariant](#switchtocurrentvariant) | `void` | Selects the project's current variant. |
| [SwitchToDefaultVariant](#switchtodefaultvariant) | `void` | Selects the default variant. |
| [SwitchToVariantByIndex](#switchtovariantbyindex) | `void` | Selects a variant by its position in the list of variants that have parameters of their own. |
| [SwitchToVariantByName](#switchtovariantbyname) | `void` | Selects a variant of the project by its name. |
| [SwitchToVariantByUniqueID](#switchtovariantbyuniqueid) | `void` | Selects a variant by its unique ID. |
| [TryGetValueByName](#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](#trynewvaluebyname) | `bool` | Adds a parameter with the given name and value to the selected variant and set, and returns whether it was added. |
| [TryRemoveByName](#tryremovebyname) | `bool` | Removes the parameter with the given name from the selected variant and set, and returns whether it was removed. |
| [TrySetValueByName](#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](#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.

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

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argParameter` | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | 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.

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

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argParameter` | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | 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`](#addorsetparameter) to replace it.

### Count

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

```csharp
int Count();
```

**Returns:** `int`

Returns 0 when the primitive has no parameters.

**Examples:** [Extension_BOMManager](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_BOMManager/Source%20Code/PcbComponent.cs#L30)

### ExportToList

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

```csharp
IPCB_ParameterList ExportToList();
```

**Returns:** [IPCB_ParameterList](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_ParameterList.md)

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.

```csharp
IPCB_Parameter FindParameterByName(string argName);
```

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argName` | `string` | value | The parameter name. |

**Returns:** [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md)

Extension method of `IPCB_PrimitiveParametersHelper` (`using PCB;`).

### GetAppurtenance

Returns the parameter set that the other members read and change, as selected by [`SwitchAppurtenance`](#switchappurtenance).

```csharp
TParameterAppurtenance GetAppurtenance();
```

**Returns:** [TParameterAppurtenance](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/TParameterAppurtenance.md)

Extension method of `IPCB_PrimitiveParametersHelper` (`using PCB;`).

### GetIsCurrentVariant

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

```csharp
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.

```csharp
bool GetIsDefaultVariant();
```

**Returns:** `bool`

### GetParameterByIndex

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

```csharp
IPCB_Parameter GetParameterByIndex(int argIndex);
```

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

**Returns:** [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md)

Extension method of `IPCB_PrimitiveParametersHelper` (`using PCB;`).

Raises an error when the index is out of range.

**Examples:** [Extension_BOMManager](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_BOMManager/Source%20Code/PcbComponent.cs#L32)

### GetParameterByName

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

```csharp
IPCB_Parameter GetParameterByName(string argName);
```

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argName` | `string` | value | The parameter name. |

**Returns:** [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md)

Extension method of `IPCB_PrimitiveParametersHelper` (`using PCB;`).

Raises an error when there is no such parameter; [`FindParameterByName`](#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.

```csharp
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.

```csharp
int GetVariantCount();
```

**Returns:** `int`

The default variant is not counted. [`SwitchToVariantByIndex`](#switchtovariantbyindex) and [`GetVariantIndex`](#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.

```csharp
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.

```csharp
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.

```csharp
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.

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

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argParameters` | [IPCB_ParameterList](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_ParameterList.md) | 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.

```csharp
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`](#trynewvaluebyname) returns false instead.

### RemoveAllParameters

Removes all parameters of the selected variant and set.

```csharp
void RemoveAllParameters();
```

**Returns:** nothing (`void`)

### RemoveAllParametersAndVariants

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

```csharp
void RemoveAllParametersAndVariants();
```

**Returns:** nothing (`void`)

### RemoveByIndex

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

```csharp
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.

```csharp
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`](#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.

```csharp
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.

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

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argParameter` | [IPCB_Parameter](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_Parameter.md) | 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.

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

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argValue` | [TParameterAppurtenance](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/TParameterAppurtenance.md) | 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.

```csharp
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.

```csharp
void SwitchToDefaultVariant();
```

**Returns:** nothing (`void`)

### SwitchToVariantByIndex

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

```csharp
void SwitchToVariantByIndex(int argIndex);
```

| Parameter | Type | Passing | Description |
| --- | --- | --- | --- |
| `argIndex` | `int` | value | The zero-based position, less than [`GetVariantCount`](#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.

```csharp
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.

```csharp
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.

```csharp
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.

```csharp
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.

```csharp
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.

```csharp
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.

```csharp
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](https://altiumdeveloper.github.io/ad-sdk-docs/reference/pcb/IPCB_ParametersFactory.md#createprimitiveparameters)

## Examples

Used in the SDK examples: [Extension_BOMManager](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_BOMManager/Source%20Code/PcbComponent.cs#L29).