DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Groups/GroupList.md

---
source_files:
  - Common/DTS.Common/Interface/Groups/GroupList/IGroupListView.cs
  - Common/DTS.Common/Interface/Groups/GroupList/TestSetupParentHelper.cs
  - Common/DTS.Common/Interface/Groups/GroupList/IGroupListViewModel.cs
  - Common/DTS.Common/Interface/Groups/GroupList/IGroup.cs
generated_at: "2026-04-16T03:07:21.318900+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "cfa13e8b0909ec6a"
---

# GroupList

## Documentation: Group List Module

---

### 1. Purpose

This module defines the core interfaces and supporting types for managing *groups*—logical collections of test hardware (e.g., sensors, data recorders, channels)—within the DTS system. It provides a standardized contract for group data modeling (`IGroup`), group list management and filtering (`IGroupListViewModel`), and view-layer integration (`IGroupListView`). The module serves as the domain abstraction layer between UI components and underlying data persistence (e.g., database via `IGroupDbRecord`), enabling features like group creation, editing, deletion, hardware association, XML export/import, and test setup association.

---

### 2. Public Interface

#### Interfaces

- **`IGroupListView : IBaseView`**  
  *Namespace:* `DTS.Common.Interface.Groups.GroupTemplateList`  
  Marker interface for the view layer associated with group list display. Inherits `IBaseView`. No additional members.

- **`IGroupListViewModel : IBaseViewModel, IFilterableListView`**  
  *Namespace:* `DTS.Common.Interface.Groups.GroupList`  
  ViewModel managing the group list state and operations. Key members:
  - `IGroupListView View { get; set; }` – Binds to the view instance.
  - `void Unset()` – Releases resources or clears state (exact semantics not specified in source).
  - `void Sort(object o, bool columnClick)` – Sorts the group list; `o` likely identifies the sort key/column.
  - `IGroup[] Groups { get; set; }` – Gets or sets the current list of groups.
  - `void OnSetActive(object page, bool groupTile, object currentUser)` – Initializes or activates the view for a specific context (`page`, `currentUser`) and display mode (`groupTile`).
  - `void MouseDoubleClick(int index)` – Handles double-click on group at `index`.
  - `void Filter(string term)` – Filters the group list by `term`.
  - `IGroup GetGroup(int? id, bool updateTags = true)` – Retrieves a group by ID; optionally updates tags.
  - `IGroup GetGroup(string displayName)` – Retrieves a group by `displayName`.
  - `IGroup[] GetGroups(int[] ids)` – Retrieves multiple groups by IDs.
  - `IGroup[] GetAllGroups()` – Retrieves all groups.
  - `void DeleteGroups(int[] ids)` – Deletes groups by IDs.
  - `IGroup CreateGroup()` – Creates a new, unsaved group.
  - `IGroup CreateGroup(List<string> includedHardwareStringList)` – Creates a new group, pre-populating hardware via legacy string IDs.
  - `IGroup CreateGroup(SqlDataReader reader, List<string> includedHardwareStringList, List<int> dasIdList)` – Creates a group from database record and hardware lists.
  - `IGroup CreateGroup(IGroupDbRecord groupRecord, List<string> includedHardwareStringList, List<int> dasIdList)` – Creates a group from a database record and hardware lists.

- **`IGroup : IComparable<IGroup>`**  
  *Namespace:* `DTS.Common.Interface.Groups.GroupList`  
  Core domain interface for a group entity. Key members:
  - `int Id { get; set; }`, `string Name { get; set; }`, `string DisplayName { get; set; }`, `string Description { get; set; }` – Basic metadata.
  - `int? StaticGroupId { get; set; }`, `bool IsDifferentThanStaticGroup { get; set; }`, `bool StaticGroupIsEqual()` – Support for static group templates.
  - `bool Embedded { get; set; }` – Indicates if group is embedded (non-editable?).
  - `DateTime LastModified { get; set; }`, `string LastModifiedBy { get; set; }` – Audit fields.
  - `int[] IncludedHardware { get; set; }`, `string[] IncludedHardwareStringList { get; set; }` – Hardware associations (new and legacy ID formats).
  - `bool Filter(string term)` – Returns `true` if group matches `term`.
  - `bool Save(Channels.IGroupChannel[] groupChannels, bool canUserCommitChannelCodes)`  
    `bool Save(Channels.IGroupChannel[] groupChannels, bool canUserCommitChannelCodes, ref List<IGroupChannel> newGroupChannelList)`  
    Persists group and its channels; returns success. Second overload tracks newly created channels.
  - `void ClearGroupChannelSettingCache(long groupId)` – Clears cached channel settings for this group.
  - `Channels.IGroupChannel[] GetAllChannels(bool bEditable, IDictionary<int, ISensorData> sensorLookup, IDictionary<int, IDASHardware> hardwareLookup, IChannelSetting[] channelDefaults, bool allowSensorPushAndPull = false)` – Retrieves all channels for this group, with lookups for sensors/hardware and defaults.
  - `void LoadHardware()` – Loads associated hardware data.
  - `void ConvertToEmbedded(Channels.IGroupChannel[] groupChannels)` – Converts group to embedded state.
  - `void DeterminePositionAndTestObject(Channels.IGroupChannel[] channels)` – Infers position/test object values from channels.
  - `bool PositionIsMixed { get; set; }`, `bool PositionIsTextbox { get; set; }`, `bool PositionIsCombobox { get; set; }`, `string Position { get; set; }` – UI state for position field.
  - `bool TestObjectIsMixed { get; set; }`, `string TestObject { get; set; }` – UI state for test object field.
  - `int DisplayOrder { get; set; }` – Sort order in UI.
  - `ISensorData GetSensor(Channels.IGroupChannel channel, ISensorData sensorData, bool bUseIsoFilter)`  
    `void SetSensor(Channels.IGroupChannel channel, ISensorData sensorData)` – Sensor read/write helpers.
  - `void WriteXML(ref XmlWriter writer)`  
    `IGroup ReadXML(XmlElement node, Dictionary<long, IGroupChannel> channelLookup, List<ISensorData> sensors)` – XML serialization/deserialization.
  - `List<Channels.IGroupChannel> GroupChannelList { get; set; }` – In-memory channel list.
  - `void SetIncludedHardware(int[] hardware)` – Sets hardware list and marks data as loaded.
  - `List<TestSetupParentHelper> AssociatedTestSetups { get; set; }` – Associated test setups.
  - `void SetTestSetupLists()` – Populates `AssociatedTestSetups`.
  - `bool TagCompatible(int[] tags)` – Checks if group’s tags are compatible with `tags`.
  - `int[] TagIDs { get; set; }`, `string Tags { get; set; }` – Tag metadata.
  - `string GetTagsAsCommaSeparatedString(TagsGetDelegate tagsGet)` – Formats tags as CSV using a delegate.
  - `List<string> AvailableTestObjects { get; set; }`, `string SelectedTestObjectItem { get; set; }`  
    `List<string> AvailablePositions { get; set; }`, `string SelectedPositionItem { get; set; }` – UI selection lists.

