DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Menu/HamburgerMenu.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuView.cs Common/DTS.Common/Interface/Menu/HamburgerMenu/IHamburgerMenuViewModel.cs	2026-04-16T03:09:52.260112+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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).