--- 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 includedHardwareStringList)` – Creates a new group, pre-populating hardware via legacy string IDs. - `IGroup CreateGroup(SqlDataReader reader, List includedHardwareStringList, List dasIdList)` – Creates a group from database record and hardware lists. - `IGroup CreateGroup(IGroupDbRecord groupRecord, List includedHardwareStringList, List dasIdList)` – Creates a group from a database record and hardware lists. - **`IGroup : IComparable`** *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 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 sensorLookup, IDictionary 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 channelLookup, List sensors)` – XML serialization/deserialization. - `List GroupChannelList { get; set; }` – In-memory channel list. - `void SetIncludedHardware(int[] hardware)` – Sets hardware list and marks data as loaded. - `List 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 AvailableTestObjects { get; set; }`, `string SelectedTestObjectItem { get; set; }` `List 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 includedHardwareStringList` and `List 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 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".