82 lines
6.0 KiB
Markdown
82 lines
6.0 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuView.cs
|
||
- Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuViewModel.cs
|
||
generated_at: "2026-04-16T03:09:52.260112+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "9a1e8d073f3885f4"
|
||
---
|
||
|
||
# HamburgerMenu
|
||
|
||
## Documentation: Hamburger Menu Module Interfaces
|
||
|
||
### 1. Purpose
|
||
This module defines the contract interfaces (`IHamburgerMenuView` and `IHamburgerMenuViewModel`) for the hamburger menu UI component in the application. It serves as the presentation-layer abstraction for a navigation menu (likely the primary sidebar or top-level menu), separating view concerns (via `IHamburgerMenuView`) from business logic and state management (via `IHamburgerMenuViewModel`). The module enables dynamic population and interaction with menu items, supports activation/deactivation lifecycle events, and provides a mechanism for enabling/disabling the menu—likely to prevent user interaction during sensitive operations (e.g., admin viewing another user’s context, as referenced in the code comment).
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `IHamburgerMenuView`
|
||
- **Inherits**: `IBaseView`
|
||
- **Description**: A marker interface representing the view layer for the hamburger menu. No additional members beyond base view contract. Used for dependency injection or view-model binding to ensure type safety and separation of concerns.
|
||
|
||
#### `IHamburgerMenuViewModel`
|
||
- **Inherits**: `IBaseViewModel`
|
||
- **Properties**:
|
||
- `IHamburgerMenuView View { get; set; }`
|
||
Gets or sets the associated view instance. Used for view-model/view coordination (e.g., updating UI state).
|
||
- `bool IsEnabled { get; }`
|
||
Read-only property indicating whether the hamburger menu is currently enabled (i.e., interactive).
|
||
- `MenuItemPressedDelegate MenuItemPressed { get; set; }`
|
||
Gets or sets a delegate handler invoked when a menu item is selected.
|
||
|
||
- **Methods**:
|
||
- `void OnSetActive()`
|
||
Invoked when the view becomes active (e.g., tab selected or view loaded). Intended for initialization logic (e.g., populating menu items, registering event handlers).
|
||
- `void Unset()`
|
||
Invoked when the view is unloaded or deactivated. Intended for cleanup (e.g., unregistering handlers, releasing resources).
|
||
- `ContextMenu GetContextMenu()`
|
||
Returns the `ContextMenu` instance used for the hamburger menu. Likely used to attach the menu to a UI element (e.g., a button or icon).
|
||
- `void SetMenuItems(string[] items)`
|
||
Populates the menu with items derived from the provided string array. Each string likely represents a menu item label or command name.
|
||
- `void ClearMenuItems()`
|
||
Removes all menu items from the current menu.
|
||
- `void EnableMenu(bool enable)`
|
||
Enables or disables the hamburger menu based on the `enable` parameter. Affects `IsEnabled` state (though `IsEnabled` itself is read-only, its value is controlled via this method).
|
||
|
||
#### `MenuItemPressedDelegate`
|
||
- **Signature**: `delegate void MenuItemPressedDelegate(string command)`
|
||
- **Description**: Delegate for handling menu item selection events. The `command` parameter identifies the selected menu item (e.g., by label, key, or command name).
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- `IHamburgerMenuViewModel.View` must be set before `OnSetActive()` is called (implied by typical MVVM patterns and lifecycle semantics).
|
||
- `IsEnabled` reflects the current enabled state of the menu and is updated only via `EnableMenu(bool)`.
|
||
- `SetMenuItems(string[])` and `ClearMenuItems()` must be called in a mutually exclusive manner relative to `GetContextMenu()`—i.e., the returned `ContextMenu` must reflect the latest state after these operations.
|
||
- `OnSetActive()` and `Unset()` are expected to be called in balanced pairs (e.g., `OnSetActive()` on activation, `Unset()` on deactivation).
|
||
- `MenuItemPressed` must be non-null before menu items are interacted with (though not enforced by interface—consumers must handle null delegates).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
- **Depends on**:
|
||
- `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel` base interfaces).
|
||
- `System.Windows.Controls` (for `ContextMenu`, `MenuItem` types—indicating WPF UI framework usage).
|
||
- **Used by**:
|
||
- Likely consumed by a WPF view (e.g., `UserControl`) implementing `IHamburgerMenuView`.
|
||
- View models or services that manage application navigation or global commands (e.g., a main window view model or menu controller).
|
||
- **Inferred consumers**: Any module requiring dynamic hamburger menu population (e.g., group/channel management, user switching, admin tools).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **Critical**: The comment `//15324 Warning dialog displayed on every tab change once admin user tries to view another users view` indicates a known bug where enabling/disabling the menu (`EnableMenu`) may be tied to user context changes, potentially causing excessive warnings. This suggests `EnableMenu(false)` might be used to suppress interactions during sensitive operations, but the implementation may not correctly manage state transitions or dialog suppression.
|
||
- `IsEnabled` is read-only; external code cannot directly set it—must use `EnableMenu(bool)`. Misuse (e.g., bypassing `EnableMenu`) could lead to inconsistent state.
|
||
- `SetMenuItems(string[])` does not specify how items map to commands or UI behavior (e.g., are items labels, keys, or full command strings?). Implementation details are hidden.
|
||
- `GetContextMenu()` returns a `ContextMenu` instance, but the interface does not clarify whether this is a new instance per call or a cached reference. Repeated calls may or may not return the same object.
|
||
- No explicit thread-safety guarantees are provided for methods like `SetMenuItems`, `ClearMenuItems`, or `EnableMenu`. If called from non-UI threads, marshaling to the UI thread may be required.
|
||
- **None identified from source alone** for lifecycle management (e.g., `OnSetActive`/`Unset` ordering), but real-world usage may require additional constraints (e.g., `Unset()` must be idempotent). |