DP44/docs/ai/DataPRO/DataPRO.md

---
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-17T15:44:47.349944+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "d26160d5c15903dc"
---

# DataPRO UI Infrastructure Documentation

## 1. Purpose

This module provides the core WPF user interface infrastructure for the DataPRO application. It establishes the main application window, session lifecycle management via Prism/Unity, and a composite navigation system. The code defines contracts for page content (`IPageContent`), action handling (`IActionButtonContainer`), and supplies reusable controls for navigation steps, search functionality, licensing status display, and window customization.

## 2. Public Interface

### Interfaces

**`IActionButtonContainer`**
Defines a contract for components that host and respond to action controls.
- `ActionButton[] GetActionButtons()`: Returns an array of `Controls.ActionButton` instances.
- `void OnActionButtonPress(Controls.ActionButton button)`: Handler for button click events.
- `void OnActionComboBoxChange(Controls.ActionComboBox comboBox)`: Handler for combo box selection changes.
- `void OnActionComboBoxDropDownClose(Controls.ActionComboBox comboBox)`: Handler for combo box drop-down closure.
- `void OnActionRadioButtonPress(Controls.ActionRadioButton button)`: Handler for radio button clicks.

**`IPageContent`**
Defines the lifecycle and interaction contract for content displayed within the navigation system.
- `void StartSearch(string term)`: Initiates a search within the content.
- `bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow)`: Validates content state; returns `true` if valid.
- `void OnSetActive()`: Called when the content becomes active/visible.
- `void SetPermissions(User.UserPermissionLevels actualPermission, User.UserPermissionLevels requiredPermission)`: Configures UI based on user rights.
- `void UnSet(Action OnComplete = null)`: Cleans up resources when content is unloaded.
- `bool OnButtonPress(Controls.PageButton button)`: Handles page-specific button presses.
- `object GetPageContent()`: Retrieves the content object.
- `bool KeyDown(object sender, KeyEventArgs e)`: Handles keyboard input.

### Classes

**`DataProMainWindow` : Window**
The application's main entry point window.
- `DataProMainWindow()`: Constructor that initializes components and sets `contentControl.Content` to a new `LoginControl2`.

**`DataProSession`**
Manages the application session, bootstrapping, and dependency injection container.
- `IUnityContainer Container { get; }`: The Unity dependency container.
- `IEventAggregator EventAggregator { get; }`: Prism event aggregator instance.
- `IRegionManager RegionManager { get; }`: Prism region manager instance.
- `void CreateSession()`: Initializes the session with default configuration.
- `void CreateSession(string customConfigPath)`: Initializes the session with a specific configuration path.
- `void Terminate()`: Called during application shutdown.

**`WaitCursor` : IDisposable**
A utility to temporarily set the mouse cursor to `Cursors.Wait`.
- `WaitCursor()`: Constructor that saves the current cursor and sets `Mouse.OverrideCursor` to `Cursors.Wait`.
- `void Dispose()`: Restores `Mouse.OverrideCursor` to the previous value.

**`BoolToOppositeBoolConverter` : IValueConverter**
WPF value converter that inverts a boolean value.
- `object Convert(object value, Type targetType, object parameter, CultureInfo culture)`: Returns `!(bool)value`.
- `object ConvertBack(...)`: Throws `NotSupportedException`.

**`TranslateExtension` : MarkupExtension**
XAML markup extension for localization.
- `TranslateExtension(string key)`: Constructor accepting the resource key.
- `object ProvideValue(IServiceProvider serviceProvider)`: Returns the localized string from `StringResources.ResourceManager`. Returns `#stringnotfound#` if the key is missing.

**`PageContentControl` : UserControl, INotifyPropertyChanged**
A composite control hosting navigation and main content areas.
- `object MainContent { get; set; }`: The current main content; setting this triggers `OnSetActive()` on `IPageContent` implementations.
- `bool UsesNavControl { get; set; }`: Toggles visibility of the navigation control.
- `bool Validate(ref List<string> errors, ref List<string> warnings, bool displayWindow)`: Delegates validation to the `NavControl` or `MainContent`.
- `void OnSetActive()`: Activates the navigation control.
- `void UnSet()`: Cleans up the navigation control.

**`PageMainContentControl` : UserControl, INotifyPropertyChanged**
Hosts the actual content within a page.
- `object MainContent { get; set; }`: The content to display.
- `ContentControl GetContentControl()`: Returns the internal content presenter.
- `static void MarkInvalid(Control tb)`: Applies error styling (red border, specific styles) to a control.
- `static void MarkValid(Control tb)`: Resets styling for a control.
- `static void MarkWarning(Control tb)`: Applies warning styling (orange border) to a control.

**`PageSearchControl` : UserControl, INotifyPropertyChanged**
Provides search UI with debouncing.
- `bool UsesSearchControl { get; set; }`: Toggles search box visibility.
- `int RaiseSearchDelay { get; set; }`: Delay in milliseconds before firing the search event.
- `event SearchDelegate OnSearch`: Event raised when a search executes.
- `void ClearSearchTerm()`: Clears the search text box.

**`NavGraphStep` : UserControl, INotifyPropertyChanged**
Represents a single step in a visual navigation graph.
- `string Title { get; }`: The display text for the step.
- `IPageContent NavStepContent { get; set; }`: The content associated with this step.
- `void SetStatus(StatusTypes status)`: Updates visual state (`Current`, `NotCurrent`).

