jessequ
/
BayTemplate
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BayTemplate/CLAUDE.md

7.5 KiB
Raw Permalink Blame History

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

# Create build/debug directory and configure
mkdir -p build/debug && cd build/debug
/Users/jesse/Qt/Tools/CMake/CMake.app/Contents/bin/cmake -S ../.. -B . -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_GENERATOR:STRING=Ninja -DCMAKE_MAKE_PROGRAM:FILEPATH=/Users/jesse/Qt/Tools/Ninja/ninja -DQT_QMAKE_EXECUTABLE:FILEPATH=/Users/jesse/Qt/6.9.3/macos/bin/qmake -DCMAKE_PREFIX_PATH:PATH=/Users/jesse/Qt/6.9.3/macos -DCMAKE_PROJECT_INCLUDE_BEFORE:FILEPATH=/Users/jesse/Platforms/package-manager/auto-setup.cmake -DCMAKE_CXX_COMPILER:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang++ -DCMAKE_C_COMPILER:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -DCMAKE_CXX_FLAGS_INIT:STRING=-DQT_QML_DEBUG -DPostgreSQL_INCLUDE_DIR:FILEPATH=/opt/homebrew/opt/postgresql@17/include/postgresql -DPostgreSQL_LIBRARY_DIR:FILEPATH=/opt/homebrew/opt/postgresql@17/lib/postgresql -DPostgreSQL_LIBRARY:FILEPATH=/opt/homebrew/opt/postgresql@17/lib/postgresql/libpq.dylib

# Build
/Users/jesse/Qt/Tools/Ninja/ninja -C /Users/jesse/Workspaces/projects/qt-projects/qtclaw/BayTemplate/build/debug

Build Output Locations

Platform-specific output directories under build/:

  • build/x64/bin/BayTemplate - Executable (64-bit Intel/AMD)
  • build/x86/bin/BayTemplate - Executable (32-bit)
  • build/arm64/bin/BayTemplate - Executable (64-bit ARM)
  • build/${pd_PlatformDir}/lib/ - Libraries

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