Lesson 2. Your First Addon: «Hello World»

📘 Tutorial: Creating Addons for FreeCAD

Lesson Goal: Create a simple addon that adds a new workbench with a button, and displays a message when clicked.

---

📁 Step 1. Preparing the Addon Folder

Make sure you have the folder:

.../FreeCAD/Mod/HelloWorldAddon/

If not, create it.

💡 The folder name is important: it must match the module name in the code.
We will use HelloWorldAddon.

Inside this folder, create two files:

• InitGui.py
• hello_workbench.py

❗ Do not use spaces or Cyrillic characters in file and folder names!

---

📄 Step 2. InitGui.py File — Entry Point

This file is automatically launched by FreeCAD at startup if it’s in the addon folder.

Open it in an editor and paste the following code:

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

FreeCADGui.addWorkbench(HelloWorldWorkbench())

🔍 What does this code do?

1. Imports our workbench from the hello_workbench.py file
2. Registers it in the FreeCAD interface via FreeCADGui.addWorkbench()

⚠️ Note:
from HelloWorldAddon.hello_workbench — here HelloWorldAddon is the folder name, and hello_workbench is the file name without the .py extension.

---

📄 Step 3. hello_workbench.py File — Addon Logic

Now let’s create the workbench itself.

Paste the following code into hello_workbench.py:

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

# === COMMAND: what happens when the button is clicked ===
class HelloWorldCommand:
    def GetResources(self):
        """Returns data for displaying the command"""
        return {
            "MenuText": "Say Hello",      # Text in the menu
            "ToolTip": "Show a greeting", # Tooltip
            "Pixmap": ""                  # Path to icon (empty for now)
        }

    def Activated(self):
        """Called when the button is clicked"""
        QtGui.QMessageBox.information(
            None,
            "FreeCAD Addon",
            "Hello, world!\nYou just launched your first addon!"
        )

    def IsActive(self):
        """When is the command available? (always — True)"""
        return True


# === WORKBENCH: groups commands together ===
class HelloWorldWorkbench(FreeCADGui.Workbench):
    # Name that will be displayed in the list
    MenuText = "Hello World"
    ToolTip = "My first workbench"

    def Initialize(self):
        """Called when the workbench is activated"""
        # List of command names
        self.list = ["HelloWorldCommand"]

        # Add toolbar
        self.appendToolbar("Hello Tools", self.list)

        # Add menu item
        self.appendMenu("Hello World", self.list)

    def GetClassName(self):
        """Required method for Python workbenches"""
        return "Gui::PythonWorkbench"


# === COMMAND REGISTRATION ===
FreeCADGui.addCommand("HelloWorldCommand", HelloWorldCommand())

🔍 Code Breakdown by Parts:

1. Command (HelloWorldCommand)

• GetResources() — describes how the command looks in the interface
• Activated() — what happens when clicked
• IsActive() — when the button is active (e.g., only if there’s a document)

2. Workbench (HelloWorldWorkbench)

• Inherits from FreeCADGui.Workbench
• The Initialize() method adds commands to the toolbar and menu
• GetClassName() tells FreeCAD: «this is a Python workbench»

3. Registration

• FreeCADGui.addCommand() links the name `