XFCE4 Terminal Theme Creator

A GTK4-based graphical interface for creating and customizing XFCE4 Terminal color themes. Built with PyGObject (GTK4), this application provides a professional, user-friendly way to design beautiful terminal color schemes with live preview and instant feedback.

Create beautiful terminal themes visually – no more manual .theme file editing!

✨ Features

🎨 Complete Theme Editing

• Full GUI with GTK4 color pickers for all terminal elements
• 16 ANSI color palette with semantic tooltips (hover to see what each color is used for)
• Live preview with realistic terminal scenarios (ls, git status, npm test)
• Blinking cursor animation in preview for realistic feel
• Global hue tint sliders to shift all colors at once (R/G/B bias)
• Randomize colors - generate random color schemes with one click
• Invert colors - flip light/dark themes instantly

💾 Theme Management

• Export themes to ~/.local/share/xfce4/terminal/colorschemes/ (for use in XFCE Terminal)
• Save to favorites for quick access within the app (⭐ starred presets)
• Load themes from existing .theme files
• Automatic backups before overwriting existing themes
• Smart filename validation with live feedback and sanitization
• Built-in presets including GitHub Light, Dracula, Nord, Solarized Dark
• Custom favorites - save your themes to the dropdown with ⭐ icon
• Delete custom presets - right-click starred items to remove
• Recent themes - quick access to last 5 opened themes (🕒 icon)

🎯 User Experience

• Smart tooltips explaining each color's real-world use
• Visual feedback for validation errors
• Keyboard shortcuts (Ctrl+S, Ctrl+O, Ctrl+R)
• Dark mode with persistent preference
• Window title shows theme name and unsaved changes indicator
• Apply button workflow for safe color previewing
• Error handling with user-friendly messages

🔧 Technical Features

• Semantic color names for all 16 ANSI palette positions with usage tooltips
• Visual grouping separating Normal (0-7) and Bright (8-15) colors
• "Use default" toggles for cursor, selection, and bold colors
• Comprehensive preview showing multiple realistic scenarios:
  • ls -la with colored files, directories, and permissions
  • git status with additions, modifications, and deletions
  • npm test output with PASS/FAIL results
  • Selection highlighting and cursor display
• Config persistence - app remembers dark mode preference and last directory
• Standards compliant - generates proper XFCE4 .theme format with semicolon-separated palettes

---

📦 Installation

Requirements

# Ubuntu / Debian / Linux Mint
sudo apt install python3-gi gir1.2-gtk-4.0

# Fedora
sudo dnf install python3-gobject gtk4

# Arch Linux
sudo pacman -S python-gobject gtk4

Requires Python 3.6+ and GTK 4

Quick Install

# Clone the repository
git clone https://github.com/YOUR_USERNAME/xfce4-terminal-theme-creator.git
cd xfce4-terminal-theme-creator

# Run the installation script
chmod +x install.sh
./install.sh

# Launch the application
xfce4-terminal-theme-creator
# Or find it in: Applications → Settings → XFCE4 Terminal Theme Creator

Or run directly without installing:

python3 term_theme_picker.py

The installation script will:

• Install the application to ~/.local/bin/
• Install icons to ~/.local/share/icons/hicolor/
• Install desktop file to ~/.local/share/applications/
• Create colorschemes directory if needed

---

🚀 Usage

Launching the Application

# After installation, find it in your application menu:
# Applications → Settings → XFCE4 Terminal Theme Creator

# Or run from terminal:
python3 term_theme_picker.py

Creating a Theme

1. Start with a preset or from scratch
2. Pick colors: Click any color button to open the GTK4 color picker
3. Fine-tune (optional):
   • Use Global Hue Tint sliders (R/G/B bias) to shift all colors
   • Click Apply Tint to commit changes
   • Or use Randomize for instant random colors
   • Or use Invert to flip light/dark
