jackfield-labeler

User Guide

Table of Contents

  1. Getting Started
  2. Application Overview
  3. Designer Tab
  4. Preview Tab
  5. Settings Tab
  6. File Operations
  7. Export Options
  8. Tips and Best Practices
  9. Troubleshooting

Getting Started

First Launch

When you first launch Jackfield Labeler, you’ll see the main window with three tabs:

The application starts with a default label strip configuration that you can immediately modify.

Quick Start Tutorial

Let’s create your first label strip:

  1. Set Strip Dimensions
    • In the Designer tab, set “Strip Height” to 6.0 mm
    • Set “Content Cell Width” to 12.0 mm
    • Set “Number of Content Cells” to 4
  2. Add Content
    • In the segment table, enter text for each cell: “CH1”, “CH2”, “CH3”, “CH4”
    • Choose different background colors for each channel
    • Keep text color as black for readability
  3. Preview Your Design
    • Click the “Preview” tab to see your label
    • The preview updates automatically as you make changes
  4. Generate PDF
    • Go to File → Generate PDF or click the “Generate PDF” button
    • Choose a location to save your PDF
    • Your label will be generated with the current settings

Application Overview

Main Window Components

Keyboard Shortcuts

Project State Tracking

The application tracks your project state:

Designer Tab

The Designer tab is your main workspace for creating label strips.

Control Panel

Located at the top of the Designer tab, the control panel contains global settings for your label strip:

Strip Dimensions

Content Management

Display Information

Segment Table

The segment table provides a spreadsheet-like interface for editing individual segments:

Table Columns

  1. Segment: Read-only identifier
    • Content segments numbered 1, 2, 3, etc.
    • End segment labeled “L_END” (when present)
    • Cannot be edited directly
  2. Text: The text to display on each segment
    • Click to edit directly
    • Supports Unicode characters
    • No length limit, but consider readability
    • Empty text is allowed
  3. Text Format: Formatting options for the text
    • Normal: Standard text (default)
    • Bold: Bold text for emphasis
    • Italic: Italic text for style
    • Choose from dropdown menu
  4. Text Color: Color of the text
    • Click the color button to open color picker
    • Standard colors: Black, White, Red, Green, Blue, Yellow, Orange, Purple
    • Custom colors available through color dialog
    • Default: Black (#000000)
  5. Background Color: Background color of the segment
    • Click the color button to open color picker
    • Same color options as text color
    • Consider contrast with text color for readability
    • Default: White (#FFFFFF)

Table Operations

Table Behavior

Action Buttons

Located at the bottom of the Designer tab:

Preview Tab

The Preview tab provides real-time visualization of your label strip design.

Strip Information Panel

Located at the top of the Preview tab, this panel shows:

Visual Preview

The main preview area shows a scaled representation of your label:

Preview Features

Preview Rendering

Preview Controls

Export Controls

PNG Export Features

Settings Tab

The Settings tab configures global options that affect all label generation.

Paper Settings

Paper Size

Choose from standard paper sizes:

Selection Guidelines:

Page Margins

Set margins for PDF output:

Margin Guidelines:

Rotation Settings

Rotation Angle

Rotation Guidelines:

Preset Buttons

Quick access to common rotations:

When to Use Presets:

Font Settings

Default Font

Font Selection:

Font Configuration

Default Colors

Default Text Color

Text Color Guidelines:

Default Background Color

Background Color Guidelines:

Settings Application

File Operations

Project Management

New Project

Open Project

Save Project

Save Project As

Project File Format

Jackfield Labeler uses .jlp files with the following features:

File Structure

{
  "version": "1.0",
  "application": "Jackfield Labeler",
  "label_strip": {
    "height": 6.0,
    "content_cell_width": 12.0,
    "segments": [
      {
        "type": "content",
        "id": "1",
        "width": 12.0,
        "text": "CH1",
        "text_color": "#000000",
        "background_color": "#FFFF00",
        "text_format": "NORMAL"
      }
    ],
    "settings": {
      "paper_size": "A3",
      "rotation_angle": 60.0,
      "default_font_name": "Arial",
      "default_font_size": 8.0
    }
  },
  "metadata": {
    "created_by": "Jackfield Labeler",
    "file_format_version": "1.0"
  }
}

Benefits

Project State Tracking

The application tracks your project state:

Window Title

Status Messages

File Validation

Export Options

PDF Generation

Access Methods

PDF Features

PDF Process

  1. Click Generate PDF
  2. Choose file location and name
  3. PDF is created with current settings
  4. Confirmation message shows success
  5. File is ready for printing

PDF Technical Details

PNG Export

Access Methods

PNG Features

PNG Process

  1. Click Export PNG
  2. Choose file location and name
  3. PNG is created at 300 DPI
  4. Confirmation message shows success
  5. File is ready for digital use

PNG Technical Details

Output Considerations

Choosing PDF vs PNG

Quality Settings

File Sizes

Tips and Best Practices

Design Guidelines

Text Readability

Color Selection

Dimensions

Workflow Optimization

Project Organization

Efficient Design Process

  1. Start with dimensions and basic layout
  2. Add all text content first
  3. Apply formatting and colors
  4. Preview frequently during design
  5. Test print on draft paper before final output

Template Creation

Printing Tips

Paper Selection

Cutting and Application

Color Management

Color Consistency

Accessibility

Troubleshooting

Common Issues

Application Won’t Start

Problem: Application fails to launch

Solutions:

Diagnostic Steps:

# Check Python version
python --version

# Check UV installation
uv --version

# Try running directly
uv run -m jackfield_labeler

# Check dependencies
uv pip list

PDF Generation Fails

Problem: PDF export produces errors

Solutions:

Common Causes:

Preview Not Updating

Problem: Preview tab doesn’t show changes

Solutions:

Diagnostic Steps:

  1. Verify strip has content
  2. Check total width calculation
  3. Look for validation errors
  4. Try creating new project

Colors Look Wrong

Problem: Colors in output don’t match preview

Solutions:

Color Troubleshooting:

File Won’t Open

Problem: Project file fails to load

Solutions:

File Validation:

# Check file format
file project.jlp

# Validate JSON
python -m json.tool project.jlp

Performance Issues

Slow Preview Updates

Problem: Preview takes time to update

Solutions:

Performance Tips:

Large File Sizes

Problem: Project files are unexpectedly large

Solutions:

File Size Guidelines:

Advanced Troubleshooting

Command Line Debugging

Run the application from command line to see detailed error messages:

# Run with debug output
uv run -m jackfield_labeler

# Check for Python errors
python -c "import jackfield_labeler; print('Import OK')"

# Verify PyQt6
python -c "from PyQt6.QtWidgets import QApplication; print('PyQt6 OK')"

Log Files

Check for log files in your system’s temporary directory:

Reset Settings

If settings become corrupted:

  1. Close the application
  2. Delete settings files (location varies by OS)
  3. Restart the application
  4. Reconfigure your preferences

Reinstallation

If problems persist:

  1. Uninstall the application
  2. Remove any remaining files
  3. Reinstall using the latest version
  4. Test with a simple project first

Getting Help

Documentation

Community Support

Reporting Issues

When reporting problems, include:

Issue Template:

**Environment:**
- OS: [Windows 10/macOS 12/Ubuntu 20.04]
- Python: [3.12.0]
- Application: [0.0.1]

**Problem:**
[Describe the issue]

**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [Third step]

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Additional Information:**
[Any other relevant details]

This comprehensive user guide should help you make the most of the Jackfield Labeler application. For additional support or feature requests, please visit the project’s GitHub repository.

This site is open source. Improve this page.