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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T03:49:31.452209+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.