menu-debug

Menu Component Debugging Skill

Systematic debugging and problem diagnosis for Menu component issues in OpenHarmony ACE Engine. This skill provides structured troubleshooting guidance for Menu-related problems with automatic log enhancement patch generation.

Overview

Menu component debugging requires analyzing multiple layers:

Subwindow lifecycle - Window creation, recreation, and destruction
Menu layout algorithm - Width calculation, positioning, and constraint handling
Menu pattern - State management, menu wrapper, and menu items
Pipeline context - Window rect info, theme settings, and display configuration
Event handling - Click detection, state transitions, and gesture processing

Critical Requirements:

⚠️ All log patches MUST be based on actual code analysis - no speculation
⚠️ Log patches MUST follow OpenHarmony logging standards (TAG_LOGI/W/E macros)
⚠️ Always provide context - include relevant variable values in log statements
⚠️ Use existing log tags - ACE_MENU, ACE_SUB_WINDOW, ACE_OVERLAY

Problem Categories

1. Menu Width Issues

Symptoms:

Menu width displays as 0
Menu appears too narrow or wide
Menu width calculation errors

Common Causes:

displayWindowRectInfo.Width() returns 0 (async initialization not complete)
PipelineContext source issues (subwindow vs main window)
Menu parameter configuration Errors
Theme settings problems

2. Subwindow Recreation Issues

Symptoms:

Frequent "recreate subwindow" logs
Menu fails to show on rapid open
Window state transitions (ATTACHING/DETACHING)
Menu displays blank or delayed

Common Causes:

Quick Menu opening (DETACHING state conflict)
Display ID changes
Menu wrapper state mismatches

3. Menu Layout Issues

Symptoms:

Menu positioned incorrectly
Menu overlaps with target
Menu clipped or truncated
Menu displays on wrong screen side

Common Causes:

Window rect calculation errors
Offset calculation problems
Device type issues (foldable phones)
Safe area not considered

4. Menu Crash/Instability

Symptoms:

Menu crashes when opening
Menu disappears unexpectedly
Menu interaction failures

Common Causes:

Null pointer dereferences
Menu pattern lifecycle issues
State management errors

5. Click Response Issues

Symptoms:

Click on menu trigger has no response
Menu fails to open when clicked
Delayed response to menu interaction

Common Causes:

Event hub not properly initialized
Gesture event not registered
Menu state prevents click handling

6. Menu Auto-Close Issues

Symptoms:

Menu closes immediately after opening
Menu disappears when clicked
Menu closes without user interaction

Common Causes:

State machine issues in menu wrapper
Touch event handling conflicts
HideMenu called incorrectly

7. Menu Positioning Issues

Symptoms:

Menu positioned at screen top-left corner
Menu appears at wrong screen position
Menu placement calculation errors

Common Causes:

Offset calculation problems
Anchor point configuration errors
MenuWindowRect calculation incorrect

8. Safe Area/Navigation Bar Issues

Symptoms:

Menu overlaps with navigation bar
Menu covers status bar
Menu doesn't avoid system UI

Common Causes:

Safe area insets not applied
Window rect doesn't account for system UI
Display cutout settings ignored

9. Menu Dimension Issues

Symptoms:

Menu width is 0
Menu height is 0
Menu size calculations return 0

Common Causes:

Async initialization timing
Pipeline context not ready
DisplayWindowRectInfo not properly initialized

Debugging Workflow

Step 1: Identify Problem Category

Based on symptoms, identify which problem category:

Width/Dimension Issues → Look for:

Menu width is 0
menuMaxWidth = 0
displayWindowRectInfo.Width() = 0

Subwindow Issues → Look for:

recreate subwindow
DETACHING state
MenuWindowRect

Layout Issues → Look for:

MenuOffset incorrect
position calculation error
menuWindowRect

Crash Issues → Look for:

Segmentation fault
Null pointer
CHECK_NULL_*

Click/Auto-Close Issues → Look for:

HideMenu called
state transition
gesture event not received

Positioning Issues → Look for:

anchorPoint calculation
MenuWindowRect values
offset errors

Step 2: Locate Key Code Locations

For Width/Dimension Issues:

