forbes-0023
2f89f8cbb0
All checks were successful
Build and Test / build (pull_request) Successful in 30m3s
- Create docs/examples/example-addon/ with a complete, copy-paste-ready addon skeleton demonstrating command registration, context injection, dock panels, lifecycle hooks, and event bus subscription - Add Examples section to docs/src/SUMMARY.md - Add quick-start cross-reference in writing-an-addon.md
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# Example Addon Template
|
|
|
|
A minimal but complete Kindred Create addon that demonstrates all major SDK integration points. Copy this directory into `mods/`, rename it, and start building.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
example-addon/
|
|
├── package.xml Addon manifest with <kindred> extensions
|
|
├── Init.py Console-mode bootstrap (runs in all modes)
|
|
├── InitGui.py GUI bootstrap — deferred registration
|
|
└── example_addon/
|
|
├── __init__.py Python package marker
|
|
├── commands.py FreeCAD command via kindred_sdk.register_command()
|
|
└── panel.py Dock panel widget factory
|
|
```
|
|
|
|
## What This Template Demonstrates
|
|
|
|
| Feature | File | SDK function |
|
|
|---------|------|-------------|
|
|
| Addon manifest with version bounds and dependencies | `package.xml` | — |
|
|
| Console bootstrap | `Init.py` | — |
|
|
| Deferred GUI initialization with `QTimer.singleShot` | `InitGui.py` | — |
|
|
| Command registration | `commands.py` | `kindred_sdk.register_command()` |
|
|
| Injecting commands into existing contexts | `InitGui.py` | `kindred_sdk.inject_commands()` |
|
|
| Dock panel registration | `InitGui.py`, `panel.py` | `kindred_sdk.register_dock_panel()` |
|
|
| Context lifecycle hooks | `InitGui.py` | `kindred_sdk.on_context_enter()` |
|
|
| Event bus subscription | `InitGui.py` | `kindred_sdk.on()` |
|
|
|
|
## Installation (for testing)
|
|
|
|
1. Copy or symlink this directory into the `mods/` folder at the repository root:
|
|
|
|
```bash
|
|
cp -r docs/examples/example-addon mods/example-addon
|
|
```
|
|
|
|
2. Launch Kindred Create:
|
|
|
|
```bash
|
|
pixi run freecad
|
|
```
|
|
|
|
3. Open the Python console (View > Panels > Python console) and verify:
|
|
|
|
```
|
|
example-addon: console init
|
|
```
|
|
|
|
4. The "Example Panel" dock widget should appear on the right after ~2 seconds.
|
|
|
|
5. To test the command, create a Part Design Body and look for "Hello World" in the Part Design toolbar.
|
|
|
|
## Customizing
|
|
|
|
1. **Rename** — change `example-addon` and `example_addon` to your addon's name in all files
|
|
2. **Update `package.xml`** — set your name, description, repository URL, and load priority
|
|
3. **Add commands** — create more functions in `commands.py` and register them
|
|
4. **Add contexts** — use `kindred_sdk.register_context()` for custom editing modes
|
|
5. **Add overlays** — use `kindred_sdk.register_overlay()` for conditional toolbars
|
|
6. **Theme colors** — use `kindred_sdk.get_theme_tokens()` for Catppuccin Mocha palette access
|
|
|
|
## Common Pitfalls
|
|
|
|
- **Missing `<workbench>` tag** — `InitGui.py` will not be loaded without it, even if you don't register a workbench
|
|
- **Import at module level** — avoid importing `kindred_sdk` or `PySide6` at the top of `InitGui.py`; use deferred imports inside functions to avoid load-order issues
|
|
- **Blocking startup** — keep each `QTimer.singleShot` callback fast; do heavy work in background threads
|
|
- **Forgetting `<dependency>sdk</dependency>`** — your addon may load before the SDK if you omit this
|
|
|
|
## Further Reading
|
|
|
|
- [Writing an Addon](../../src/development/writing-an-addon.md) — full tutorial
|
|
- [Package.xml Schema](../../src/development/package-xml-schema.md) — manifest reference
|
|
- [KCSDK Python API](../../src/reference/kcsdk-python.md) — complete API reference
|