DP44/enriched-qwen3-coder-next/DataPRO/DataPRO/Common.md

---
source_files:
  - DataPRO/DataPRO/Common/IPageGrid.cs
  - DataPRO/DataPRO/Common/UsedInGroup.cs
  - DataPRO/DataPRO/Common/UsedInTestSetup.cs
  - DataPRO/DataPRO/Common/IFullScreenCapable.cs
  - DataPRO/DataPRO/Common/UsedIn.cs
  - DataPRO/DataPRO/Common/WindowWrapper.cs
  - DataPRO/DataPRO/Common/UsageReport.cs
  - DataPRO/DataPRO/Common/INavStepContent.cs
  - DataPRO/DataPRO/Common/CommonStyles.xaml.cs
  - DataPRO/DataPRO/Common/WaitCursor.cs
  - DataPRO/DataPRO/Common/DeviceSelected.cs
  - DataPRO/DataPRO/Common/TimeUnits.cs
  - DataPRO/DataPRO/Common/Negative.cs
  - DataPRO/DataPRO/Common/PageHelper.cs
  - DataPRO/DataPRO/Common/SQLConversion.cs
  - DataPRO/DataPRO/Common/BoolToVisibilityConverter.cs
  - DataPRO/DataPRO/Common/InvertVisibilityConverter.cs
  - DataPRO/DataPRO/Common/HardwareIPRanges.cs
  - DataPRO/DataPRO/Common/Transition.cs
  - DataPRO/DataPRO/Common/ToastWindow.xaml.cs
  - DataPRO/DataPRO/Common/ModalDialog.xaml.cs
  - DataPRO/DataPRO/Common/GroupedItemControl.cs
  - DataPRO/DataPRO/Common/DataPROTabItem.cs
  - DataPRO/DataPRO/Common/DbAccess.cs
generated_at: "2026-04-16T04:06:41.007079+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "ff478277c20f6904"
---

# DataPROWin7.Common Module Documentation

## 1. Purpose  
This module (`DataPROWin7.Common`) provides foundational infrastructure components for the DataPRO Windows 7 application. It defines shared interfaces, data models, UI helpers, converters, and database initialization utilities used across the application’s UI and data layers. Its role is to decouple cross-cutting concerns—such as navigation state management, UI state transitions, cursor handling, and hardware/database metadata caching—from domain-specific logic, enabling consistent behavior and reuse across modules like Data Recorders, Sensor Database, and Test Setup pages.

## 2. Public Interface  

### Interfaces  
- **`IPageGrid`**  
  ```csharp
  void OnSetActive();
  ```  
  Called when a page becomes active (e.g., during navigation). Intended for page-specific initialization or UI updates.

- **`IFullScreenCapable`**  
  ```csharp
  void GoFullScreen();
  void GoSmallScreen();
  ```  
  Enables toggling between full-screen and normal windowed display modes. *Note: Interface is internal (`interface` without `public` modifier).*

- **`INavStepContent`**  
  ```csharp
  void UnSet(Action OnComplete = null);
  ```  
  Invoked when the current test setup changes, allowing UI cleanup (e.g., clearing fields). Optional completion callback.

### Classes  
- **`UsedInGroup`**  
  ```csharp
  public class UsedInGroup { public string Name { get; set; } }
  ```  
  Represents a group context where an item is used (e.g., in group-based configurations).

- **`UsedInTestSetup`**  
  ```csharp
  public class UsedInTestSetup { public string Name { get; set; } }
  ```  
  Represents a test setup context where an item is used.

- **`UsedIn`**  
  ```csharp
  public class UsedIn { public string Type { get; set; } public string Name { get; set; } }
  ```  
  Generic metadata for tracking where an item is used (e.g., in groups or test setups). `Type` indicates context (e.g., `"Group"` or `"TestSetup"`).

- **`WindowWrapper`**  
  ```csharp
  public class WindowWrapper : System.Windows.Forms.IWin32Window
  ```  
  Wraps a Win32 `HWND` (`IntPtr`) for interop with WinForms APIs (e.g., dialog hosting). Constructor: `WindowWrapper(IntPtr handle)`.

- **`UsageReport`**  
  ```csharp
  public class UsageReport { public List<DeviceSelected> SelectedDevices { get; set; } }
  ```  
  Container for usage report data, populated from Data Recorders/Sensor Database tabs (FB 12774).

- **`DeviceSelected`**  
  ```csharp
  public class DeviceSelected
  {
      public string Type { get; set; }
      public string SerialNumber { get; set; }
      public DateTime CalDueDate { get; set; }
      public List<UsedIn> Groups { get; set; }
      public List<UsedIn> TestSetups { get; set; }
  }
  ```  
  Represents a selected device for usage reporting, including calibration due date and usage contexts (FB 12774).