menu_layout_algorithm.cpp:941 - UpdateChildConstraintByDevice
menu_layout_algorithm.cpp:3618 - GetMenuWindowRectInfo
menu_layout_algorithm.cpp:931 - Pipeline context source
menu_pattern.cpp - Menu wrapper initialization

For Subwindow Issues:

subwindow_manager.cpp:1954 - GetOrCreateMenuSubWindow
subwindow_manager.cpp:1965 - Recreate log
menu_wrapper_pattern.cpp - Menu wrapper lifecycle

For Layout Issues:

menu_layout_algorithm.cpp:3611-3659 - GetMenuWindowRectInfo
menu_pattern.cpp - Menu positioning
multi_menu_layout_algorithm.cpp - Multi-menu layout

For Click/Auto-Close Issues:

menu_wrapper_pattern.cpp - OnDetach/OnAttach
menu_pattern.cpp - Menu state management
menu_view.cpp - Event handling

For Positioning Issues:

menu_layout_algorithm.cpp - GetMenuWindowRectInfo
menu_pattern.cpp - Offset calculation
subwindow_manager.cpp - Window rect calculation

Step 3: Collect Existing Logs

Key log tags to filter:

# Menu-related logs
cat xxx.log | grep "ACE_MENU"
cat xxx.log | grep "ACE_SUB_WINDOW"
cat xxx.log | grep "ACE_OVERLAY"

# Specific issues
cat xxx.log | grep "recreate subwindow"
cat xxx.log | grep "DisplayWindowRectInfo"
cat xxx.log | grep "MenuWindowRect"
cat xxx.log | grep "HideMenu"
cat xxx.log | grep "OnClick"

Critical log patterns:

recreate subwindow → Subwindow recreation occurred
DisplayWindowRectInfo width is 0 → Width initialization problem
DETACHING → Window state transition
MenuWindowRect → Window rect calculation
HideMenu → Menu hide operation

New Problem Analysis (v0.2.0)

Problem 1: Click No Response/No menu pops up on click (Click No Response)

Symptoms:

No response when clicking the menu trigger
The menu does not pop up after clicking
There are no error logs
The click event seems to be ignored

Possible Causes:

The event hub is not initialized correctly
- GestureEventHub is not obtained or created
- The Pan event is not registered to the menu component
The menu state is incorrect
- MenuWrapper is in the DETACHING state
- The MenuPattern state machine blocks new events
The click area is blocked
- Other components cover the menu's click area
- Window z-order issue
The event is consumed
- Other components intercept the click event
- The touch event is not passed to the menu

Debug Steps:

Check event registration

# 查找菜单事件相关日志
cat xxx.log | grep "OnClick"
cat xxx.log | grep "GestureEventHub"

Check the menu state

# 查找菜单状态
cat xxx.log | grep "MenuWrapper"
cat xxx.log | grep "MenuState"

Check the window state

# 查找子窗口状态
cat xxx.log | grep "ACE_SUB_WINDOW"
cat xxx.log | grep "MenuWindowRect"

Code Locations:

menu_wrapper_pattern.cpp:OnDetach() - State transitions
menu_pattern.cpp:OnClick - Click handling
menu_view.cpp:Create() - Menu creation process

Solutions:

Ensure events are registered correctly
- Check GestureEventHub initialization
- Verify Pan event registration
- Confirm the event hub passes correctly
Check the menu state machine
- Verify the OnModifyDone timing
- Ensure the Menu is not in a blocking state
- Check the isShowing_ state
Verify the click area
- Check whether any component is blocking it
- Verify the hitTestStack configuration
- Confirm touch event passing

Add debug logs

// 在点击处理中添加日志
TAG_LOGI(AceLogTag::ACE_MENU, "OnClick called: menuId=%{public}d", menuId);

Problem 2: The menu closes immediately after clicking (Menu Closes Immediately)

Symptoms:

The menu closes immediately after opening
The menu disappears after clicking it
The menu flashes and then disappears
See "HideMenu" log immediately followed by "ShowMenu"

Possible Causes:

