79 lines
5.2 KiB
Markdown
79 lines
5.2 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- Common/DTS.CommonCore/Interface/Menu/HamburgerMenu/IHamburgerMenuView.cs
|
|||
|
|
- Common/DTS.CommonCore/Interface/Menu/HamburgerMenu/IHamburgerMenuViewModel.cs
|
|||
|
|
generated_at: "2026-04-16T02:34:46.916280+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "2d2eff5fd8108e4e"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# HamburgerMenu
|
|||
|
|
|
|||
|
|
## Documentation: Hamburger Menu Module Interfaces
|
|||
|
|
|
|||
|
|
### 1. Purpose
|
|||
|
|
This module defines the core interfaces (`IHamburgerMenuView` and `IHamburgerMenuViewModel`) for the *Hamburger Menu* UI component within the application. It serves as the contract between the view (UI layer) and view model (logic/data layer) for a navigation menu typically rendered as a collapsible side panel (e.g., triggered by a hamburger icon). The module enables separation of concerns by decoupling UI rendering from business logic, supporting menu item management, lifecycle hooks for activation/deactivation, and event-driven interaction via `MenuItemPressed`.
|
|||
|
|
|
|||
|
|
### 2. Public Interface
|
|||
|
|
|
|||
|
|
#### `IHamburgerMenuView`
|
|||
|
|
- **Inherits**: `IBaseView`
|
|||
|
|
- **Description**: A marker interface representing the *view* (UI) for the hamburger menu. No additional members are defined beyond base view contract. Implementation is expected to render the hamburger menu UI (e.g., `Menu`, `Button`, `Popup`) and bind to `IHamburgerMenuViewModel`.
|
|||
|
|
|
|||
|
|
#### `IHamburgerMenuViewModel`
|
|||
|
|
- **Inherits**: `IBaseViewModel`
|
|||
|
|
- **Properties**:
|
|||
|
|
- `IHamburgerMenuView View { get; set; }`
|
|||
|
|
Gets or sets the associated view instance (standard MVVM pattern for view-model ↔ view binding).
|
|||
|
|
- `bool TestRunning { get; }`
|
|||
|
|
Read-only flag indicating whether a test is currently executing. *Note: Comment references issue #15324 regarding a warning dialog appearing on tab changes for admin users viewing other users’ views.*
|
|||
|
|
|
|||
|
|
- **Methods**:
|
|||
|
|
- `void OnSetActive()`
|
|||
|
|
Invoked when the view becomes active (e.g., when its tab/page is selected). Used for initialization or resource acquisition.
|
|||
|
|
- `void Unset()`
|
|||
|
|
Invoked when the view is deactivated/unloaded. Used for cleanup (e.g., releasing resources, unsubscribing events).
|
|||
|
|
- `ContextMenu GetContextMenu()`
|
|||
|
|
Returns the `ContextMenu` instance used for the hamburger menu. Likely used to attach the menu to a UI element (e.g., `Button.ContextMenu`).
|
|||
|
|
- `void SetMenuItems(string[] items)`
|
|||
|
|
Populates the menu with items derived from the `items` array (e.g., menu item labels).
|
|||
|
|
- `void ClearMenuItems()`
|
|||
|
|
Removes all menu items from the current menu state.
|
|||
|
|
|
|||
|
|
- **Events**:
|
|||
|
|
- `MenuItemPressedDelegate MenuItemPressed { get; set; }`
|
|||
|
|
Event handler invoked when a menu item is selected. The delegate signature is `void delegate(string command)`, where `command` is the identifier (e.g., menu item text or key) of the pressed item.
|
|||
|
|
|
|||
|
|
#### `MenuItemPressedDelegate`
|
|||
|
|
- **Signature**: `delegate void MenuItemPressedDelegate(string command)`
|
|||
|
|
- **Description**: Delegate for menu item selection events. Carries the `command` string identifying the selected menu item.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3. Invariants
|
|||
|
|
- `View` must be set to a valid `IHamburgerMenuView` instance before `OnSetActive()` is called (implied by MVVM pattern).
|
|||
|
|
- `SetMenuItems()` and `ClearMenuItems()` must be called *before* `GetContextMenu()` returns a fully populated menu (ordering implied by typical menu construction workflows).
|
|||
|
|
- `TestRunning` is read-only and externally controlled (implementation not visible here); callers must not modify it directly.
|
|||
|
|
- `MenuItemPressed` must be assigned a handler *before* menu items are interacted with (otherwise, selections will be ignored).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4. Dependencies
|
|||
|
|
- **Internal Dependencies**:
|
|||
|
|
- `DTS.Common.Base` namespace (provides `IBaseView`, `IBaseViewModel`).
|
|||
|
|
- `System.Windows.Controls` (provides `ContextMenu`, `MenuItem`).
|
|||
|
|
- **External Dependencies**:
|
|||
|
|
- `IHamburgerMenuView`/`IHamburgerMenuViewModel` implementations (e.g., WPF view/user control and its view model) must exist elsewhere in the codebase.
|
|||
|
|
- Likely consumed by higher-level navigation or shell modules (e.g., main window or tabbed interface) that manage view lifecycle (`OnSetActive`/`Unset`).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5. Gotchas
|
|||
|
|
- **Ambiguous `GetContextMenu()` semantics**: The method returns a `ContextMenu` but does not specify whether it is a *new instance* or a *cached instance*. Callers must avoid modifying the returned object without understanding ownership (risk of side effects).
|
|||
|
|
- **`TestRunning` flag purpose unclear**: While the property exists, its implementation and update mechanism are not visible here. Its usage in UI logic (e.g., blocking tab changes) is referenced in a comment but not enforced by the interface.
|
|||
|
|
- **No error handling in interface**: Methods like `SetMenuItems()` lack validation or exception guarantees (e.g., null/empty `items` handling).
|
|||
|
|
- **`MenuItemPressed` delegate signature is minimal**: Only passes `string command`; no context (e.g., menu item index, source element) for complex scenarios.
|
|||
|
|
- **Comment references issue #15324**: The inline comment about a warning dialog suggests a known bug or technical debt in tab-switching behavior for admin users. This behavior is *not* reflected in the interface and must be investigated in implementation code.
|
|||
|
|
|
|||
|
|
None identified beyond the above.
|