---
source_files:
  - DataPRO/DataPRO/IActionButtonContainer.cs
  - DataPRO/DataPRO/WaitCursor.cs
  - DataPRO/DataPRO/IPageContent.cs
  - DataPRO/DataPRO/DataProMainWindow.xaml.cs
  - DataPRO/DataPRO/BoolToOppositeBoolConverter.cs
  - DataPRO/DataPRO/TranslateExtension.cs
  - DataPRO/DataPRO/Settings.cs
  - DataPRO/DataPRO/PageActionButtonsGroup.xaml.cs
  - DataPRO/DataPRO/PageContentHeaderControl.xaml.cs
  - DataPRO/DataPRO/DataProSession.cs
  - DataPRO/DataPRO/LicensingFooter.xaml.cs
  - DataPRO/DataPRO/PageContentControl.xaml.cs
  - DataPRO/DataPRO/WindowResizer.cs
  - DataPRO/DataPRO/PageActionControlsRibbon.xaml.cs
  - DataPRO/DataPRO/PageActionButtonsRibbon.xaml.cs
  - DataPRO/DataPRO/PageSearchControl.xaml.cs
  - DataPRO/DataPRO/PageNavControlsGroup.xaml.cs
  - DataPRO/DataPRO/PageMainContentControl.xaml.cs
  - DataPRO/DataPRO/NavGraphStep.xaml.cs
generated_at: "2026-04-16T03:49:31.452209+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "1010e7b302783464"
---

# DataPROWin7 Module Documentation

## 1. Purpose

This module provides core infrastructure and UI framework components for the DataPROWin7 application, a Windows-based data acquisition and analysis system. It establishes foundational patterns for page navigation, search functionality, licensing display, and user permission management, while integrating with Prism-based modular architecture (via Unity container and region management). The module enables structured UI composition through interfaces like `IPageContent` and `IActionButtonContainer`, supports WPF-specific utilities (e.g., `WaitCursor`, `TranslateExtension`), and enforces permission-based visibility and enabled states for UI controls.

## 2. Public Interface

### Interfaces

#### `IActionButtonContainer`
- `DataPROWin7.Controls.ActionButton[] GetActionButtons()`  
  Returns all action buttons managed by the container.
- `void OnActionButtonPress(DataPROWin7.Controls.ActionButton button)`  
  Handles press events for action buttons.
- `void OnActionComboBoxChange(DataPROWin7.Controls.ActionComboBox comboBox)`  
  Handles selection change events for action combo boxes.
- `void OnActionComboBoxDropDownClose(DataPROWin7.Controls.ActionComboBox comboBox)`  
  Handles dropdown close events for action combo boxes.
- `void OnActionRadioButtonPress(DataPROWin7.Controls.ActionRadioButton button)`  
  Handles press events for action radio buttons.

#### `IPageContent`
- `void StartSearch(string term)`  
  Initiates a search operation using the provided search term.
- `bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow)`  
  Validates the page content; populates `errors` and `warnings` lists; `displayWindow` controls whether validation errors are shown in a UI dialog.
- `void OnSetActive()`  
  Called when the page becomes the active content (e.g., on navigation to the page).
- `void SetPermissions(DTS.Slice.Users.User.UserPermissionLevels actualPermission, DTS.Slice.Users.User.UserPermissionLevels requiredPermission)`  
  Configures UI state based on user permissions (e.g., enabling/disabling controls).
- `void UnSet(Action OnComplete = null)`  
  Cleans up resources allocated during `OnSetActive`; optional callback after cleanup.
- `bool OnButtonPress(Controls.PageButton button)`  
  Handles presses of page-specific buttons; returns `true` if handled.
- `object GetPageContent()`  
  Returns the underlying content object (e.g., view model or data model).
- `bool KeyDown(object sender, System.Windows.Input.KeyEventArgs e)`  
  Handles key press events; returns `true` if the event was handled.

### Classes

#### `WaitCursor`
- `WaitCursor()`  
  Sets the mouse cursor to `Cursors.Wait` and stores the previous cursor. Implements `IDisposable`.
- `void Dispose()`  
  Restores the previously stored cursor.

#### `BoolToOppositeBoolConverter`
- `object Convert(object value, Type targetType, object parameter, CultureInfo culture)`  
  Converts a `bool` to its logical opposite (`!value`). Throws `InvalidOperationException` if `targetType` is not `bool`.
- `object ConvertBack(...)`  
  Throws `NotSupportedException`.

#### `TranslateExtension`
- `TranslateExtension(string key)`  
  Constructor storing the resource key.
