Урок 2. Ваш первый аддон: «Hello World»

📘 Учебный курс: Создание аддонов для FreeCAD

Цель урока: создать простой аддон, который добавляет новую рабочую среду с кнопкой, и при нажатии показывает сообщение.

---

📁 Шаг 1. Подготовка папки аддона

Убедитесь, что у вас есть папка:

.../FreeCAD/Mod/HelloWorldAddon/

Если нет — создайте её.

💡 Имя папки важно: оно должно совпадать с именем модуля в коде.
Мы будем использовать HelloWorldAddon.

Внутри этой папки создайте два файла:

• InitGui.py
• hello_workbench.py

❗ Не используйте пробелы или кириллицу в именах файлов и папок!

---

📄 Шаг 2. Файл InitGui.py — точка входа

Этот файл автоматически запускается FreeCAD при старте, если лежит в папке аддона.

Откройте его в редакторе и вставьте следующий код:

# InitGui.py
import FreeCADGui
from HelloWorldAddon.hello_workbench import HelloWorldWorkbench

FreeCADGui.addWorkbench(HelloWorldWorkbench())

🔍 Что делает этот код?

1. Импортирует нашу рабочую среду из файла hello_workbench.py
2. Регистрирует её в интерфейсе FreeCAD через FreeCADGui.addWorkbench()

⚠️ Обратите внимание:
from HelloWorldAddon.hello_workbench — здесь HelloWorldAddon — это имя папки, а hello_workbench — имя файла без расширения .py.

---

📄 Шаг 3. Файл hello_workbench.py — логика аддона

Теперь создадим саму рабочую среду.

Вставьте в hello_workbench.py следующий код:

# hello_workbench.py
import FreeCAD, FreeCADGui
from PySide import QtGui

# === КОМАНДА: то, что происходит при нажатии кнопки ===
class HelloWorldCommand:
    def GetResources(self):
        """Возвращает данные для отображения команды"""
        return {
            "MenuText": "Say Hello",      # Текст в меню
            "ToolTip": "Show a greeting", # Всплывающая подсказка
            "Pixmap": ""                  # Путь к иконке (пока пусто)
        }

    def Activated(self):
        """Вызывается при нажатии кнопки"""
        QtGui.QMessageBox.information(
            None,
            "FreeCAD Addon",
            "Привет, мир!\nТы только что запустил свой первый аддон!"
        )

    def IsActive(self):
        """Когда команда доступна? (всегда — True)"""
        return True


# === РАБОЧАЯ СРЕДА: объединяет команды в группу ===
class HelloWorldWorkbench(FreeCADGui.Workbench):
    # Название, которое будет отображаться в списке
    MenuText = "Hello World"
    ToolTip = "Моя первая рабочая среда"

    def Initialize(self):
        """Вызывается при активации рабочей среды"""
        # Список имён команд
        self.list = ["HelloWorldCommand"]

        # Добавляем панель инструментов
        self.appendToolbar("Hello Tools", self.list)

        # Добавляем пункт в меню
        self.appendMenu("Hello World", self.list)

    def GetClassName(self):
        """Обязательный метод для Python-рабочих сред"""
        return "Gui::PythonWorkbench"


# === РЕГИСТРАЦИЯ КОМАНДЫ ===
FreeCADGui.addCommand("HelloWorldCommand", HelloWorldCommand())

🔍 Разбор кода по частям:

1. Команда (HelloWorldCommand)

• GetResources() — описывает, как команда выглядит в интерфейсе
• Activated() — что происходит при нажатии
• IsActive() — когда кнопка активна (например, только если есть документ)

2. Рабочая среда (HelloWorldWorkbench)

• Наследуется от FreeCADGui.Workbench
• Метод Initialize() добавляет команды на панель и в меню
• GetClassName() говорит FreeCAD: «это Python-рабочая среда»

3. Регистрация

• FreeCADGui.addCommand() связывает имя "HelloWorldCommand" с классом

---

▶️ Шаг 4. Запуск и проверка

1. Сохраните оба файла
2. Закройте FreeCAD (если был открыт)
3. Запустите FreeCAD заново

💡 FreeCAD загружает аддоны только при старте, поэтому перезапуск обязателен.

Как проверить, что аддон работает?

1. В правом нижнем углу FreeCAD нажмите на название текущей рабочей среды (например, «Part Design»)
2. В выпадающем списке найдите «Hello World» и выберите его
3. На панели инструментов появится кнопка «Say Hello»
4. Нажмите её → должно появиться окно с приветствием!

✅ Поздравляем! Вы создали свой первый аддон!

---

🔍 Шаг 5. Отладка (если что-то не работает)

Если аддон не появился или выдал ошибку:

1. Откройте Report view:
   View → Panels → Report view
2. Ищите красные сообщения об ошибках

Частые проблемы:

Проблема	Решение
ModuleNotFoundError: No module named 'HelloWorldAddon'	Проверьте имя папки — оно должно быть точно таким же, как в from HelloWorldAddon...
Кнопка есть, но ничего не происходит	Проверьте, нет ли ошибок в Activated() (например, забыли import QtGui)
Аддон не появляется в списке	Убедитесь, что файл называется именно InitGui.py (не initgui.py, не InitGUI.py)
Ошибка синтаксиса	Проверьте отступы (в Python они важны!) и скобки

💡 Совет: в Windows имена файлов не чувствительны к регистру, но в Linux/macOS — чувствительны. Лучше писать точно: InitGui.py.

---

🧪 Практическое задание

1. Измените текст сообщения в Activated() на свой
2. Попробуйте добавить вторую команду (например, «Say Goodbye»)
3. Добавьте её в тот же список self.list и проверьте, что появляются две кнопки

Пример второй команды:

class GoodbyeCommand:
    def GetResources(self):
        return {"MenuText": "Say Goodbye", "ToolTip": "Bye!"}
    def Activated(self):
        QtGui.QMessageBox.information(None, "Bye", "До свидания!")
    def IsActive(self):
        return True

# Не забудьте зарегистрировать!
FreeCADGui.addCommand("GoodbyeCommand", GoodbyeCommand())

И обновите список:

self.list = ["HelloWorldCommand", "GoodbyeCommand"]

---

▶️ Что дальше?

В Уроке 3 мы:

• Научимся создавать настоящие 3D-объекты (коробки, цилиндры)
• Разберёмся, как устроена документная модель FreeCAD
• Сделаем аддон, который строит параметрическую деталь