**`WindowResizer`**
Helper class to enable borderless window resizing via Win32 API.
- `WindowResizer(Window activeW)`: Attaches to a window and hooks `WndProc`.
- `void resizeWindow(object sender)`: Initiates resize based on the clicked rectangle name (e.g., "top", "bottomLeft").
- `void displayResizeCursor(object sender)`: Updates the cursor to a resize icon based on position.
- `void resetCursor()`: Resets cursor to `Cursors.Arrow`.
- `void dragWindow()`: Initiates a window drag operation.

**`LicensingFooter` : UserControl, INotifyPropertyChanged**
Displays licensing information at the bottom of the UI.
- `void OnSetActive()`: Updates licensing state and messages.
- `string LicensedTo`, `string LicenseType`, `string DataProVersion`, `string FooterMessage`: Bindable properties for display.

**`PageNavControlsGroup` : UserControl, INotifyPropertyChanged, IUIItems**
A container for navigation controls, handling permissions and layout.
- `string UniqueId { get; set; }`: Identifier for the control.
- `int SetControls(UserControl[] controls, int startingRow)`: Populates the internal grid with controls.
- `void SetEnabled(bool bEnable)`: Sets enabled state based on permissions.
- `void SetVisible(bool bShow)`: Sets visibility based on user preferences/permissions.

**`PageActionControlsRibbon` : UserControl**
A ribbon-style container for action controls.
- `void SetGroups(PageActionControlsGroup[] groups)`: Populates the ribbon with groups.
- `ActionButton GetButton(string id)`: Retrieves a button by ID.
- `ActionComboBox GetComboBox(string id)`: Retrieves a combo box by ID.

**`PageActionButtonsRibbon` : UserControl**
A specific ribbon implementation for button groups.
- `void SetGroups(PageActionButtonsGroup[] groups)`: Populates the ribbon.
- Routed Events: `FirstGroupFirstButtonClickedEvent`, `FirstGroupSecondButtonClickedEvent`, etc.

## 3. Invariants

- **Cursor Restoration**: `WaitCursor` must be disposed to restore `Mouse.OverrideCursor`. It is designed to be used within a `using` block.
- **Converter Target Type**: `BoolToOppositeBoolConverter.Convert` requires `targetType` to be `bool`; otherwise, it throws `InvalidOperationException`.
- **Session Initialization**: `DataProSession.CreateSession` must be called before accessing `Container`, `EventAggregator`, or `RegionManager`.
- **Main Content Activation**: Setting `PageContentControl.MainContent` automatically calls `OnSetActive()` on the new content if it implements `IPageContent`, provided the application `MainWindow` is not null.
- **Re-entrancy Guard**: `PageContentControl.MainContent` setter will return immediately without action if `_bSettingMainContentActive` is `true`.
- **Search Delay Coercion**: `PageSearchControl.RaiseSearchDelay` coerces negative values to `0`.

## 4. Dependencies

**Internal Dependencies (Inferred)**
- `DataPROWin7.Controls`: Custom controls (`ActionButton`, `ActionComboBox`, `NavStep`, `PageButton`, etc.).
- `DataPROWin7.Properties`: Application settings and resources.
- `LoginControl2`: Used in `DataProMainWindow` (definition not provided).
- `DataProBootstrapper`: Used in `DataProSession` (definition not provided).

**External Dependencies**
- **Prism & Unity**: `Prism.Events`, `Prism.Regions`, `Prism.Ioc`, `Prism.Unity`, `Unity` for DI and modular architecture.
- **WPF**: `System.Windows`, `System.Windows.Controls`, `System.Windows.Input`, `System.Windows.Markup`.
- **DTS Libraries**: `DTS.Slice.Users` (User permissions), `DTS.Common.SharedResource.Strings` (Localization), `DTS.Common` (Brushes/Colors).
- **ComponentOne**: `C1.WPF` (specifically `C1NumericBox`).
- **Win32 API**: `user32.dll` for `WindowResizer`.

## 5. Gotchas

- **Dead Code**: The file `PageActionButtonsGroup.xaml.cs` contains a class definition that is **entirely commented out**. It should not be considered functional.
- **Namespace Anomaly**: `WindowResizer.cs` is defined in the **global namespace** (it lacks a `namespace` declaration), which is unusual for this codebase.
- **Event Naming Mismatch**: In `PageActionButtonsRibbon`, the `SecondGroupThirdButtonClickedEvent` is registered with the name `"ThirdGroupThirdButtonClickedEvent"`. This typo could cause issues if wiring events by name.
- **Hardcoded Strings in WindowResizer**: The `resizeWindow` and `displayResizeCursor` methods rely on `switch` statements matching the `Name` property of the sender (e.g., "top", "bottomRight"). These names must exactly match the XAML element names.
- **Localization Fallback**: `TranslateExtension` returns the string `"#stringnotfound#"` (appended with the key) rather than throwing an exception or returning `null` if a resource key is missing.
- **Validation Styling**: `PageMainContentControl.MarkInvalid` and `MarkValid` rely on specific styles (`PageContentTextBoxErrorStyle`, etc.) being defined in the application resources. They also contain specific type checks for third-party controls (e.g., `C1NumericBox`) and internal controls (`ChannelCodeBuilder`).
- **Memory Usage**: Comments in `DataProSession` warn that the bootstrapper loads ~40MB and cannot be cleanly unloaded once created.