Beyhan Oğur
25 KiB
25 KiB
Macro Editor
**Referenced Files in This Document** - [Macro.cs](file://ClassicAssist/Browser/Models/Macro.cs) - [Category.cs](file://ClassicAssist/Browser/Models/Category.cs) - [Metadata.cs](file://ClassicAssist/Browser/Models/Metadata.cs) - [Repository.cs](file://ClassicAssist/Browser/Models/Repository.cs) - [Database.cs](file://ClassicAssist/Browser/Data/Database.cs) - [Filter.cs](file://ClassicAssist/Browser/Data/Filter.cs) - [FilterType.cs](file://ClassicAssist/Browser/Data/FilterType.cs) - [CategoriesConverter.cs](file://ClassicAssist/Browser/Data/CategoriesConverter.cs) - [MacroBrowserControl.xaml.cs](file://ClassicAssist/Browser/MacroBrowserControl.xaml.cs) - [MacroBrowserViewModel.cs](file://ClassicAssist/Browser/MacroBrowserViewModel.cs) - [MacrosCommandWindow.xaml.cs](file://ClassicAssist/UI/Views/Macros/MacrosCommandWindow.xaml.cs) - [MacrosTabControl.xaml.cs](file://ClassicAssist/UI/Views/MacrosTabControl.xaml.cs) - [MacrosTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MacrosTabViewModel.cs) - [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs) - [Python.xshd](file://ClassicAssist/Python.xshd) - [Python.Dark.xshd](file://ClassicAssist/Python.Dark.xshd) - [AvalonEditBehaviour.cs](file://ClassicAssist/UI/Misc/AvalonEditBehaviour.cs) - [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs) - [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs) - [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs) - [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs) - [DebugWindow.xaml.cs](file://ClassicAssist/UI/Views/DebugWindow.xaml.cs) - [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/DebugWindow.axaml.cs) - [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document explains the Macro Editor interface and functionality, focusing on macro creation workflows, script editing capabilities, Python integration (including IntelliSense support and syntax highlighting), organization via folders/categories/metadata, debugging tools, testing in isolation, practical examples for complex automation, and performance optimization techniques. The content is derived from the repository’s UI components, models, and shared macro runtime infrastructure.
Project Structure
The Macro Editor spans multiple layers:
- Browser layer for browsing, filtering, and organizing macros
- UI layer for editing and running macros
- Shared macro runtime for execution, commands, and diagnostics
- Python language support files for syntax highlighting and completion data
graph TB
subgraph "Browser Layer"
BVM["MacroBrowserViewModel"]
BMC["MacroBrowserControl"]
Repo["Repository"]
DB["Database"]
Cat["Category"]
Meta["Metadata"]
Filt["Filter / FilterType"]
CConv["CategoriesConverter"]
end
subgraph "UI Layer"
MTab["MacrosTabControl"]
MCWin["MacrosCommandWindow"]
AEB["AvalonEditBehaviour"]
end
subgraph "Shared Runtime"
ME["MacroEntry"]
MI["MacroInvoker"]
MM["MacroManager"]
SMTW["SystemMessageTextWriter"]
end
subgraph "Python Support"
PCD["PythonCompletionData"]
PXSHD["Python.xshd"]
PDXSHD["Python.Dark.xshd"]
end
subgraph "Debugging"
DW["DebugWindow"]
DVM["DebugViewModel"]
end
BVM --> Repo
Repo --> DB
BVM --> Cat
BVM --> Meta
BVM --> Filt
BVM --> CConv
MTab --> MCWin
MCWin --> AEB
MCWin --> ME
MCWin --> MI
MI --> MM
MI --> SMTW
AEB --> PXSHD
AEB --> PDXSHD
MCWin --> PCD
MCWin --> DW
DW --> DVM
Diagram sources
- MacroBrowserViewModel.cs
- MacroBrowserControl.xaml.cs
- Repository.cs
- Database.cs
- Category.cs
- Metadata.cs
- Filter.cs
- FilterType.cs
- CategoriesConverter.cs
- MacrosTabControl.xaml.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- MacroEntry.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- PythonCompletionData.cs
- Python.xshd
- Python.Dark.xshd
- DebugWindow.xaml.cs
- DebugViewModel.cs
Section sources
- MacroBrowserViewModel.cs
- MacroBrowserControl.xaml.cs
- Repository.cs
- Database.cs
- Category.cs
- Metadata.cs
- Filter.cs
- FilterType.cs
- CategoriesConverter.cs
- MacrosTabControl.xaml.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- MacroEntry.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- PythonCompletionData.cs
- Python.xshd
- Python.Dark.xshd
- DebugWindow.xaml.cs
- DebugViewModel.cs
Core Components
- Macro model and metadata:
- Macro entity with properties for identification, content, and metadata
- Category and Metadata models for organization and descriptive information
- Repository and persistence:
- Repository orchestrates loading/saving macros
- Database abstraction for storage operations
- Browser view model:
- Provides filtering, sorting, and category-based views
- Exposes converters to map categories to display values
- Editing UI:
- Macros command window hosts the editor surface
- AvalonEdit behavior wires syntax highlighting and behaviors
- Python integration:
- Completion data source for IntelliSense
- Syntax highlight definitions for light/dark themes
- Execution and diagnostics:
- Macro entry and invoker orchestrate execution
- System message writer routes output to UI
- Debug window and view model provide tracing and inspection
Section sources
- Macro.cs
- Category.cs
- Metadata.cs
- Repository.cs
- Database.cs
- MacroBrowserViewModel.cs
- CategoriesConverter.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- PythonCompletionData.cs
- Python.xshd
- Python.Dark.xshd
- MacroEntry.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- DebugWindow.xaml.cs
- DebugViewModel.cs
Architecture Overview
The Macro Editor integrates a browser, an editor, and a runtime. The browser loads and filters macros; the editor provides scripting features; the runtime executes macros and exposes commands. Diagnostics are surfaced through a debug window.
sequenceDiagram
participant User as "User"
participant Browser as "MacroBrowserViewModel"
participant Repo as "Repository"
participant DB as "Database"
participant UI as "MacrosCommandWindow"
participant Edit as "AvalonEditBehaviour"
participant Py as "PythonCompletionData"
participant Inv as "MacroInvoker"
participant Man as "MacroManager"
participant Out as "SystemMessageTextWriter"
participant DBG as "DebugWindow"
User->>Browser : Open Macro Browser
Browser->>Repo : Load macros
Repo->>DB : Read storage
DB-->>Repo : Macro list
Repo-->>Browser : Catalog
User->>UI : Create/Edit macro
UI->>Edit : Configure editor
Edit->>Py : Request completions
Py-->>Edit : Completions
User->>UI : Run macro
UI->>Inv : Execute macro
Inv->>Man : Invoke commands
Man-->>Inv : Results
Inv->>Out : Write messages
Out-->>DBG : Stream logs
DBG-->>User : Show trace/output
Diagram sources
- MacroBrowserViewModel.cs
- Repository.cs
- Database.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- PythonCompletionData.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- DebugWindow.xaml.cs
Detailed Component Analysis
Macro Model and Organization
- Macro entity holds core fields such as identifier, name, content, and references to metadata.
- Category represents grouping for macros (folders).
- Metadata captures additional attributes like description, author, version, tags, and visibility flags.
- Repository coordinates persistence and retrieval of macros and their metadata.
- Database abstracts storage operations used by the repository.
classDiagram
class Macro {
+string Id
+string Name
+string Content
+string CategoryId
+string MetadataId
}
class Category {
+string Id
+string Name
}
class Metadata {
+string Id
+string Description
+string Author
+string Version
+string Tags
}
class Repository {
+Load()
+Save(macro)
}
class Database {
+Read()
+Write(data)
}
Macro --> Category : "belongs to"
Macro --> Metadata : "has"
Repository --> Database : "uses"
Diagram sources
Section sources
Browser and Filtering
- MacroBrowserViewModel exposes filtered collections and supports search, category selection, and sorting.
- Filter and FilterType define query criteria and types.
- CategoriesConverter maps category identifiers to human-readable labels for UI binding.
flowchart TD
Start(["Open Browser"]) --> Load["Load catalog via Repository"]
Load --> ApplyFilters{"Apply Filters?"}
ApplyFilters --> |Yes| BuildQuery["Build Filter using FilterType"]
BuildQuery --> Query["Execute query against catalog"]
ApplyFilters --> |No| UseAll["Use full catalog"]
Query --> Display["Display results"]
UseAll --> Display
Display --> End(["Ready to edit/run"])
Diagram sources
Section sources
Script Editing and Python Integration
- MacrosCommandWindow hosts the editor surface and binds to the selected macro.
- AvalonEditBehaviour configures editor behaviors and syntax highlighting.
- PythonCompletionData supplies IntelliSense entries for Python scripts.
- Python.xshd and Python.Dark.xshd define tokenization rules for light/dark themes.
sequenceDiagram
participant UI as "MacrosCommandWindow"
participant Edit as "AvalonEditBehaviour"
participant Py as "PythonCompletionData"
participant Theme as "Python.xshd / Python.Dark.xshd"
UI->>Edit : Initialize editor instance
Edit->>Theme : Load syntax definition
UI->>Py : Request completions on trigger
Py-->>UI : Provide completion items
UI->>Edit : Apply highlighting and completions
Diagram sources
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- PythonCompletionData.cs
- Python.xshd
- Python.Dark.xshd
Section sources
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- PythonCompletionData.cs
- Python.xshd
- Python.Dark.xshd
Macro Execution and Commands
- MacroEntry defines the executable unit and its parameters.
- MacroInvoker orchestrates invocation, context setup, and result handling.
- MacroManager registers and resolves commands available to macros.
- SystemMessageTextWriter streams output for user feedback and debugging.
classDiagram
class MacroEntry {
+string Name
+string Script
+Run(context)
}
class MacroInvoker {
+Invoke(entry)
+SetupContext()
+HandleErrors()
}
class MacroManager {
+RegisterCommands()
+Resolve(commandName)
}
class SystemMessageTextWriter {
+Write(message)
}
MacroInvoker --> MacroEntry : "executes"
MacroInvoker --> MacroManager : "resolves commands"
MacroInvoker --> SystemMessageTextWriter : "writes output"
Diagram sources
Section sources
Debugging Tools
- DebugWindow surfaces logs, errors, and traces produced during macro execution.
- DebugViewModel manages state and bindings for the debug UI.
- SystemMessageTextWriter feeds messages into the debug stream.
sequenceDiagram
participant Inv as "MacroInvoker"
participant Out as "SystemMessageTextWriter"
participant DBG as "DebugWindow"
participant VM as "DebugViewModel"
Inv->>Out : Write error/info messages
Out->>DBG : Append to log buffer
DBG->>VM : Bind log entries
VM-->>DBG : Render trace and variables
Diagram sources
Section sources
Conceptual Overview
- Macro creation workflow:
- Select or create a new macro in the browser
- Assign category and metadata
- Edit script with Python IntelliSense and syntax highlighting
- Save and run in isolation via the command window
- Testing in isolation:
- Use the command window to execute a single macro without global side effects
- Inspect outputs and errors in the debug window
- Organizing large collections:
- Group macros by categories (folders)
- Use metadata tags and descriptions for discoverability
- Leverage filters to narrow down sets during development
[No sources needed since this section doesn't analyze specific files]
Dependency Analysis
The following diagram highlights key dependencies among macro-related components.
graph LR
BrowserVM["MacroBrowserViewModel"] --> Repo["Repository"]
Repo --> DB["Database"]
BrowserVM --> Cat["Category"]
BrowserVM --> Meta["Metadata"]
BrowserVM --> Filt["Filter / FilterType"]
BrowserVM --> CConv["CategoriesConverter"]
CmdWin["MacrosCommandWindow"] --> Edit["AvalonEditBehaviour"]
Edit --> PyDef["Python.xshd / Python.Dark.xshd"]
CmdWin --> PyComp["PythonCompletionData"]
CmdWin --> Entry["MacroEntry"]
Entry --> Inv["MacroInvoker"]
Inv --> Man["MacroManager"]
Inv --> Out["SystemMessageTextWriter"]
Out --> DBG["DebugWindow"]
Diagram sources
- MacroBrowserViewModel.cs
- Repository.cs
- Database.cs
- Category.cs
- Metadata.cs
- Filter.cs
- FilterType.cs
- CategoriesConverter.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- Python.xshd
- Python.Dark.xshd
- PythonCompletionData.cs
- MacroEntry.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- DebugWindow.xaml.cs
Section sources
- MacroBrowserViewModel.cs
- Repository.cs
- Database.cs
- Category.cs
- Metadata.cs
- Filter.cs
- FilterType.cs
- CategoriesConverter.cs
- MacrosCommandWindow.xaml.cs
- AvalonEditBehaviour.cs
- Python.xshd
- Python.Dark.xshd
- PythonCompletionData.cs
- MacroEntry.cs
- MacroInvoker.cs
- MacroManager.cs
- SystemMessageTextWriter.cs
- DebugWindow.xaml.cs
Performance Considerations
- Efficient filtering:
- Prefer precise filters and avoid overly broad queries when browsing large macro sets
- Lazy loading:
- Defer heavy operations until the macro is opened or executed
- Editor responsiveness:
- Keep syntax highlighting definitions minimal and theme-aware
- Limit completion payload size and cache frequently used entries
- Execution overhead:
- Reuse command resolution where possible
- Minimize I/O during runs; batch writes to the message writer
- Memory management:
- Dispose of large buffers and clear debug logs after sessions
[No sources needed since this section provides general guidance]
Troubleshooting Guide
- Syntax issues:
- Verify Python syntax highlighting is active and that completion suggestions appear
- Execution errors:
- Check the debug window for stack traces and system messages
- Confirm command availability via the macro manager
- Persistence problems:
- Ensure repository and database paths are valid and accessible
- Category and metadata:
- Validate category IDs and metadata fields for consistency
Section sources
- AvalonEditBehaviour.cs
- PythonCompletionData.cs
- SystemMessageTextWriter.cs
- DebugWindow.xaml.cs
- Repository.cs
- Database.cs
- Category.cs
- Metadata.cs
Conclusion
The Macro Editor combines a robust browser, a feature-rich editor with Python support, and a flexible runtime with strong diagnostics. By leveraging categories, metadata, and filters, users can organize large macro collections effectively. The integrated debugging tools streamline troubleshooting, while performance-oriented practices ensure smooth operation even with extensive macro libraries.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Practical Examples
- Complex automation workflow:
- Compose multi-step sequences using reusable commands
- Parameterize inputs via macro metadata and pass them at runtime
- Use filters to isolate test subsets during development
- Organizing large collections:
- Group by functional areas (e.g., combat, crafting, navigation)
- Tag macros with version and author metadata for collaboration
- Maintain consistent naming conventions and concise descriptions
[No sources needed since this section doesn't analyze specific files]