- **`TimeUnits`**  
  ```csharp
  public class TimeUnits : BasePropertyChanged
  {
      public enum Units { MilliSeconds, Seconds }
      public Units MyUnits { get; set; }
      public string ToShortString() { ... }
  }
  ```  
  Encapsulates time unit selection (`ms` or `s`). `ToShortString()` returns `"ms"` or `"s"`. Inherits `BasePropertyChanged` for property change notifications.

- **`Negative`**  
  ```csharp
  public class Negative : IValueConverter
  {
      public static Negative Instance { get; }
      public object Convert(object value, ...) { ... }
      public object ConvertBack(...) { throw ...; }
  }
  ```  
  XAML value converter that negates `double` values. `ConvertBack` is unimplemented.

- **`BoolToVisibilityConverter`**  
  ```csharp
  public sealed class BoolToVisibilityConverter : IValueConverter
  {
      public Visibility TrueValue { get; set; } // default: Visible
      public Visibility FalseValue { get; set; } // default: Collapsed
      public object Convert(...) { ... }
      public object ConvertBack(...) { ... }
  }
  ```  
  Converts `bool` to `Visibility` (and vice versa). Configurable `TrueValue`/`FalseValue` (defaults: `Visible`/`Collapsed`).

- **`InvertVisibilityConverter`**  
  ```csharp
  public sealed class InvertVisibilityConverter : IValueConverter
  {
      public object Convert(...) { ... } // Visible ↔ Collapsed
      public object ConvertBack(...) { ... }
  }
  ```  
  Inverts `Visibility` values (`Visible` ↔ `Collapsed`). Returns `Visible` for non-`Visibility` inputs.

- **`PageHelper`**  
  ```csharp
  internal static class PageHelper
  {
      public static int GetTabAndButtonFontSize()
  }
  ```  
  Retrieves tab/page button font size from app settings, clamped to `[Min, Max]` range (FB 44523). Returns `Min` if out of bounds.

- **`SQLConversion`**  
  ```csharp
  public static class SQLConversion
  {
      public static string ConvertInternalVersionToYear(int sqlVersion)
  }
  ```  
  Maps SQL Server internal version numbers to release years (e.g., `12` → `"2014"`, `16` → `"2022"`). Returns `"{version} (Internal)"` for unknown versions.

- **`WaitCursor`**  
  ```csharp
  public class WaitCursor : IDisposable
  {
      public WaitCursor();
      public void Dispose();
  }
  ```  
  Temporarily sets the mouse cursor to `Cursors.Wait` during disposal. Ensures cursor restoration via `IDisposable`.

- **`HardwareIPRanges`**  
  ```csharp
  public class HardwareIPRanges
  {
      public IPRange[] IPRanges { get; set; }
      public void AddIPRange(IPRange r);
      public void AddRange(IPRange[] ranges);
      public HardwareIPRanges(); // Loads from "HWIPRanges.txt"
  }
  ```  
  Loads IP ranges from `HWIPRanges.txt` (comma-separated start/end IPs) for hardware discovery/ping sweeps. Logs exceptions via `APILogger`.

- **`Transition`**  
  ```csharp
  public class Transition : FrameworkElement
  {
      public enum TransitionState { A, B }
      public object Source { get; set; }
      public object DisplayA { get; set; }
      public object DisplayB { get; set; }
      public TransitionState State { get; set; }
  }
  ```  
  A WPF `FrameworkElement` that swaps `Source` between `DisplayA` and `DisplayB` based on `State`. Initialized to `State.A`.

- **`ToastWindow`**  
  ```csharp
  public partial class ToastWindow : Window
  {
      public ToastWindow(string screenShotFilename);
  }
  ```  
  Displays a non-modal notification in the lower-right corner. Auto-closes after 2 seconds. Clicking opens the screenshot file. Used for screenshot notifications (FB 15332).

- **`ModalDialog`**  
  ```csharp
  public partial class ModalDialog : UserControl
  {
      public string Message { get; set; }
      public void SetParent(UIElement parent);
      public bool ShowHandlerDialog(string message);
      public void OkButton_Click(...);
      public void CancelButton_Click(...);
      public UserControl MyContent { set { ... } }
  }
  public interface IModalDialogContent
  {
      void SetCancelEvent(ModalDialog.ButtonEvent ev);
      void SetOKEvent(ModalDialog.ButtonEvent ev);
  }
  ```  
  A reusable modal dialog overlay. `ShowHandlerDialog` blocks until user clicks OK/Cancel. `MyContent` setter wires events for content implementing `IModalDialogContent`.

- **`GroupedItemControl`**  
  ```csharp
  public class GroupedItemControl : Control
  {
      public static RoutedCommand ClickCommand { get; }
      public ImageSource Image { get; set; }
      public int ResourceId { get; set; }
      public string Title { get; set; }
      public DataModel.TabPageItem TabItem { get; set; }
  }
  ```  
  A custom control for tab/page tiles. Triggers `ClickCommand` (handled by `MainWindow.GroupedItemControlClicked`). *Note: `Subtitle` property is commented out.*