State machine error
- MenuWrapper state rapidly switches between ATTACHING and DETACHED
- OnDetach is called unexpectedly
- The state transition logic is flawed
Touch event conflict
- The click event is triggered twice
- Hide and Show events conflict
- Touch down and touch up events are handled incorrectly
Window focus issue
- The Window loses focus, causing the menu to close
- Focus change event triggers hiding
Timeout configuration error
- The Menu timeout is set to 0
- The Duration is too short, causing immediate closing

Debug Steps:

Check state transition logs

# 查找快速的状态变化
cat xxx.log | grep -E "ATTACHING|DETACHING" | head -20

Check HideMenu calls

# 查找谁调用了 HideMenu
cat xxx.log | grep "HideMenu" | grep -B 5 "ShowMenu"

Check touch events

# 查找触摸事件
cat xxx.log | grep "Touch"
cat xxx.log | grep "Click"

Check the window lifecycle

# 查找子窗口创建和销毁
cat xxx.log | grep "GetOrCreateMenuSubWindow"
cat xxx.log | grep "RemoveMenuSubWindow"

Code Locations:

menu_wrapper_pattern.cpp:OnDetach() - State management
menu_wrapper_pattern.cpp:HideMenu() - Hide logic
menu_pattern.cpp - State machine implementation

Solutions:

Fix the state transition logic
- Add state transition logs
- Add transition condition check
- Prevent illegal state transitions
Optimize event handling
- Add event deduplication logic
- Prevent Show/Hide conflicts
- Add event handling delay
Check focus management
- Verify window focus setting
- Confirm focus event handling
- Add focus state logging

Add state protection

// 添加状态检查
if (menuWrapperPattern->GetState() != MenuWrapperState::DETACHING) {
    TAG_LOGW(AceLogTag::ACE_MENU,
        "Invalid HideMenu call, current state=%{public}d",
        static_cast<int>(state));
    return;
}

Problem 3: Menu Positioned at Top-Left

Symptoms:

Menu position at top-left of screen (0,0)
Menu position is clearly incorrect
Menu does not follow the trigger
Offset calculation error

Possible Causes:

Offset calculation error
- targetOffset calculated as 0
- PositionOffset not set correctly
- Initial position uses default value
Anchor configuration error
- anchorPoint not set
- anchorPosition uses default value
- Menu anchored to wrong position
MenuWindowRect calculation error
- GetMenuWindowRectInfo returns incorrect value
- displayWindowRect information error
- Child window size calculation failed
Placement configuration not taking effect
- UpdateMenuPlacement is not being called
- placement property is ignored
- AlignRule configuration error

Debug Steps:

Check position-related logs

# 查找菜单位置计算
cat xxx.log | grep "MenuOffset"
cat xxx.log | grep "MenuPosition"
cat xxx.log | grep "targetOffset"

Check window Rect information

# 查找窗口矩形
cat xxx.log | grep "MenuWindowRect"
cat xxx.log | grep "DisplayWindowRectInfo"

Check placement configuration

# 查找 placement 配置
cat xxx.log | grep "placement"
cat xxx.log | grep "anchor"

Code Locations:

menu_layout_algorithm.cpp:3611-3659 - GetMenuWindowRectInfo
menu_layout_algorithm.cpp - Offset calculation
menu_pattern.cpp - PositionOffset update
menu_view.cpp:1627 - UpdateMenuPlacement

Solutions:

Verify Offset calculation
- Check whether targetOffset is correct
- Verify positionOffset source
- Add offset calculation logging
Check anchor configuration
- Verify anchorPoint setting
- Check anchorPosition property
- Confirm anchor calculation logic
Verify Placement
- Ensure UpdateMenuPlacement is called
- Check AlignRule configuration
- Verify placement type

Add position debug logging

// 添加位置日志
TAG_LOGI(AceLogTag::ACE_MENU,
    "Menu position: offset=(%{public}f,%{public}f), target=(%{public}f,%{public}f)",
    offsetX, offsetY, targetOffsetX, targetOffsetY);

Problem 4: Menu Direction Incorrect

Symptoms:

Menu direction incorrect (should pop up but pops down)
Menu direction does not match trigger
Submenu expansion direction incorrect
Menu pops up on the wrong side

Possible Causes:

Direction parameter error
- fontSize or direction parameter configuration error
- menuDirection enum value incorrect
- Arrow drawing direction incorrect
Placement calculation error
- placement type judgment error
- Top/Bottom/Left/Right confusion
- AlignRule applied incorrectly
Target position calculation error
- Trigger position retrieval error
- TargetOffset uses incorrect value
- Relative position calculation sign error
Layout algorithm direction error
- Column/Row direction setting error
- crossAxis configuration error
- mainAxisSize setting error

Debug Steps:

Check direction-related configuration

# 查找方向配置
cat xxx.log | grep -E "direction|font|arrow"

Check placement configuration

cat xxx.log | grep "placement"
cat xxx.log | grep "AlignDirection"

Check layout direction

cat xxx.log | grep "mainAxisSize"
cat xxx.log | grep "crossAxis"

Code Locations:

menu_pattern.cpp - Direction configuration
menu_layout_algorithm.cpp - Placement calculation
menu_item/ - Menu item layout

Solutions:

Verify Direction parameter
- Check fontSize API call
- Verify direction enum values
- Check arrow drawing logic
Fix Placement calculation
- Ensure placement type is correct
- Check Top/Bottom determination logic
- Verify alignment rules
Check target position
- Verify trigger component position
- Check targetOffset calculation
- Confirm relative position direction

Add direction debug logs

TAG_LOGI(AceLogTag::ACE_MENU,
    "Menu direction: placement=%{public}d, direction=%{public}d",
    placement, direction);

Problem 5: Menu does not avoid cutout/navigation bar (Menu Overlaps System UI)

Symptoms:

Menu is obscured by navigation bar
Menu covers status bar
Menu does not account for system UI safe area
Menu is partially off-screen

Possible Causes:

SafeArea not applied
- GetSafeArea() is not called
- SafeArea insets are not passed to layout
- system_safe_area property not set
Window Rect calculation error
- displayWindowRect does not account for safe area
- Window position and size calculation error
- Cutout state not applied
Z-Order issue
- Menu window level error
- Window type is not PANEL type
- Z-order configuration is incorrect
Maximize setting error
- LayoutFullScreen used incorrectly
- Window mode set to FULLSCREEN instead of FLOATING
- Layout constraint configuration error

Debug Steps:

Check SafeArea-related logs
```
cat xxx.log | grep -i "safe|safeArea"
```

Check Window Mode

cat xxx.log | grep "LayoutFullScreen"
cat xxx.log | grep "WindowMode"

Check Window Rect

cat xxx.log | grep "DisplayWindowRectInfo"

Code Locations:

subwindow_manager.cpp - Window creation
menu_layout_algorithm.cpp - SafeArea application
Menu wrapper - Window mode settings

Solutions:

Apply SafeArea constraints
- Ensure GetSafeArea() is called
- Pass safe area to layout algorithm
- Set system_safe_area property
Adjust Window Mode
- Use FLOATING or PANEL type
- Avoid FULLSCREEN mode
- Set appropriate window properties
Fix Window Rect calculation
- Subtract safe area from window rect
- Ensure menu is within visible area
- Verify cutout handling
Verify Z-Order
- Check window type configuration
- Ensure menu is at the correct level
- Verify relationship with system UI

Problem 6: Menu popup width is 0/height is 0 (Menu Width/Height is 0)

Symptoms:

Menu width calculated as 0
Menu height calculated as 0
Menu displays abnormally narrow or does not display
displayWindowRectInfo returns 0 value

Possible Causes:

Asynchronous initialization not complete
- GetDisplayWindowRectInfo is called before pipeline ready
- displayWindowRect is not yet initialized
- Incorrect timing for asynchronously obtaining display information
Incorrect source of Pipeline Context
- Used the subwindow's context instead of the main window's
- Incorrect determination of Context type
- Issue with PipelineContext initialization timing
MenuParam configuration error
- fontSize parameter not parsed
- MenuParam passed incorrectly
- Property value not set correctly
Calculation formula error
- menuMaxWidthRatio calculated as 0
- displayWidth multiplied by incorrect coefficient
- theme return value used incorrectly

Debug Steps:

Check displayWidth-related logs

# 查找宽度计算
cat xxx.log | grep "displayWidth"
cat xxx.log | grep "displayWindowRect.Width"
cat xxx.log | grep "menuMaxWidthRatio"