- `override object ProvideValue(IServiceProvider serviceProvider)`  
  Retrieves localized string from `StringResources.ResourceManager` using `_key`; returns `"#stringnotfound#"` or `"#stringnotfound# <key>"` if not found.

#### `DataProSession`
- `DataProSession()`  
  Default constructor.
- `void CreateSession()`  
  Initializes Prism infrastructure (bootstrapper, container, event aggregator, region manager) using default config.
- `void CreateSession(string customConfigPath)`  
  Initializes Prism infrastructure using a custom configuration path.
- `void Terminate()`  
  Placeholder for shutdown logic (currently empty).
- `IUnityContainer Container { get; }`  
  Gets the Unity container after session creation.
- `IEventAggregator EventAggregator { get; }`  
  Gets the Prism event aggregator.
- `IRegionManager RegionManager { get; }`  
  Gets the Prism region manager.
- `string CustomConfigPath { get; set; }`  
  Gets/sets the custom configuration path used during session creation.

#### `PageContentHeaderControl`
- `bool UsesSearchControl { get; set; }`  
  Controls visibility of search controls (`searchTextBlock`, `searchTextBox`). Raises `PropertyChanged` for `"UsesSearchControl"`.
- `bool UsesSelectControl { get; set; }`  
  Controls visibility of select controls (`selectTextBlock`, `selectComboBox`). Raises `PropertyChanged` for `"UsesSearchControl"` (note: property name mismatch in `SetProperty` call).

#### `LicensingFooter`
- `Color BackgroundColor { get; }`  
  Gets the footer background color (from `BrushesAndColors.Brush_ApplicationLicensingFooterBackground` if `MainWindow` is `MainWindow`).
- `void OnSetActive()`  
  Updates licensing info and triggers `UpdateLicensingBar()` asynchronously.
- `string LicensedTo { get; set; }`  
  Licensed entity name.
- `string FooterMessage { get; set; }`  
  Combined validation/license expiration messages.
- `string LicenseType { get; set; }`  
  License type string (e.g., `"Professional Edition"`).
- `string DataProVersion { get; set; }`  
  Version string (e.g., `"DataPRO 3.1.0 - "`).

#### `PageContentControl`
- `object MainContent { get; set; }`  
  Gets/sets the main content; on set, calls `OnSetActive()` on the content if it implements `IPageContent`.
- `Color ContentBackgroundColor { get; set; }`  
  Background color; syncs to `NavControl` and `MainContentControl`.
- `bool UsesNavControl { get; set; }`  
  Controls visibility of navigation control (`NavControl`).
- `bool IsInSetMainContentActive()`  
  Returns `true` if `MainContent` is currently being set/activated.
- `ContentControl GetMainContentControl()`  
  Returns the internal `MainContentControl`.
- `virtual void UnSet()`  
  Calls `NavControl.UnSet()` if `UsesNavControl`.
- `virtual bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow)`  
  Delegates validation to `NavControl` or `MainContent` (if `IPageContent`).
- `virtual void OnSetActive()`  
  Calls `NavControl.OnSetActive()` if `UsesNavControl`.

#### `PageActionControlsRibbon`
- `void SetGroups(PageActionControlsGroup[] groups)`  
  Adds groups to the ribbon grid.
- `void SetGroups(Controls.ActionRadioButton[] groups)`  
  Adds radio button groups to the ribbon grid (stored separately in `_newRadioButtons`).
- `Controls.ActionButton GetButton(string id)`  
  Searches all groups for a button with `UniqueId == id`; throws `NullReferenceException` if not found.
- `Controls.ActionButton[] GetButtons()`  
  Returns all buttons from all groups.
- `Controls.ActionLabel GetLabel(string id)`  
  Searches all groups for a label with `UniqueId == id`; throws `NullReferenceException` if not found.
- `Controls.ActionComboBox GetComboBox(string id)`  
  Searches all groups for a combo box with `UniqueId == id`; throws `NullReferenceException` if not found.

#### `PageSearchControl`
- `void ClearSearchTerm()`  
  Clears the `searchTextBox.Text`.
- `bool UsesSearchControl { get; set; }`  
  Controls search visibility; raises `PropertyChanged` for `"SearchVisibility"`.
- `bool UsesSelectControl { get; set; }`  
  Controls select control visibility.
- `Visibility SearchVisibility { get; }`  
  Computed visibility (`Visible` if `UsesSearchControl`, else `Collapsed`).
- `int RaiseSearchDelay { get; set; }`  
  Debounce delay (ms) for search events; if `> 0`, uses `DispatcherTimer`.
- `event SearchDelegate OnSearch`  
  Raised after search term changes (debounced if `RaiseSearchDelay > 0`).

#### `PageNavControlsGroup`
- `UserPermissionLevels GetRequiredPermission()`  
  Gets `_requiredPermission`.
