Lesson 6. Icons and Visual Design

📘 Tutorial: Creating Addons for FreeCAD

Lesson Goal: Add icons to buttons and the workbench to make the addon look professional.

---

🖼 Part 1. Supported Icon Formats

FreeCAD supports:

• SVG (recommended) — scales without loss
• PNG — raster, but easy to use

💡 Icons should be simple, contrasting, and recognizable even at a small size (16×16 or 24×24 pixels).

---

📁 Part 2. Icon Folder Structure

Inside your addon’s folder, create a subfolder:

BoxBuilderAddon/
├── Resources/
│   └── icons/
│       ├── box_builder.svg   ← workbench icon
│       └── create_box.svg    ← command icon
├── InitGui.py
└── box_builder_workbench.py

💡 The path Resources/icons/ is a standard convention in the FreeCAD ecosystem.

---

🎨 Part 3. Where to get icons?

Option 1: Use built-in FreeCAD icons

FreeCAD comes with hundreds of icons. For example:

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

But it’s better to create your own — to avoid dependency on internal paths.

Option 2: Create a simple icon manually

Example: 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>

Save this code to create_box.svg inside Resources/icons/.

💡 You can open the SVG in a browser to see the result.

---

🛠 Part 4. Connecting icons in code

Step 1. Update box_builder_workbench.py

Add to the beginning of the file (after imports):

import os

Then find the BoxBuilderCommand class and update the GetResources method:

class BoxBuilderCommand:
    def GetResources(self):
        # Path to the icon
        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  # ← connect the icon
        }
    # ... rest unchanged

Step 2. Add an icon for the workbench

In the BoxBuilderWorkbench class, add the Icon property:

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

    # Path to the workbench icon
    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"

⚠️ If you haven’t created box_builder.svg — just copy create_box.svg and rename it.

---

🧪 Step 5. Verification

1. Make sure the folder structure is correct:

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

2. Restart FreeCAD
3. Select the Box Builder workbench

✅ You should see:

• An icon next to the workbench name (in the list)
• An icon on the toolbar button

---

💡 Icon Tips

• Use black on a transparent background — FreeCAD will adapt it to the theme (light/dark)
• SVG size doesn’t matter — the main thing is that it’s vector
• For PNG, use a transparent background and a size of 64×64 or 128×128
• Do not use colors — icons in FreeCAD are usually monochrome

---

🧪 Practical Task

1. Create the box_builder.svg icon (you can copy create_box.svg)
2. Find a free SVG box icon online (e.g., on Flaticon or Material Icons) and adapt it
3. Try using PNG instead of SVG — make sure the background is transparent

---

🌐 Where to get ready-made icons?

• Material Design Icons → download as SVG
• Feather Icons → simple and clean
• FreeCAD sources → hundreds of icons in .svg format

---

▶️ What’s next?

In Lesson 7 we will:

• Learn how to publish an addon via the official Addon Manager
• Create a package.xml file
• Prepare a GitHub repository
• Make it easy for other users to install your addon