Lezione 2. Il tuo primo addon: «Hello World»

📘 Corso di formazione: Creazione di addon per FreeCAD

Obiettivo della lezione: creare un semplice addon che aggiunge un nuovo ambiente di lavoro con un pulsante, e al clic mostra un messaggio.

---

📁 Passo 1. Preparazione della cartella dell’addon

Assicurati di avere la cartella:

.../FreeCAD/Mod/HelloWorldAddon/

Se non c’è, creala.

💡 Il nome della cartella è importante: deve corrispondere al nome del modulo nel codice.
Useremo HelloWorldAddon.

All’interno di questa cartella crea due file:

• InitGui.py
• hello_workbench.py

❗ Non usare spazi o caratteri cirillici nei nomi di file e cartelle!

---

📄 Passo 2. File InitGui.py — punto di ingresso

Questo file viene avviato automaticamente da FreeCAD all’avvio, se si trova nella cartella dell’addon.

Aprilo nell’editor e incolla il seguente codice:

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

FreeCADGui.addWorkbench(HelloWorldWorkbench())

🔍 Cosa fa questo codice?

1. Importa il nostro ambiente di lavoro dal file hello_workbench.py
2. Registra l’ambiente di lavoro nell’interfaccia di FreeCAD tramite FreeCADGui.addWorkbench()

⚠️ Attenzione:
from HelloWorldAddon.hello_workbench — qui HelloWorldAddon è il nome della cartella, e hello_workbench è il nome del file senza estensione .py.

---

📄 Passo 3. File hello_workbench.py — logica dell’addon

Ora creiamo l’ambiente di lavoro stesso.

Incolla in hello_workbench.py il seguente codice:

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

# === COMANDO: ciò che accade quando si preme il pulsante ===
class HelloWorldCommand:
    def GetResources(self):
        """Restituisce i dati per la visualizzazione del comando"""
        return {
            "MenuText": "Say Hello",      # Testo nel menu
            "ToolTip": "Show a greeting", # Suggerimento
            "Pixmap": ""                  # Percorso dell'icona (attualmente vuoto)
        }

    def Activated(self):
        """Chiamato quando si preme il pulsante"""
        QtGui.QMessageBox.information(
            None,
            "FreeCAD Addon",
            "Ciao mondo!\nHai appena avviato il tuo primo addon!"
        )

    def IsActive(self):
        """Quando il comando è disponibile? (sempre — True)"""
        return True


# === AMBIENTE DI LAVORO: raggruppa i comandi ===
class HelloWorldWorkbench(FreeCADGui.Workbench):
    # Nome che verrà visualizzato nell'elenco
    MenuText = "Hello World"
    ToolTip = "Il mio primo ambiente di lavoro"

    def Initialize(self):
        """Chiamato all'attivazione dell'ambiente di lavoro"""
        # Elenco dei nomi dei comandi
        self.list = ["HelloWorldCommand"]

        # Aggiungiamo la barra degli strumenti
        self.appendToolbar("Hello Tools", self.list)

        # Aggiungiamo una voce al menu
        self.appendMenu("Hello World", self.list)

    def GetClassName(self):
        """Metodo obbligatorio per gli ambienti di lavoro Python"""
        return "Gui::PythonWorkbench"


# === REGISTRAZIONE DEL COMANDO ===
FreeCADGui.addCommand("HelloWorldCommand", HelloWorldCommand())

🔍 Analisi del codice per parti:

1. Comando (HelloWorldCommand)

• GetResources() — descrive come appare il comando nell’interfaccia
• Activated() — cosa succede quando si preme
• IsActive() — quando il pulsante è attivo (ad esempio, solo se c’è un documento)

2. Ambiente di lavoro (HelloWorldWorkbench)

• Eredita da FreeCADGui.Workbench
• Il metodo Initialize() aggiunge i comandi alla barra e al menu
• GetClassName() dice a FreeCAD: «questo è un ambiente di lavoro Python»

3. Registrazione

• FreeCADGui.addCommand() associa il nome `