- **`DataPROTabItem`**  
  ```csharp
  public class DataPROTabItem : TabItem
  {
      public void SetReferringTab(DataPROTabItem tab);
      public void GoToNewPage(UserControl o);
      public void ClearPreviousPages();
      public void GoToPreviousPage(bool setActive);
      public TabPageItem Item { get; }
      public DataPROTabItem(TabPageItem item);
  }
  ```  
  Extends `TabItem` to manage navigation history. Supports forward/back navigation, caching of test setup names (FB 15748), and special handling for `RunTestBase`/`EditTestSetupPage`.

- **`DbAccess`**  
  ```csharp
  public abstract class DbAccess
  {
      public static void InitializeGroupHardwareIds();
      public static void InitializeTestSetupHardwareIds();
      public static void InitializeDASIdChannelIndexGroupIdList();
      public static void InitializeBaseModuleChannelIndexList();
      public static void InitializeDASIds();
      public static void InitializeGroupChannelIds();
      public static void InitializeStaticGroupNames();
      public static void InitializeEmbeddedGroupIdList();
      public static void InitializeTestSetupGroupIds();
      public static void InitializeTestSetupNames();
  }
  ```  
  Static methods to populate `GroupHelper`/`TestSetupHelper` caches from the database. Used during application startup to avoid repeated DB queries.

### Helpers  
- **`CommonStyles.ToolTipEventHandler`**  
  ```csharp
  public void ToolTipEventHandler(object sender, ToolTipEventArgs e)
  ```  
  Publishes `HelpTextEvent` via Prism’s `IEventAggregator` for context-sensitive help.

## 3. Invariants  
- **`IPageGrid.OnSetActive()`**: Must be called exactly once per page activation (e.g., during `DataPROTabItem.GoToNewPage`).  
- **`IFullScreenCapable`**: `GoFullScreen`/`GoSmallScreen` must be symmetric (no partial states).  
- **`INavStepContent.UnSet`**: Must be idempotent and safe to call multiple times.  
- **`WaitCursor`**: Must restore the original cursor on `Dispose`, even if exceptions occur.  
- **`HardwareIPRanges`**: Requires `HWIPRanges.txt` in the application directory; malformed lines are silently skipped (exceptions logged).  
- **`Transition`**: `Source` property changes trigger an immediate swap to the opposite display (`A`/`B`).  
- **`SQLConversion.ConvertInternalVersionToYear`**: Only supports known SQL Server versions (12–16); others return `(Internal)`.  
- **`DbAccess` methods**: All assume database connectivity; failures are silently ignored (no exceptions thrown).  

## 4. Dependencies  
- **Imports/References**:  
  - `System.Windows.Forms` (`IWin32Window` for `WindowWrapper`).  
  - `Prism.Ioc`, `Prism.Events` (`IEventAggregator`, `ContainerLocator`).  
  - `DTS.Common.*` (e.g., `DTS.Common.Events`, `DTS.Common.Base`, `DTS.Common.Storage`, `DTS.Common.Classes.*`).  
  - `System.Data`, `System.Data.SqlClient` (ADO.NET for `DbAccess`).  
  - `System.Windows`, `System.Windows.Data` (WPF converters).  
- **Consumers**:  
  - `DataPROWin7.DataModel` (`TabPageItem`, `DataPROPage`).  
  - `DataPROWin7.TSRAIRGo.ViewModel` (`NavigationViewModel`).  
  - `DataPROWin7.App` (`App.Current`, `CurrentUser`).  
  - `MainWindow` (handles `GroupedItemControl.ClickCommand`).  

## 5. Gotchas  
- **`Negative.ConvertBack`**: Throws `NotImplementedException`; not suitable for two-way binding.  
- **`InvertVisibilityConverter.ConvertBack`**: Returns `Visibility.Visible` for non-`Visibility` inputs (not `null`).  
- **`HardwareIPRanges` constructor**: Reads `HWIPRanges.txt` synchronously on instantiation; may block startup if file is large or network-mounted.  
- **`ModalDialog.ShowHandlerDialog`**: Uses a blocking loop with `Dispatcher.Invoke`/`Thread.Sleep` (a "DoEvents" hack); may cause reentrancy issues.  
- **`DataPROTabItem` caching**: `_currentTestName` is static; may cause incorrect navigation if multiple tabs are used concurrently.  
- **`DbAccess` methods**: All are static and mutate global state (`GroupHelper`, `TestSetupHelper`); not thread-safe or testable in isolation.  
- **`TimeUnits.ToShortString`**: Throws `NotSupportedException` for unknown units (should be `ArgumentException` per .NET conventions).  
- **`PageHelper.GetTabAndButtonFontSize`**: Relies on `Properties.Settings.Default` and `DTS.Common.Constants`; external dependency not visible in source.  
- **`IFullScreenCapable`**: Interface is internal (no `public` modifier), limiting its use outside the assembly.  
- **`GroupedItemControl`**: `Subtitle` property is commented out; developers may assume it exists.  
- **`WindowWrapper`**: Does not validate `IntPtr` (e.g., `IntPtr.Zero` is accepted).