Check MenuParam

cat xxx.log | grep "MenuParam"
cat xxx.log | grep "fontSize"

Check Pipeline Context

cat xxx.log | grep "PipelineContext"
cat xxx.log | grep "GetMainPipelineContext"

Code Locations:

menu_layout_algorithm.cpp:920-966 - UpdateChildConstraintByDevice
menu_layout_algorithm.cpp:3618 - GetMenuWindowRectInfo
menu_pattern.cpp - MenuParam handling
Theme-related - menuMaxWidthRatio configuration

Solutions:

Add initialization check

// 在 GetMenuWindowRectInfo 中添加检查
auto displayWidth = displayWindowRectInfo.Width();
if (displayWidth <= 0.0f) {
    TAG_LOGE(AceLogTag::ACE_MENU,
        "Invalid displayWidth=%{public}f, waiting for async init",
        displayWidth);
    return menuWindowRect;
}

Verify Context source
- Check whether the main window context should be used
- Verify PipelineContext type
- Add context source logging
Delay width calculation
- Use default width before asynchronous initialization completes
- Add ready state check
- Prevent use of uninitialized values

Add asynchronous initialization logging

TAG_LOGI(AceLogTag::ACE_MENU,
    "Async display init: displayWidth=%{public}f, ready=%{public}d",
    displayWidth, IsDisplayReady());

Log Enhancement Reference

Key Logging Patterns

1. State Transition Logging

TAG_LOGI(AceLogTag::ACE_SUB_WINDOW,
    "Subwindow state transition: %{public}d -> %{public}d",
    static_cast<int>(oldState), static_cast<int>(newState));

2. Value Context Logging

TAG_LOGI(AceLogTag::ACE_MENU,
    "Calculation: displayWidth=%{public}f, menuMaxWidthRatio=%{public}f, result=%{public}f",
    displayWidth, menuMaxWidthRatio, menuMaxWidth);

3. Code Path Logging

TAG_LOGI(AceLogTag::ACE_MENU,
    "GetMenuWindowRectInfo: host=%{public}p, menuId=%{public}d, targetTag=%{public}d, targetNodeId=%{public}d",
    host.Get(), menuPattern->GetMenuId(), targetTag_, targetNodeId_);

4. Error Context Logging

if (displayWidth <= 0.0f) {
    TAG_LOGE(AceLogTag::ACE_MENU,
        "Invalid displayWidth=%{public}f, expected>%{public}f",
        displayWidth, expectedWidth);
    return;
}

Critical Variables to Log

For Width/Height Issues:

displayWindowRectInfo.Width() / Height()
menuMaxWidth / menuMaxHeight
menuMaxWidthRatio / menuMaxHeightRatio
theme->GetMenuMaxWidthRatio()
pipeline->GetDisplayWindowRectInfo()

For Subwindow Issues:

subwindow->GetDetachState()
subwindow->GetShown()
subwindow->GetRect().GetSize()
instanceId / searchKey.ToString()

For Layout Issues:

menuWindowRect (all fields)
targetOffset_ / targetSize_
GetMenuWindowRectInfo() return value
placement / anchorPosition

Quick Reference Code Locations

Problem Type	File	Line(s)	Function	Key Variables
Click issues	`menu_wrapper_pattern.cpp`	-	`OnDetach` / `OnAttach`	`state_`
Auto-close	`menu_pattern.cpp`	-	State machine	`isShowing_`
Position (top-left)	`menu_layout_algorithm.cpp`	3611-3659	`GetMenuWindowRectInfo`	`menuWindowRect`
Direction	`menu_pattern.cpp`	-	`direction_` / `placement`	-
Safe area	`subwindow_manager.cpp`	-	Window creation params	-
Width=0/Height=0	`menu_layout_algorithm.cpp`	920-966	`UpdateChildConstraintByDevice`	`displayWidth`

Log Filtering Commands

Extract all Menu-related logs:

# Comprehensive Menu logs
grep -E "ACE_MENU|ACE_SUB_WINDOW|ACE_OVERLAY" xxx.log > menu_debug.log

# Width-specific logs
grep -E "DisplayWindowRectInfo|menuMaxWidth|displayWidth" xxx.log

