Lezione 6. Icone e aspetto visivo

📘 Corso di formazione: Creazione di addon per FreeCAD

Obiettivo della lezione: aggiungere icone ai pulsanti e all’ambiente di lavoro per rendere l’addon professionale.

---

🖼 Parte 1. Formati di icone supportati

FreeCAD supporta:

• SVG (consigliato) — scalabile senza perdite
• PNG — raster, ma facile da usare

💡 Le icone devono essere semplici, contrastanti e riconoscibili anche in piccole dimensioni (16×16 o 24×24 pixel).

---

📁 Parte 2. Struttura della cartella delle icone

Crea una sottocartella all’interno della cartella dell’addon:

BoxBuilderAddon/
├── Resources/
│   └── icons/
│       ├── box_builder.svg   ← icona dell'ambiente di lavoro
│       └── create_box.svg    ← icona del comando
├── InitGui.py
└── box_builder_workbench.py

💡 Il percorso Resources/icons/ è una convenzione standard nell’ecosistema FreeCAD.

---

🎨 Parte 3. Dove trovare le icone?

Opzione 1: Usa le icone integrate di FreeCAD

FreeCAD viene fornito con centinaia di icone. Ad esempio:

• :/icons/Part_Box.svg
• :/icons/Document-new.svg

Ma è meglio crearne di proprie — per non dipendere dai percorsi interni.

Opzione 2: Crea un’icona semplice manualmente

Esempio: create_box.svg

<!-- create_box.svg -->
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
  <rect x="10" y="10" width="44" height="44" fill="none" stroke="black" stroke-width="4"/>
  <line x1="10" y1="10" x2="20" y2="0" stroke="black" stroke-width="4"/>
  <line x1="54" y1="10" x2="64" y2="0" stroke="black" stroke-width="4"/>
  <line x1="54" y1="54" x2="64" y2="44" stroke="black" stroke-width="4"/>
  <line x1="20" y1="0" x2="64" y2="0" stroke="black" stroke-width="4"/>
  <line x1="64" y1="0" x2="64" y2="44" stroke="black" stroke-width="4"/>
</svg>

Salva questo codice nel file create_box.svg all’interno di Resources/icons/.

💡 Puoi aprire l’SVG nel browser per vedere il risultato.

---

🛠 Parte 4. Collegamento delle icone nel codice

Passaggio 1. Aggiorna box_builder_workbench.py

Aggiungi all’inizio del file (dopo gli import):

import os

Quindi trova la classe BoxBuilderCommand e aggiorna il metodo GetResources:

class BoxBuilderCommand:
    def GetResources(self):
        # Percorso dell'icona
        icon_path = os.path.join(
            os.path.dirname(__file__),
            "Resources", "icons", "create_box.svg"
        )
        return {
            "MenuText": "Box Builder",
            "ToolTip": "Create a box with custom dimensions",
            "Pixmap": icon_path  # ← collega l'icona
        }
    # ... il resto senza modifiche

Passaggio 2. Aggiungi un’icona per l’ambiente di lavoro

Nella classe BoxBuilderWorkbench aggiungi la proprietà Icon:

class BoxBuilderWorkbench(FreeCADGui.Workbench):
    MenuText = "Box Builder"
    ToolTip = "Create custom boxes with GUI"

    # Percorso dell'icona dell'ambiente di lavoro
    def __init__(self):
        self.Icon = os.path.join(
            os.path.dirname(__file__),
            "Resources", "icons", "box_builder.svg"
        )

    def Initialize(self):
        self.list = ["BoxBuilderCommand"]
        self.appendToolbar("Box Tools", self.list)
        self.appendMenu("Box Builder", self.list)

    def GetClassName(self):
        return "Gui::PythonWorkbench"

⚠️ Se non hai creato box_builder.svg — copia semplicemente create_box.svg e rinominalo.

---

🧪 Passaggio 5. Verifica del funzionamento

1. Assicurati che la struttura delle cartelle sia corretta:

   BoxBuilderAddon/Resources/icons/create_box.svg
   BoxBuilderAddon/Resources/icons/box_builder.svg

2. Riavvia FreeCAD
3. Seleziona l’ambiente di lavoro Box Builder

✅ Dovresti vedere:

• Un’icona accanto al nome dell’ambiente di lavoro (nell’elenco)
• Un’icona sul pulsante della barra degli strumenti

---

💡 Consigli sulle icone

• Usa il nero su sfondo trasparente — FreeCAD si adatterà automaticamente al tema (chiaro/scuro)
• La dimensione dell’SVG non è importante — l’importante è che sia vettoriale
• Per il PNG usa uno sfondo trasparente e una dimensione di 64×64 o 128×128
• Non usare colori — le icone in FreeCAD sono solitamente monocromatiche

---

🧪 Esercizio pratico

1. Crea l’icona box_builder.svg (puoi copiare create_box.svg)
2. Trova su internet un’icona SVG gratuita di una scatola (ad esempio, su Flaticon o Material Icons) e adattala
3. Prova a usare il PNG invece dell’SVG — assicurati che lo sfondo sia trasparente

---

🌐 Dove trovare icone pronte?

• Material Design Icons → scarica come SVG
• Feather Icons → semplici e pulite
• Codice sorgente di FreeCAD → centinaia di icone in formato .svg

---

▶️ Cosa c’è dopo?

Nella Lezione 7 impareremo a:

• Pubblicare l’addon tramite l’Addon Manager ufficiale
• Creare il file package.xml
• Preparare il repository su GitHub
• Fare in modo che altri utenti possano installare facilmente il tuo addon