EzUI/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

EzUI is a Windows desktop UI framework built on Direct2D. It provides a C++ API for creating modern Windows applications with custom controls, layouts, and styling.

## Build Commands

The project uses CMake for building. Prebuilt libraries exist in `lib/` for both x64 and x86 architectures.

### Build Static Library (EzUI)

```bash
# Generate and build (choose one)
cmake -G "Visual Studio 17 2022" -A x64 -S . -B build/x64
cmake -G "Visual Studio 17 2022" -A Win32 -S . -B build/x86

# Build Debug or Release
cmake --build build/x64 --config Debug
cmake --build build/x64 --config Release

# Or use build.bat to build all configurations at once
build.bat
```

### Build Demos

```bash
# Build demos (from demo/ directory)
cd demo
mkdir build && cd build
cmake ..
cmake --build . --config Debug/Release
```

Key demo projects in `demo/`:
- `helloWorld` - Basic controls demo
- `QQ` - QQ-style login UI demo
- `kugou` - Kugou music player demo
- `TableViewDemo` - TableView control demo

## Architecture

### Core Classes

- **Window** ([include/EzUI/Window.h](include/EzUI/Window.h)) - Top-level window, inherits from Object, manages HWND, handles message loop
- **Control** ([include/EzUI/Control.h](include/EzUI/Control.h)) - Base class for all UI elements, contains m_controls (child collection), Style/HoverStyle/ActiveStyle/DisabledStyle
- **Application** ([include/EzUI/Application.h](include/EzUI/Application.h)) - Manages message loop, resource loading, high DPI

### Layout System

- **HLayout** - Horizontal layout container
- **VLayout** - Vertical layout container
- Uses DockStyle (None, Horizontal, Vertical, Fill) for child control positioning
- Layout state machine: None → Pend → Layouting → None

### Rendering

- **DXRender** (Direct2D) handles all graphics
- Paint pipeline: OnPaintBefore → OnBackgroundPaint → OnForePaint → OnBorderPaint → OnChildPaint
- Uses PushLayer/PopLayer for clipping regions
- Color uses BGRA format internally

### Control Hierarchy

```
Object
├── Control (base for all widgets)
│   ├── Window (top-level, owns HWND)
│   ├── BorderlessWindow (frameless window)
│   ├── LayeredWindow (transparency support)
│   ├── PopupWindow (modal/popup dialogs)
│   ├── Label
│   ├── Button
│   ├── TextBox
│   ├── ComboBox
│   ├── CheckBox
│   ├── RadioButton
│   ├── PictureBox
│   ├── ProgressBar
│   ├── Menu
│   ├── ScrollBar / HScrollBar / VScrollBar
│   ├── HLayout / VLayout
│   ├── HListView / VListView / TileListView / PagedListView
│   ├── TreeView
│   ├── TableView
│   └── TabLayout
└── IFrame (container frame for embedding)
```

### Event System

Events defined in [include/EzUI/EzUI.h](include/EzUI/EzUI.h):
- Mouse: OnMouseDown, OnMouseUp, OnMouseMove, OnMouseEnter, OnMouseLeave, OnMouseWheel, OnMouseDoubleClick
- Keyboard: OnKeyDown, OnKeyUp, OnKeyChar
- Focus: OnFocus, OnKillFocus
- Paint: OnPaint
- Layout: OnMove, OnSize

ControlState enum (bit flags): None(1), Static(2), Disabled(4), Checked(8), Hover(16), Active(32)

### Key Patterns

1. **Thread Safety**: Use `BeginInvoke()` and `Invoke()` for cross-thread UI updates (uses hidden message window)
2. **Memory Management**: Controls can be parented - parent deletes children. Use `Attach()` / `Detach()` for resource management
3. **Styling**: ControlStyle supports inheritance. Use SetStyleSheet() for CSS-like styling
4. **XML Loading**: Window::LoadXml() loads UI from XML files

### Additional Resources

- [doc/Control_Guide.md](doc/Control_Guide.md) - Comprehensive guide for the Control class, including CSS property mapping, event handling, and best practices

### File Organization

- `include/EzUI/` - Public headers
- `sources/` - Implementation files
- `lib/` - Prebuilt static libraries (EzUI_Debug/Release_{Win32,x64}.lib)