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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T04:06:41.007079+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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

  void OnSetActive();
  

  Called when a page becomes active (e.g., during navigation). Intended for page-specific initialization or UI updates.

• IFullScreenCapable

  void GoFullScreen();
  void GoSmallScreen();
  

  Enables toggling between full-screen and normal windowed display modes. Note: Interface is internal (interface without public modifier).

• INavStepContent

  void UnSet(Action OnComplete = null);
  

  Invoked when the current test setup changes, allowing UI cleanup (e.g., clearing fields). Optional completion callback.

Classes

• UsedInGroup

  public class UsedInGroup { public string Name { get; set; } }
  

  Represents a group context where an item is used (e.g., in group-based configurations).

• UsedInTestSetup

  public class UsedInTestSetup { public string Name { get; set; } }
  

  Represents a test setup context where an item is used.

• UsedIn

  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

  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

  public class UsageReport { public List<DeviceSelected> SelectedDevices { get; set; } }
  

  Container for usage report data, populated from Data Recorders/Sensor Database tabs (FB 12774).

• DeviceSelected

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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

  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).