# Subwindow recreation logs
grep -E "recreate subwindow|DETACHING|MenuWindowState" xxx.log

# Positioning logs
grep -E "MenuOffset|MenuPosition|targetOffset|placement" xxx.log

# Click/Event logs
grep -E "OnClick|TouchEvent|GestureEvent" xxx.log

Filter by specific instance:

# For specific container ID
grep "instanceId: 123" xxx.log

# For specific menu node
grep "menuId: 456" xxx.log

Best Practices

Log Enhancement Principles

DO:

✅ Add context - log relevant variable values
✅ Log state transitions - old → new
✅ Use appropriate log level - INFO for normal, WARN for unexpected, ERROR for failures
✅ Include identifiers - node IDs, instance IDs
✅ Log calculations - input values and results
✅ Minimal changes - Only add logging, don't modify logic
✅ Use existing macros - TAG_LOGI/W/E with correct tags
✅ Test compilation - Verify syntax before applying
✅ Document changes - Note what and why for each log

DON'T:

❌ Log without context - just "entered function"
❌ Over-log - excessive logging in loops
❌ Log sensitive data - user information, tokens
❌ Speculate - log actual values only
❌ Modify logic - Only add logging statements

Patch Generation Guidelines

Minimal Changes - Only add logging, don't modify logic
Preserve Formatting - Follow existing code style
Use Existing Macros - TAG_LOGI/W/E with correct tags
Test Compilation - Verify syntax before applying
Document Changes - Note what and why for each log
Contextual Logging - Include surrounding code state in logs

Analysis Workflow

Gather baseline - Collect logs without issue if possible
Apply patch - Add targeted logging
Reproduce issue - Trigger problem with enhanced logging
Extract relevant logs - Filter specific log tags
Trace execution flow - Follow log sequence through code
Identify root cause - Find where unexpected behavior occurs
Implement fix - Address identified issue
Verify resolution - Confirm fix works, remove debug logs if needed

Integration with Other Skills

This skill complements:

compile-analysis - For performance issues in Menu code
build-error-analyzer - If Menu changes cause build failures
xts-component-test - For writing Menu test cases

Version History

0.2.0 (2026-02-12): Added analysis of 6 common issues
- 💫 Added analysis of unresponsive click issue
- 💫 Added analysis of menu auto-close issue
- 💫 Added analysis of menu position in upper-left corner issue
- 💫 Added analysis of incorrect menu direction issue
- 💫 Added analysis of menu avoiding navigation bar issue
- 💫 Added analysis of width/height being 0 issue
- 📝 Provide detailed debugging steps and solutions for each issue
- 🎯 Expanded trigger keywords to cover common user issues
0.1.0 (2026-02-12): Initial version
- ✨ Complete Menu component debugging skill
- 📝 Covers 4 major categories of issues including width, subwindow, layout, and crashes
- 🔧 Provides a systematic debugging workflow
- 📊 Includes key code locations and variable references
- 🎯 Automated log enhancement patch generation

About this skill

Overview

Problem Categories

1. Menu Width Issues

2. Subwindow Recreation Issues

3. Menu Layout Issues

4. Menu Crash/Instability

5. Click Response Issues

6. Menu Auto-Close Issues

7. Menu Positioning Issues

8. Safe Area/Navigation Bar Issues

9. Menu Dimension Issues

Debugging Workflow

Step 1: Identify Problem Category

Step 2: Locate Key Code Locations

Step 3: Collect Existing Logs

New Problem Analysis (v0.2.0)

Problem 1: Click No Response/No menu pops up on click (Click No Response)

Problem 2: The menu closes immediately after clicking (Menu Closes Immediately)

Problem 3: Menu Positioned at Top-Left

Problem 4: Menu Direction Incorrect

Problem 5: Menu does not avoid cutout/navigation bar (Menu Overlaps System UI)

Problem 6: Menu popup width is 0/height is 0 (Menu Width/Height is 0)

Log Enhancement Reference

Key Logging Patterns

Critical Variables to Log

Quick Reference Code Locations

Log Filtering Commands

Best Practices

Log Enhancement Principles

Patch Generation Guidelines

Analysis Workflow

Integration with Other Skills

Version History