# ISch_Iterator interface

An iterator object interface represents an existing iterator object which iterates through a design database to fetch specified objects within a specified region if necessary.

```csharp
public interface ISch_Iterator
```

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

## Remarks

The [`TIterationDepth`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md) type denotes how deep the iterator can look - look for first level objects (for example standalone system parameters of the document only, or all levels for example all parameters on the document including system parameters, objects' parameters such as component's parameters. By default, eIterateAllLevels value is used.

[`SetState_FilterAll`](#setstate_filterall) denotes that all objects and the whole schematic document is to be searched within. Otherwise, use the following [`AddFilter_ObjectSet`](#addfilter_objectset), [`AddFilter_Area`](#addfilter_area) etc methods to set up a restricted search.

## Example

Count the ports on the current schematic sheet.

```csharp
using SCH;

ISch_Document currentSheet = SCH.GlobalVars.SchServer?.GetCurrentSchDocument();
if (currentSheet == null)
    return;
int portNumber = 0;

ISch_Iterator iterator = currentSheet.SchIterator_Create();
if (iterator == null)
    return;
iterator.AddFilter_ObjectSet(new SCH.TObjectSet { TObjectId.ePort });
try
{
    ISch_BasicContainer port = iterator.FirstSchObject();
    while (port != null)
    {
        portNumber = portNumber + 1;
        port = iterator.NextSchObject();
    }
}
finally
{
    currentSheet.SchIterator_Destroy(ref iterator);
}
```

## Properties

| Property | Type | Access | Description |
| --- | --- | --- | --- |
| [IterationDepth](#iterationdepth) | [TIterationDepth](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md) | set | The [`TIterationDepth`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md) type denotes how deep the iterator can look on a document. |

### IterationDepth

The [`TIterationDepth`](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md) type denotes how deep the iterator can look on a document.

```csharp
void SetState_IterationDepth(TIterationDepth argIterationDepth);
```

**Type:** [TIterationDepth](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md) · **Access:** write-only

The accessors are extension methods of `ISch_IteratorHelper` (`using SCH;`).

Look for first level objects, for example standalone system parameters of the document only, or all levels for example all parameters on the document including system parameters, objects' parameters such as component's parameters.

By default, eIterateAllLevels value is used.

**See also:** [TIterationDepth](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TIterationDepth.md)

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

## Methods

| Method | Returns | Description |
| --- | --- | --- |
| [AddFilter_Area](#addfilter_area) | `void` | The `AddFilter_Area` method defines the rectangular bounds (X1,Y1 and X2,Y2) of the schematic/library document that the iterator will search within. |
| [AddFilter_CurrentDisplayModePrimitives](#addfilter_currentdisplaymodeprimitives) | `void` | This method sets the iterator to look for current display mode primitives only. |
| [AddFilter_CurrentPartPrimitives](#addfilter_currentpartprimitives) | `void` | This method sets up the filter of the iterator to look for the current primitives of a part only. |
| [AddFilter_ObjectSet](#addfilter_objectset) | `void` | This method defines which objects the iterator will look for on a schematid document or a library document. |
| [AddFilter_PartPrimitives](#addfilter_partprimitives) | `void` | This method sets up the filter of the iterator to look for primitives of a part (of a component). |
| [FirstSchObject](#firstschobject) | [ISch_BasicContainer](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/ISch_BasicContainer.md) | The `FirstSchObject` method fetches the first object found by the iterator. |
| [NextSchObject](#nextschobject) | [ISch_BasicContainer](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/ISch_BasicContainer.md) | The `NextSchObject` method fetches the next object found by the iterator. |
| [SetState_FilterAll](#setstate_filterall) | `void` | This method sets the iterator to look for everything on a document. |

### AddFilter_Area

The `AddFilter_Area` method defines the rectangular bounds (X1,Y1 and X2,Y2) of the schematic/library document that the iterator will search within.

```csharp
void AddFilter_Area(int argx1, int argy1, int argx2, int argy2);
```

| Parameter | Type | Passing |
| --- | --- | --- |
| `argx1` | `int` | value |
| `argy1` | `int` | value |
| `argx2` | `int` | value |
| `argy2` | `int` | value |

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

### AddFilter_CurrentDisplayModePrimitives

This method sets the iterator to look for current display mode primitives only. A component can be represented by different modes - ie there can be different graphical representations of the same component type.

```csharp
void AddFilter_CurrentDisplayModePrimitives();
```

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

### AddFilter_CurrentPartPrimitives

This method sets up the filter of the iterator to look for the current primitives of a part only. A component can be composed of multiple parts and each part is identified by its PartID value.

```csharp
void AddFilter_CurrentPartPrimitives();
```

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

### AddFilter_ObjectSet

This method defines which objects the iterator will look for on a schematid document or a library document.

```csharp
void AddFilter_ObjectSet(TObjectSet argObjectSet);
void AddFilter_ObjectSet(ITransportSet argObjectSet);
```

| Parameter | Type | Passing |
| --- | --- | --- |
| `argObjectSet` | [TObjectSet](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TObjectSet.md) | value |

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

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

**See also:** [TObjectSet](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/TObjectSet.md)

**Examples:** [Ciiva](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Ciiva/Source%20Code/CiivaBOMDocument.cs#L90), [Extension_ModifySchWireColor](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_ModifySchWireColor/Source%20Code/Commands.cs#L37)

### AddFilter_PartPrimitives

This method sets up the filter of the iterator to look for primitives of a part (of a component). A component can be a multi-part component, for example a 74LS04 can have four parts and they are identified by the PartID value.

```csharp
void AddFilter_PartPrimitives(int argPartId, byte argDisplayMode);
```

| Parameter | Type | Passing |
| --- | --- | --- |
| `argPartId` | `int` | value |
| `argDisplayMode` | `byte` | value |

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

### FirstSchObject

The `FirstSchObject` method fetches the first object found by the iterator. The `FirstSchObject` method is to be invoked first and then in a While null loop, the [`NextSchObject`](#nextschobject) is called repeatedly until it returns a nil value where the loop is terminated.

```csharp
ISch_BasicContainer FirstSchObject();
```

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

Extension method of `ISch_IteratorHelper` (`using SCH;`).

**See also:** [ISch_Iterator.NextSchObject](#nextschobject)

**Examples:** [Ciiva](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Ciiva/Source%20Code/CiivaBOMDocument.cs#L91), [Extension_ModifySchWireColor](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_ModifySchWireColor/Source%20Code/Commands.cs#L43)

### NextSchObject

The `NextSchObject` method fetches the next object found by the iterator. The [`FirstSchObject`](#firstschobject) method is to be invoked first and then in a While null loop, the `NextSchObject` is called repeatedly until it returns a nil value where the loop is terminated.

```csharp
ISch_BasicContainer NextSchObject();
```

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

Extension method of `ISch_IteratorHelper` (`using SCH;`).

**See also:** [ISch_Iterator.FirstSchObject](#firstschobject)

**Examples:** [Ciiva](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Ciiva/Source%20Code/CiivaBOMDocument.cs#L119), [Extension_ModifySchWireColor](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_ModifySchWireColor/Source%20Code/Commands.cs#L59)

### SetState_FilterAll

This method sets the iterator to look for everything on a document.

```csharp
void SetState_FilterAll();
```

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

## Returned by

[ISch_BasicContainer.SchIterator_Create](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/ISch_BasicContainer.md#schiterator_create), [ISch_Lib.SchLibIterator_Create](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/ISch_Lib.md#schlibiterator_create)

## Accepted by

[ISch_BasicContainer.SchIterator_Destroy](https://altiumdeveloper.github.io/ad-sdk-docs/reference/sch/ISch_BasicContainer.md#schiterator_destroy)

## Examples

Used in the SDK examples: [Ciiva](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Ciiva/Source%20Code/CiivaBOMDocument.cs#L84), [Extension_ModifySchWireColor](https://github.com/AltiumDeveloper/ad-sdk-examples/blob/5b144f54740a53ec578b3b6c3f902b831e0b1144/Extension_ModifySchWireColor/Source%20Code/Commands.cs#L34).