How to Create Custom QDeluxe Theme Archives (.qth files) Print

Overview

QDeluxe Theme Archives (.qth files) allow you to customize the appearance of your QDeluxe application. These theme files contain color schemes, background images, and preview images that completely transform the look and feel of the app interface.

What is a .qth file?

A .qth file is actually a ZIP archive containing:

• manifest.xml - Theme configuration file
• images/ folder - Drawable resources (backgrounds, icons, etc.)
• previews/ folder - Preview image shown in the Themes section

File Structure

Your theme archive should follow this structure:

mytheme.qth (ZIP file)
├── manifest.xml
├── images/
│   ├── background.png
│   ├── logo.png
│   └── other_images.png
└── previews/
    └── theme_preview.jpg

Creating the manifest.xml

The manifest.xml file is the heart of your theme. It defines all colors and drawable resources:

<?xml version="1.0"?>
<theme version="1.0" name="My Custom Theme">
    
    <!-- COLOR SECTION -->
    <color>
        <item name="primary">#2196F3</item>
        <item name="primary_dark">#1976D2</item>
        <item name="accent">#FF5722</item>
        <item name="primary_text">#FFFFFF</item>
        <item name="button_normal">#E0E0E0</item>
        <item name="button_focused">#FF9800</item>
        <item name="button_disabled">#9E9E9E</item>
        <item name="button_normal_text">#212121</item>
        <item name="button_focused_text">#FFFFFF</item>
        <item name="controller_background">#424242</item>
        <item name="dialog_background">#FAFAFA</item>
        <item name="textbox_background_normal">#F5F5F5</item>
        <item name="textbox_background_focused">#E3F2FD</item>
        <item name="textbox_normal_text">#616161</item>
        <item name="textbox_focused_text">#1976D2</item>
    </color>
    
    <!-- DRAWABLE SECTION -->
    <drawable>
        <item name="main_background" type="image">images/my_background.png</item>
    </drawable>
    
    <!-- PREVIEW SECTION -->
    <preview>
        <item>previews/theme_preview.jpg</item>
    </preview>
    
</theme>

Color Elements Explained

Primary Colors

• primary - Main theme color for headers and primary elements
• primary_dark - Darker variant used for status bars and navigation
• accent - Accent color for highlights, switches, and interactive elements

Text Colors

• primary_text - Main text color displayed on primary colored backgrounds
• textbox_normal_text - Text color in input fields (normal state)
• textbox_focused_text - Text color in input fields when focused

Button Colors

• button_normal - Default button background color
• button_focused - Button background when selected/focused
• button_disabled - Button background when disabled
• button_normal_text - Text color on normal buttons
• button_focused_text - Text color on focused/selected buttons

Background Colors

• controller_background - Background for control panels and toolbars
• dialog_background - Background color for popup dialogs
• textbox_background_normal - Background for text input fields (normal)
• textbox_background_focused - Background for text input fields (focused)

Drawable Resources

The drawable section allows you to replace any drawable resource in the APK:

<drawable>
    <item name="main_background" type="image">images/my_background.png</item>
    <item name="app_logo" type="image">images/custom_logo.png</item>
    <item name="button_background" type="image">images/button_bg.png</item>
</drawable>

Drawable Types

• type="image" - For bitmap images (PNG, JPG)
• type="color" - For solid color drawables

Image Guidelines

• Format: PNG recommended for transparency, JPG for photos
• Resolution: Use high-resolution images for better quality
• Size: Keep file sizes reasonable for faster loading

Creating Preview Images

The preview image appears in the app's Themes section to show users what the theme looks like:

Preview Requirements

• Location: Must be in previews/ folder
• Format: JPG or PNG
• Aspect Ratio: 16:9 recommended (e.g., 1920x1080)
• Content: Should showcase your theme's appearance

Example Preview Section

<preview>
    <item>previews/my_theme_preview.jpg</item>
</preview>

Step-by-Step Creation Process

1. Plan Your Theme

• Choose a color scheme (primary, accent, text colors)
• Select or create background images
• Design a preview image

2. Prepare Resources

• Create/gather all image files
• Resize images appropriately
• Organize files in proper folder structure

3. Create manifest.xml

• Copy the template above
• Customize the theme name
• Set your color values (use hex format: #RRGGBB)
• Reference your image files correctly

4. Package the Theme

• Create folders: images/ and previews/
• Place your images in the appropriate folders
• Add the manifest.xml to the root
• Select all files and create a ZIP archive
• Rename the .zip file to .qth

5. Test Your Theme

• Install the .qth file in QDeluxe
• Check that colors appear correctly
• Verify images display properly
• Ensure preview shows in Themes section

Color Format Guidelines

All colors must be in hex format:

• Format: #RRGGBB (Red, Green, Blue)
• Examples:
  • #FF0000 (Red)
  • #00FF00 (Green)
  • #0000FF (Blue)
  • #FFFFFF (White)
  • #000000 (Black)

Common Issues and Solutions

Advanced Tips

Using Transparency

• Use PNG format for images with transparency
• Transparent backgrounds can create layered effects

Color Coordination

• Use online color palette generators
• Ensure sufficient contrast for readability
• Test colors on different screen brightness levels

Performance Optimization

• Compress images to reduce file size
• Use appropriate image dimensions
• Avoid overly complex drawable resources

Example Themes

Dark Theme

<color>
    <item name="primary">#212121</item>
    <item name="primary_dark">#000000</item>
    <item name="accent">#FF5722</item>
    <item name="primary_text">#FFFFFF</item>
    <item name="dialog_background">#303030</item>
</color>

Blue Theme

<color>
    <item name="primary">#2196F3</item>
    <item name="primary_dark">#1976D2</item>
    <item name="accent">#FFC107</item>
    <item name="primary_text">#FFFFFF</item>
    <item name="dialog_background">#E3F2FD</item>
</color>

Troubleshooting

If your theme isn't working properly:

1. Validate XML: Use an online XML validator to check your manifest.xml
2. Check File Paths: Ensure all image paths are correct and files exist
3. Test Colors: Use a hex color picker to verify your color codes
4. Verify ZIP Structure: Make sure the folder structure is correct when creating the archive

Official Theme Collection

Looking for inspiration or ready-made themes? You can find a comprehensive collection of official rebrand themes at:

Using Official Themes as Templates

You can download any official theme and use it as a starting point for your own custom creation:

1. Download a .qth file from https://cockpit.lol/qth/
2. Rename the .qth file to .zip and extract it
3. Examine the manifest.xml structure
4. Replace images and modify colors as desired
5. Repackage as a new .qth file