4. Preview: Watch your colors in realistic terminal scenarios with live cursor
5. Name your theme: Enter a descriptive name in the header
6. Export or Save:
   • Menu → Export as Theme File - saves to XFCE colorschemes folder
   • Menu → Save to Favorites - adds to app's dropdown list (⭐)

Applying Your Theme in XFCE Terminal

1. Export your theme: Menu → Export as Theme File
2. Open XFCE4 Terminal
3. Go to Edit → Preferences → Colors
4. Under Presets dropdown, select your theme name
5. Click Close - your theme is now active!

Note: "Save to Favorites" saves to the app's internal list only. Use "Export as Theme File" to make it available in XFCE Terminal.

Managing Custom Presets

Save a Favorite (⭐):

1. Create or modify your theme
2. Click Menu → Save to Favorites
3. Theme appears in dropdown with ⭐ icon
4. Quick access for future editing

Delete a Favorite:

1. Click the preset dropdown
2. Right-click on a ⭐ starred preset
3. Select "Delete '[preset-name]'"
4. Preset removed permanently

Preset Types:

• No icon = Built-in themes (GitHub Light, Dracula, Nord, Solarized Dark)
• ⭐ = Your saved favorites (stored in app config)
• 🕒 = Recently opened .theme files (last 5)

Favorites vs Exported: Favorites (⭐) are saved in ~/.config/xfce4-terminal-theme-creator/presets.json for use within the app. Exported themes go to ~/.local/share/xfce4/terminal/colorschemes/ for use in XFCE Terminal.

Keyboard Shortcuts

• Ctrl+S: Save theme
• Ctrl+O: Open theme file
• Ctrl+R: Reset to defaults

---

🎨 Color Palette Guide

Normal Colors (0-7)

Index	Color	Use Cases
0	Black	Dim text, inactive prompt parts
1	Red	Git deletions, errors, failed tests
2	Green	Git additions, executables, passed tests
3	Yellow	Git modifications, directories
4	Blue	Links, Git branches, current path
5	Magenta	Git renames, special files, sockets
6	Cyan	Archives, devices, symlinks
7	White	Default text color

Bright Colors (8-15)

Index	Color	Use Cases
8	Bright Black	Comments, dim elements
9	Bright Red	Bold errors, critical issues
10	Bright Green	Bold success, active hostname
11	Bright Yellow	Bold warnings
12	Bright Blue	Bold links, highlighted directory
13	Bright Magenta	Bold special items
14	Bright Cyan	Bold archives
15	Bright White	Bright text, full paths

Special Colors

• Foreground: Default text color
• Background: Terminal background color
• Cursor: Cursor color (can use default foreground)
• Selection: Highlighted text background
• Bold: Bold text color (can use default foreground)
• Tab Activity: Color for tabs with new output

---

📁 File Format

Themes are saved to:

~/.local/share/xfce4/terminal/colorschemes/your-theme-name.theme

Example .theme file:

[Scheme]
Name=My Custom Theme
ColorForeground=#24292f
ColorBackground=#ffffff
TabActivityColor=#0969da
ColorCursorUseDefault=FALSE
ColorCursor=#0969da
ColorCursorForeground=#ffffff
ColorSelectionUseDefault=TRUE
ColorBoldUseDefault=FALSE
ColorBold=#1f2328
BoldIsBright=TRUE
BackgroundVary=FALSE
ColorPalette=#24292f;#cf222e;#116329;#4d2d00;#0969da;#8250df;#1b7c83;#6e7781;#57606a;#a40e26;#1a7f37;#633c01;#218bff;#a475f9;#3192aa;#8c959f

Uses semicolons (;) as palette separators (XFCE4 standard format)

Automatic Backups

When overwriting an existing theme, a timestamped backup is automatically created:

your-theme-name.backup.20241122-181530.theme

---

🔧 Configuration

Application preferences are saved to:

~/.config/xfce4-terminal-theme-creator/config.ini

Persistent settings:

• Dark mode preference
• Last used directory for file dialogs

---