- `UserPermissionLevels GetDefaultRolePermission(DefaultRoles role)`  
  Returns default permission per role (`Read`, `Edit`, `Admin`, etc.).
- `void SetEnabled(bool bEnable)`  
  Enables/disables control based on user permission vs. `_requiredPermission`.
- `bool GetDefaultRoleVisibility(DefaultRoles role)`  
  Returns visibility per role based on `_requiredPermission`.
- `string UniqueId { get; set; }`  
  Unique identifier.
- `string GetName()`  
  Returns `UniqueId`.
- `long GetID()` / `void SetID(long id)`  
  Gets/sets `_id`.
- `void SetVisible(bool bShow)`  
  Sets visibility based on `CurrentUser.IsShowTabFlagSet(this)`.
- `int SetControls(UserControl[] controls, int startingRow)`  
  Adds controls to `navControlGrids` grid; returns number of rows used.

#### `PageMainContentControl`
- `ContentControl GetContentControl()`  
  Returns internal `contentControl`.
- `object MainContent { get; set; }`  
  Gets/sets `contentControl.Content`.
- `Color BackgroundColor { get; set; }`  
  Background color.
- `static void MarkWarning(Control tb)`  
  Sets `BorderBrush` to `Orange` and `BorderThickness` to `2.0` for `NavStep` controls.
- `static void MarkInvalid(Control tb)`  
  Applies error styles (e.g., `PageContentTextBoxErrorStyle`) or sets red border for various control types.
- `static void MarkInvalid(TextBlock tb)`  
  Sets `Foreground` to `Red`.
- `static void MarkValid(Control tb)`  
  Restores default styles for various control types.
- `static void MarkValid(TextBlock tb)`  
  Sets `Foreground` to `Black`.

#### `NavGraphStep`
- `string Title { get; }`  
  Step title (read-only).
- `string SerialNumber { set; }`  
  Sets `sensorSerialNumber.Text`; toggles visibility.
- `string AxisUnit { set; }`  
  Sets `axisUnit.Text`; toggles visibility.
- `Color GraphStepColor { get; set; }`  
  Graph step background color.
- `bool GraphChannel { get; set; }`  
  Controls visibility of `GraphColorVisibility`, `TextVisibility`, and `PartitionVisibility`.
- `Visibility GraphColorVisibility { get; }`  
  `Visible` if `GraphChannel`, else `Collapsed`.
- `Visibility TextVisibility { get; set; }`  
  Controls text visibility.
- `Visibility PartitionVisibility { get; set; }`  
  Controls partition visibility.
- `IPageContent NavStepContent { get; set; }`  
  Content associated with the step.
- `void SetStatus(StatusTypes status)`  
  Updates button/text colors based on `StatusTypes.Current` or `NotCurrent`.
- `void SetCurrent()`  
  Sets button background to `LightGray`.
- `void SetInvalid()` / `void SetValid()`  
  Placeholder methods (currently no-op).

### Routed Events (PageActionButtonsRibbon)
- `FirstGroupFirstButtonClickedEvent`, `FirstGroupSecondButtonClickedEvent`, `FirstGroupThirdButtonClickedEvent`
- `SecondGroupFirstButtonClickedEvent`, `SecondGroupSecondButtonClickedEvent`, `SecondGroupThirdButtonClickedEvent`
- `ThirdGroupThirdButtonClickedEvent`, `FourthGroupFirstButtonClickedEvent`, `FourthGroupSecondButtonClickedEvent`, `FourthGroupThirdButtonClickedEvent`

## 3. Invariants

- **`IPageContent.OnSetActive()`** must be called exactly once when a page becomes active, and **`IPageContent.UnSet()`** must be called before the page is deactivated or destroyed.
- **`WaitCursor`** must be used in a `using` block to ensure cursor restoration; no manual `Dispose()` calls should be missed.
- **`TranslateExtension`** always returns a non-null string; missing keys are indicated by `"#stringnotfound#"` prefix.
- **`PageContentControl.MainContent`** setter prevents re-entrancy via `_bSettingMainContentActive` flag.
- **`PageNavControlsGroup.SetEnabled()`** respects user permissions: controls are disabled if user permission level < `_requiredPermission`.
- **`PageNavControlsGroup.SetVisible()`** respects `CurrentUser.IsShowTabFlagSet(this)` when `bShow` is `true`.
- **`PageSearchControl.RaiseSearchDelay`** must be `>= 0`; negative values are coerced to `0`.
- **`PageMainContentControl.MarkInvalid/MarkValid`** methods must be called only on supported control types (e.g., `TextBox`, `ComboBox`, `ChannelCodeBuilder`, etc.).
- **`NavGraphStep.GraphChannel`** affects multiple computed properties (`GraphColorVisibility`, `TextVisibility`, `PartitionVisibility`); changes must be propagated via `SetProperty`.

