142 lines
6.2 KiB
Markdown
142 lines
6.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
BayTemplate is a **Bay Template Designer of Grid Framework DesignTime** tool - a Qt-based application for designing electrical power grid structures. It features a dockable UI with a graphics canvas for placing and manipulating grid elements.
|
|
|
|
## Build Commands
|
|
|
|
### Build the Project
|
|
|
|
使用 CMake presets 进行配置和构建：
|
|
|
|
```bash
|
|
# Configure using preset
|
|
cmake --preset default
|
|
|
|
# Build with Ninja
|
|
ninja -C build/Debug
|
|
```
|
|
|
|
### Output Location
|
|
|
|
- Executable: `build/Debug/BayTemplate.app` (macOS)
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
#### 1. Docking System (Qt Advanced Docking System 4.3.1)
|
|
- **CDockManager** manages dockable panels
|
|
- **Left Dock**: 图元面板 (GraphicElementsPanel) - library of draggable grid elements
|
|
- **Center**: DrawingPanel - main canvas area with DesignerScene
|
|
- **Right Dock**: 属性编辑器 (PropertyEditor) - QDetailsView for editing selected item properties
|
|
|
|
#### 2. Graphics View Framework
|
|
- **DesignerView** (`QGraphicsView` subclass): Custom view with zoom (0.02-50x), pan (middle-button drag), checkerboard background
|
|
- **DesignerScene** (`QGraphicsScene` subclass): Custom scene with grid overlay (20px spacing), routes mouse events through SelectorManager
|
|
|
|
#### 3. Selector System
|
|
Selector hierarchy in `include/util/`:
|
|
- **BaseSelector**: Abstract base for all selectors
|
|
- **CreatingSelector**: Mode for creating new items from template
|
|
- **MovingSelector**: Mode for moving items
|
|
- **RotationSelector**: Mode for rotating items around origin
|
|
- **ScalingSelector**: Mode for scaling items
|
|
- **EditingSelector**: Mode for editing polygon vertex positions
|
|
- **SelectorManager**: Singleton that manages the active working selector
|
|
|
|
Mouse events flow: `DesignerScene` → `SelectorManager::getWorkingSelector()` → specific selector implementation
|
|
|
|
#### 4. Graphics Items (`include/graphicsItem/`)
|
|
- **GraphicsBaseItem**: Abstract base class for all grid elements
|
|
- **GraphicsRectItem**: Rectangle element
|
|
- **GraphicsPolygonItem**: Polygon element (editable vertices)
|
|
- **GraphicsItemGroup**: Container for grouped items (supports flattening to prevent nesting)
|
|
- **GraphicsBusSectionItem**: Bus section element
|
|
- **ItemControlHandle**: Visual handles for manipulation (rotation, scaling, editing)
|
|
|
|
#### 5. Property Editor (Qt PropertyEditor)
|
|
- **QDetailsView**: Qt Quick-based property editor in right dock
|
|
- **QCustomType**: Custom property type for graphics item properties
|
|
- **PropertyTypeCustomization_CustomType**: Custom property editor integration
|
|
- Property editor observes `QGraphicsScene` and displays properties of selected items
|
|
|
|
#### 6. Command Pattern (Undo/Redo)
|
|
- **QUndoStack** (`m_pUndoStack` in CMainWindow) manages undo/redo
|
|
- **OperationCommand**: Base command class
|
|
- **AddItemCommand**: Add item to scene
|
|
- **DeleteItemCommand**: Remove item from scene
|
|
- **CreateItemGoupCommand**: Group selected items (with flattening)
|
|
- **DestroyItemGoupCommand**: Ungroup items
|
|
|
|
### Signal Flow
|
|
|
|
1. **User drags from 图元面板** → `GraphicElementsPanel` emits signal → `DesignerScene::signalAddItem()` → creates item with `AddItemCommand`
|
|
|
|
2. **User clicks on canvas** → `DesignerView` → `DesignerScene` → `SelectorManager::getWorkingSelector()` → selector processes event
|
|
|
|
3. **User selects items** → `DesignerScene::selectionChanged()` → `CMainWindow::onSignal_selectionChanged()` → updates property editor
|
|
|
|
4. **User modifies property in 属性编辑器** → `QDetailsView` updates item property → scene updates
|
|
|
|
### Key Files and Relationships
|
|
|
|
```
|
|
source/main.cpp # Entry point - creates CMainWindow
|
|
└── source/mainwindow.h/.cpp # Main window with CDockManager, initializes all components
|
|
├── initializeDockUi() # Sets up docks (left, center, right)
|
|
├── initializeAction() # Sets up QUndoStack and menu actions
|
|
└── Event handlers # onSignal_addItem, onSignal_selectionChanged, etc.
|
|
|
|
source/drawingPanel.h/.cpp # Central dock widget containing DesignerView
|
|
└── DesignerView + DesignerScene
|
|
|
|
source/designerView.h/.cpp # QGraphicsView subclass - zoom, pan, middle-button navigation
|
|
|
|
source/designerScene.h/.cpp # QGraphicsScene subclass - grid background, group operations
|
|
└── Delegates to SelectorManager for mouse events
|
|
|
|
source/util/selectorManager.h/.cpp # Singleton managing active selector
|
|
└── Selector::mousePressEvent/ReleaseEvent/MoveEvent()
|
|
|
|
source/graphicsItem/ # Graphics item implementations
|
|
├── GraphicsBaseItem # Base class with common functionality
|
|
├── GraphicsRectItem # Rectangle
|
|
├── GraphicsPolygonItem # Editable polygon
|
|
├── GraphicsItemGroup # Item grouping
|
|
└── GraphicsBusSectionItem
|
|
|
|
source/propertyType/ # Custom property editor integration
|
|
├── CustomType.h
|
|
├── CustomGadget.h
|
|
└── PropertyTypeCustomization_CustomType.cpp
|
|
```
|
|
|
|
### Third-Party Dependencies
|
|
|
|
1. **QtADS** (`QtADS/` subdirectory, v4.3.1): Advanced docking system - must be present as subdirectory
|
|
2. **PropertyEditor** (`PropertyEditor/` subdirectory): Qt Quick-based property editing system with QDetailsView
|
|
|
|
Both are added via `add_subdirectory()` in CMakeLists.txt and must exist in the repository root.
|
|
|
|
### Platform Support
|
|
|
|
- **Qt Version**: Qt5 or Qt6 (auto-detected, `find_package(QT NAMES Qt6 Qt5 ...)`)
|
|
- **Architectures**: x86, x64, arm64, aarch64 (auto-detected in CMakeLists.txt)
|
|
- **Platforms**: Windows, macOS, Linux, Android (Android uses shared library)
|
|
|
|
### Important Implementation Details
|
|
|
|
1. **CMAKE_AUTOUIC_SEARCH_PATHS**: Set to `"ui"` in CMakeLists.txt because .ui files are in separate directory from header files
|
|
|
|
2. **Group Flattening**: When creating a group that contains existing groups, the scene flattens nested groups first to prevent group nesting (see `DesignerScene::createGroup()`)
|
|
|
|
3. **Zoom Implementation**: Uses `QGraphicsView::zoom()` with smooth factor `qPow(1.0015, angleDelta.y())` per wheel event
|
|
|
|
4. **Wchar String Conversion**: Uses `QString::fromWCharArray(L"中文")` for Chinese UI strings
|
|
|
|
5. **Resource File**: `resource/BayTemplate.qrc` contains checkerboard background and icons, referenced in .ui files and CMakeLists.txt
|