README.md

Word's Quest - Photo Dictionary

A small desktop dictionary app built with Python and Tkinter. Type a word, see its definition, and see a matching illustration alongside it. You can also add new words directly from the app, and they're saved to the local dictionary file for future lookups.

Features

• Word lookup - search the local dictionary for a word and see its definition instantly, with live autocomplete suggestions as you type.

• Photo matching - words that have a matching illustration under assets/images/ show the picture alongside the definition, scaled to fit without distortion.

• "Word not found" prompt - searching for a word that isn't in the dictionary shows a popup offering to add it, either manually or by looking it up online (see below), instead of a dead end. Near-miss typos also get a "did you mean" suggestion.

• Add your own words - a tab lets you add a new word and meaning, which is saved to data/dictionary.csv and immediately available to search. Adding a word that already exists asks before overwriting it, instead of silently creating a duplicate entry.

• Browse all words - a filterable, scrollable list of every word in the dictionary; pick one to jump straight to its definition.

  

• Optional online lookups - fetch a definition and matching photo automatically for a word that isn't in the local dictionary yet, powered by the free Free Dictionary API and the Pexels API. Entirely optional - see "Online lookups (optional)" below.

  

• Fully usable offline - the core app (lookup, add, browse) never makes a network call. Online lookups are opt-in and fail gracefully with a clear message if you're offline, don't have requests installed, or haven't configured a Pexels API key.

• Live word count - a status line at the bottom tracks how many words are currently in the dictionary.

• Keyboard shortcuts - Ctrl+F jumps to and focuses the search box, Enter searches, Esc clears the search box.

Tech stack

• Python 3
• Tkinter / ttk for the UI, with a custom ttk.Style theme (no default gray Tk look)
• Pillow for loading and resizing photos
• requests for the optional online definition/photo lookups (not needed for the core offline app)
• The standard library csv and difflib modules for reading/writing the dictionary and generating "did you mean" suggestions

Data source

Word definitions live in data/dictionary.csv, a simple two-column CSV (name,meaning). The app reads this file at startup and writes new entries back to it when you use the "Add a Word" tab. Local lookups never touch the network, so the core app works fully offline and lookups are instant.

The illustrations in assets/images/ are sample stock images bundled only as placeholder content for this demo. They are not original photography and carry no redistribution license - swap them out for your own licensed or original images if you plan to use this project for anything beyond a personal portfolio piece. See the note at the bottom of LICENSE for details.

Project structure

main.py                    entry point - creates the Tk root and launches the app
photo_dictionary/
    data.py                 loads/searches/updates the dictionary CSV and image index
    online.py                optional definition/photo lookups (Free Dictionary API, Pexels)
    ui.py                    ttk widgets, layout, styling, and the app's tabs
data/dictionary.csv         word/meaning pairs
assets/images/               illustrations, matched to words by filename
assets/logo.jpg               small app logo shown in the header
docs/screenshot*.png         screenshots used in this README

Setup

Requires Python 3.9+ with Tkinter available (Tkinter ships with the standard python.org installers on Windows and macOS; on Linux you may need to install your distribution's python3-tk package separately).

git clone https://github.com/Jenks00/Photo-Dictionary-with-python-Tkinter.git
cd Photo-Dictionary-with-python-Tkinter

python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS / Linux

pip install -r requirements.txt
python main.py

Online lookups (optional)

Definitions come from the free Free Dictionary API and don't need any signup or API key - just requests installed (already in requirements.txt) and an internet connection.

Photos come from the Pexels API, which needs a free API key:

1. Create a free account at pexels.com/api and copy your API key.

2. Set it as an environment variable before launching the app:

   set PEXELS_API_KEY=your-key-here        # Windows (cmd)
   $env:PEXELS_API_KEY = "your-key-here"    # Windows (PowerShell)
   export PEXELS_API_KEY=your-key-here      # macOS / Linux

Without a key, definition lookups still work - only the automatic photo fetch is skipped, with a clear message explaining why.

Adding your own words and pictures

• To add a word from within the app, use the "Add a Word" tab - it writes straight to data/dictionary.csv.
• To attach a picture to a word, drop an image into assets/images/ named after the word (e.g. assets/images/lighthouse.jpg for the word "lighthouse"). Matching is case-insensitive, so Lighthouse.jpg works too.

Packaging

To share a standalone build that doesn't require Python to be installed, package it with PyInstaller:

pip install pyinstaller
pyinstaller --noconsole --onefile --add-data "data;data" --add-data "assets;assets" main.py

(On macOS/Linux, use : instead of ; in --add-data.) The bundled executable will be created under dist/.

Notes on this version

This is a redesign of an earlier version of the project. The original had several duplicate, half-finished screens wired together with a fragile "import a module to open its window" navigation trick, which broke as soon as you tried to navigate back and forth between screens. This version consolidates everything into a single window with proper tab-based navigation, fixes that navigation bug, and rebuilds the UI with ttk styling, consistent spacing, and clearer empty/error states.