# Word Search Generator & Player

A Python GUI application for generating and playing interactive word search puzzles with PDF export capability.

## Features

- **Interactive Puzzle Generation**: Create custom word search puzzles with configurable grid dimensions (5-25 x 5-25)
- **Drag-to-Select Gameplay**: Click and drag across letters to find words
- **Visual Feedback**:
  - Blue highlighting for selected letters
  - Green highlighting for found words
  - Strikethrough on found words in the word list
- **PDF Export**: Export puzzles to PDF format for printing
- **Smart Word Placement**:
  - 8-directional word placement (horizontal, vertical, and diagonal in all directions)
  - Words can appear forwards or backwards
  - Duplicate word prevention
- **Auto-Resizing Window**: Automatically adjusts to fit the generated puzzle
- **Clean PDF Output**: Grid lines removed for a professional appearance

## Requirements

- Python 3.x
- tkinter (usually included with Python)
- reportlab

## Installation

### Option 1: Download Pre-built Application (Recommended)

Download the pre-built application for your platform from the releases page:
- **Windows**: `WordSearch.exe`
- **macOS**: `WordSearch.app`
- **Linux**: `WordSearch` (executable)

No installation required - just download and run!

### Option 2: Run from Source

1. Clone the repository:
```bash
git clone https://git.firebugit.com/ksmith/WordSearch.git
cd WordSearch
```

2. Install required dependencies:
```bash
pip install -r requirements.txt
```

## Usage

### Running the Application

**From pre-built executable:**
- **Windows**: Double-click `WordSearch.exe`
- **macOS**: Double-click `WordSearch.app` or run `open WordSearch.app`
- **Linux**: Run `./WordSearch` from terminal

**From source:**
```bash
python word_search_generator.py
```

### Creating a Puzzle

1. Enter the desired grid dimensions (Width and Height)
2. Enter words to include in the puzzle (one per line)
3. Click "Generate & Play" to create the puzzle

### Playing the Game

1. Click and drag across letters to select a word
2. Release to check if the selection matches a word
3. Found words turn green and are crossed off the list
4. Use "Clear Selection" to reset your current selection

### Exporting to PDF

1. Generate a puzzle
2. Click "Export to PDF"
3. Choose a location to save the file

## How Words Are Placed

- Words can appear in 8 directions:
  - Horizontal (left-to-right or right-to-left)
  - Vertical (top-to-bottom or bottom-to-top)
  - Diagonal (all 4 diagonal directions)
- Words are placed randomly without duplicates
- Empty cells are filled with random letters

## Default Settings

- Default grid size: 12x12
- Default words: PYTHON, GUI, WORDSEARCH, GAME, PUZZLE, FUN
- Cell size: 30 pixels
- Grid dimensions: 5-25 (minimum-maximum)

## Technical Details

- Built with Python tkinter for the GUI
- Canvas-based interactive grid for responsive drag selection
- ReportLab for PDF generation
- Event-driven architecture for mouse interactions

## Building from Source

To create standalone executables for distribution:

### Prerequisites

Install build dependencies:
```bash
pip install -r requirements.txt
```

### Building

**Linux/macOS:**
```bash
./build.sh
```

**Windows:**
```cmd
build.bat
```

The built application will be in the `dist/` directory:
- **Linux**: `dist/WordSearch`
- **macOS**: `dist/WordSearch.app`
- **Windows**: `dist/WordSearch.exe`

### Manual Build

You can also build manually using PyInstaller:
```bash
pyinstaller word_search.spec
```

### Cross-Platform Notes

- PyInstaller creates platform-specific executables
- Build on the target platform (Windows build requires Windows, etc.)
- macOS builds create an `.app` bundle
- Linux/Windows builds create a single executable file

## License

Created by Keith Smith

## Contributing

This is a personal project. For issues or suggestions, please contact the repository owner.