## 4. Dependencies

### External Dependencies
- **Prism (Unity)**: `Prism.Events`, `Prism.Regions`, `Prism.Ioc`, `Unity` (used in `DataProSession`).
- **DTS.Slice.Users**: `DTS.Slice.Users.User.UserPermissionLevels`, `DTS.Slice.Users.User.DefaultRoles`, `DTS.Slice.Users.IUIItems` (used in `PageNavControlsGroup`).
- **DTS.Common**: `DTS.Common.Controls`, `DTS.Common.SharedResource.Strings` (used in `LicensingFooter`, `TranslateExtension`).
- **WPF Framework**: `System.Windows`, `System.Windows.Input`, `System.Windows.Media`, `System.Windows.Controls`, `System.Windows.Threading`.
- **C1.WPF**: `C1.WPF` (used in `PageMainContentControl` for `C1NumericBox`).
- **System.Configuration**: Implicitly used via `Settings` class (auto-generated).

### Internal Dependencies
- **`DataPROWin7.Controls` namespace**: `ActionButton`, `ActionComboBox`, `ActionRadioButton`, `ActionLabel`, `PageButton`, `NavStep`, `ChannelCodeBuilder`, `ChannelNameBuilder`, `SupportedExcitationControl`, `DatePicker`, `C1NumericBox`, `ItemsControl`, `GroupBox`, `PageActionControlsGroup`, `PageActionButtonsGroup`.
- **`DataPROWin7.Properties.Settings`**: Auto-generated settings class.
- **`App` class**: Used in `LicensingFooter`, `PageNavControlsGroup`, `PageContentControl` to access `CurrentUser`, `LicenseValidationResult`, `GetVersionString()`.
- **`BrushesAndColors`**: Used in `LicensingFooter`, `NavGraphStep` for color resources.

### Inferred Usage
- `DataProMainWindow` initializes with `LoginControl2` as initial content.
- `PageContentControl` and `PageNavControlsGroup` are used together for hierarchical navigation.
- `PageSearchControl` is integrated into `PageContentHeaderControl` and `PageContentControl`.
- `LicensingFooter` is likely hosted in the main window's footer area.

## 5. Gotchas

- **`PageContentHeaderControl.UsesSelectControl` setter**: Calls `SetProperty(..., "UsesSearchControl")` instead of `"UsesSelectControl"` — likely a typo causing incorrect `PropertyChanged` notifications.
- **`PageActionControlsRibbon.SetGroups(ActionRadioButton[])`**: Stores radio button groups in `_newRadioButtons` but does not expose them via public methods (only `_groups` is used in `GetButtons`, `GetLabel`, `GetComboBox`).
- **`PageActionButtonsRibbon`**: Button click handlers (`FirstGroupFirstButton_Click`, etc.) raise routed events but do not handle selection changes for combo boxes (handlers are empty).
- **`DataProSession.CreateBootstrapper()`**: Bootstrapper is created only once; re-creation is blocked. Attempting to re-initialize after termination may fail silently (returns `null`).
- **`WaitCursor`**: Does not handle multi-threading or nested usage; overlapping `WaitCursor` instances may restore incorrect cursors.
- **`BoolToOppositeBoolConverter.ConvertBack`**: Always throws `NotSupportedException`; not suitable for two-way bindings.
- **`PageContentControl.MainContent` setter**: Skips setting if `_bSettingMainContentActive` is `true`, preventing re-entrancy but potentially ignoring updates during activation.
- **`NavGraphStep.SetInvalid()` / `SetValid()`**: Methods are empty stubs; no visual feedback for invalid states is implemented.
- **`LicensingFooter.UpdateLicensingBar()`**: Runs `UpdateLicensingBar()` on a background thread (`Task.Run`), but UI properties (`LicensedTo`, `FooterMessage`, etc.) are updated directly — may cause cross-thread exceptions if not thread-safe (though `INotifyPropertyChanged` is typically handled on UI thread in WPF).
- **`PageSearchControl.RaiseSearchDelay`**: If `RaiseSearchDelay == 0`, `_raiseSearchTimer` is set to `null` and not reused; repeated searches may recreate the timer unnecessarily.
- **`PageNavControlsGroup.SetControls`**: Row definitions are added dynamically; if `startingRow` is reused across calls, rows may overlap or misalign.
- **`PageContentControl.Validate`**: If `UsesNavControl` is `false` and `MainContent` is not `IPageContent`, validation returns `true` without validation.