🛠️ Troubleshooting

Theme doesn't appear in XFCE4 Terminal

1. Make sure you used "Export as Theme File" not just "Save to Favorites"
2. Check the file exists: ls ~/.local/share/xfce4/terminal/colorschemes/
3. Ensure the file has .theme extension
4. Verify the file contains [Scheme] header
5. Restart XFCE4 Terminal completely (close all windows)

Colors don't match the preview

1. This was a bug fixed in v1.1 - ColorPalette was using periods instead of semicolons
2. If you have old theme files, re-export them with the updated app
3. Check the file has semicolons: grep ColorPalette ~/.local/share/xfce4/terminal/colorschemes/yourtheme.theme
4. Should see: ColorPalette=#xxx;#xxx;... not ColorPalette=#xxx.#xxx...

Colors seem missing or wrong

1. Check "Use Default" checkboxes - these override custom colors
2. Verify ColorPalette line has exactly 16 colors separated by semicolons
3. Check the live preview in the app before exporting

Permission errors

# Ensure colorschemes directory exists and is writable
mkdir -p ~/.local/share/xfce4/terminal/colorschemes
chmod 755 ~/.local/share/xfce4/terminal/colorschemes

Application won't start

# Verify GTK4 is installed
python3 -c "import gi; gi.require_version('Gtk', '4.0'); from gi.repository import Gtk"

# Check for error messages
python3 term_theme_picker.py 2>&1

---

🎯 Tips & Tricks

• Start with a preset - Modify existing themes rather than starting from scratch
• Use tooltips - Hover over palette colors to see what they're used for
• Global tint - Adjust all colors at once with R/G/B sliders instead of one-by-one
• Try randomize - Sometimes the best themes come from happy accidents!
• Check the preview - The live preview shows exactly how your theme will look
• Name descriptively - Use clear names like "Ocean Blue Dark" or "Monokai Sunset"
• Save favorites - Keep experimental themes as favorites (⭐) before exporting
• Test in terminal - Try your theme with real commands to see how it performs
• Coordinate themes - Match your terminal to your code editor for visual consistency

---

🤝 Contributing

Contributions are welcome! Here are some ideas:

New Features:

• Additional built-in preset themes
• Export to other terminal formats (GNOME Terminal, Alacritty, Kitty, iTerm2)
• Import from other terminal theme formats
• Color harmony suggestions (complementary, triadic, etc.)
• Theme sharing/download from community repository

Improvements:

• More preview scenarios (Python REPL, htop, vim, etc.)
• Accessibility improvements (contrast checking, color-blind friendly palettes)
• Better color picker with palette history
• Undo/redo functionality

# Fork and clone
git clone https://github.com/YOUR_USERNAME/xfce4-terminal-theme-creator.git
cd xfce4-terminal-theme-creator

# Make your changes
# Test thoroughly
python3 term_theme_picker.py

# Submit pull request

Before submitting:

• Test the app launches without errors
• Verify exported themes work in XFCE Terminal
• Check that saved favorites persist after restarting the app

---

📄 License

MIT License - See LICENSE file for details.

Free to use, modify, and distribute. No warranty provided.

---

👤 Author & Acknowledgments

Built with ❤️ for XFCE users who appreciate beautiful, functional terminals.

Technologies:

• GTK4 - Modern UI toolkit
• PyGObject - Python GTK bindings
• XFCE4 Terminal - Lightweight terminal emulator

---

📸 Screenshots

Main Interface: (Screenshot showing the full application with color pickers, preview, and presets)

Live Preview: (Screenshot showing the realistic terminal preview with syntax highlighting)

Preset Management: (Screenshot showing the dropdown with built-in, starred, and recent themes)

Screenshots coming soon! For now, run python3 term_theme_picker.py to see it in action.

---

🔗 Links

• XFCE4 Terminal Documentation
• GTK4 Documentation
• PyGObject Documentation

---

Enjoy creating beautiful terminal themes! 🎨✨