#### Classes

- **`TestSetupParentHelper`**  
  *Namespace:* `DTS.Common.Interface.Groups.GroupList`  
  Simple DTO for test setup associations:
  - `int Id` – Public field.
  - `string Name { get; set; }` – Display name.
  - `bool Modified { get; set; }` – Tracks modification state.
  - `override string ToString()` – Returns `Name`.

---

### 3. Invariants

- **`IGroup.Id`** must be non-null and unique per group instance (implied by `GetGroup(int? id)` and `DeleteGroups(int[] ids)`).
- **`IGroup.DisplayName`** is used for display and filtering (`Filter(string term)`), implying it must be non-null and stable.
- **`IGroup.IncludedHardware`** and **`IGroup.IncludedHardwareStringList`** must be kept in sync; the latter is explicitly noted as legacy (primarily for import).
- **`IGroup.Save(...)`** must persist both group metadata and channel state; return value indicates success/failure.
- **`IGroup.Filter(string term)`** must return `true` if and only if the group matches the search term (case-sensitivity not specified).
- **`IGroupListViewModel.Groups`** must reflect the current filtered/sorted state after `Filter()` or `Sort()` calls.
- **`IGroupListViewModel.GetGroup(...)`** methods must return a valid `IGroup` instance (or `null` if not found), with optional tag updates (`updateTags` parameter).
- **`IGroup.TagCompatible(int[] tags)`** must validate tag compatibility against group’s `TagIDs`.

---

### 4. Dependencies

#### This module depends on:
- `DTS.Common.Base` (`IBaseView`, `IBaseViewModel`, `IFilterableListView`)
- `DTS.Common.Interface.Pagination` (via `IFilterableListView`)
- `DTS.Common.Interface.Channels` (`IGroupChannel`, `IChannelSetting`)
- `DTS.Common.Interface.Sensors` (`ISensorData`)
- `DTS.Common.Interface.DataRecorders` (`IDASHardware`)
- `DTS.Common.Interface.TestSetups.TestSetupsList` (`TestSetupParentHelper` usage implies dependency)
- `System.Xml`, `System.Data.SqlClient` (for `XmlWriter`, `XmlElement`, `SqlDataReader`)

#### This module is depended upon by:
- UI components implementing `IGroupListView` (e.g., WPF/WinForms views).
- ViewModels or services implementing `IGroupListViewModel` (e.g., `GroupListViewModel` in UI layer).
- Persistence layers implementing `IGroupDbRecord` (not shown here, but referenced by `IGroup.GetIGroupDbRecord()` and `IGroup.CreateGroup(...)` overloads).

---

### 5. Gotchas

- **`IncludedHardwareStringList`** is explicitly documented as a legacy field for import purposes; relying on it for current logic may be risky.
- **`IGroup.CreateGroup(...)`** overloads accept `List<string> includedHardwareStringList` and `List<int> dasIdList`—but `dasIdList` is only used in two overloads. Inconsistent usage may indicate incomplete refactoring.
- **`IGroup.Save(...)`** has two overloads differing only by `ref List<IGroupChannel> newGroupChannelList`. The `ref` parameter suggests mutation of caller-provided lists; callers must initialize the list before invocation.
- **`IGroupListViewModel.OnSetActive(...)`** uses `object` for `page`, `currentUser`, and `groupTile` (a `bool`). This indicates weak typing; consumers must know the expected types (e.g., `page` likely a page/view instance, `currentUser` a user principal).
- **`TestSetupParentHelper`** is in namespace `DTS.Common.Interface.Groups.GroupList`, but `IGroupListView` is in `DTS.Common.Interface.Groups.GroupTemplateList`. Namespace inconsistency may cause confusion.
- **`IGroup.PositionIsMixed`, `PositionIsTextbox`, `PositionIsCombobox`** are separate flags—UI logic must ensure consistency (e.g., only one should be `true` at a time), but this is not enforced by the interface.
- **`GetTagsAsCommaSeparatedString`** requires a delegate (`TagsGetDelegate`), but its signature is not defined in this source. Callers must infer or reference `Classes.Tags.TagsInstance`.
- **`Filter(string term)`** behavior (e.g., case sensitivity, substring vs. prefix match) is not specified beyond "returns true if group matches search term".