================================================================================
  Flag Pin Tool – Installation Guide
  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================


TABLE OF CONTENTS
-----------------
  1.  System Requirements
  2.  Installation: Linux / Raspberry Pi
  3.  Installation: Windows
  4.  The Desktop Launcher (Linux / Raspberry Pi)
  5.  Starting the Program
  6.  Troubleshooting


================================================================================
1.  SYSTEM REQUIREMENTS
================================================================================

Supported Platforms
-------------------
  - Raspberry Pi 4B running Raspberry Pi OS Bookworm or Bullseye (primary)
  - Linux (Ubuntu, Debian, and derivatives)
  - Windows 10 / 11

Python Version
--------------
  Python 3.9 or newer is required.

  Check your version:
      python3 --version       (Linux / Raspberry Pi)
      python  --version       (Windows)

Required Python Packages
------------------------
  Flag Pin Tool uses only the Python standard library for its core features.
  One additional package is required for the Tools > Grid Converter feature:

      mgrs  (MGRS/USNG coordinate conversion)

  Install it with pip:
      pip3 install mgrs          (Linux / Raspberry Pi)
      pip  install mgrs          (Windows)

  If mgrs is not installed, Flag Pin Tool will start and run normally —
  only the Grid Converter tool will be unavailable.

  Tkinter is pre-installed on Raspberry Pi OS and most Linux distributions.
  See Troubleshooting (Section 6) if it is missing on your system.

Internet Connection
-------------------
  Not required for normal operation. An internet connection is only used for
  the optional startup version check, which runs as a silent background thread
  and does not affect program function if the network is unavailable.


================================================================================
2.  INSTALLATION: LINUX / RASPBERRY PI
================================================================================

Step 1 — Copy the program files
---------------------------------
  Place the flagpintool folder wherever you prefer. The recommended location
  for a single-user installation is the home directory:

      /home/<username>/flagpintool

  The program creates its data/ subdirectory automatically on first run.
  No other directories need to be created in advance.

Step 2 — Verify Python and tkinter
-------------------------------------
  Open a terminal and run:

      python3 --version
      python3 -c "import tkinter; print('tkinter OK')"

  If python3 is not found, install it:
      sudo apt install python3

  If tkinter is missing, install it:
      sudo apt install python3-tk

Step 3 — Install the desktop launcher
---------------------------------------
  See Section 4 for full details. Quick install:

      cp /home/<username>/flagpintool/flagpintool.desktop \
          ~/.local/share/applications/
      cp /home/<username>/flagpintool/flagpintool.desktop ~/Desktop/
      chmod +x ~/Desktop/flagpintool.desktop
      update-desktop-database ~/.local/share/applications

Step 4 — Launch the program
-----------------------------
  From the terminal:
      python3 /home/<username>/flagpintool/flagpintool.py

  Or use the desktop launcher once it has been installed (Step 3).


================================================================================
3.  INSTALLATION: WINDOWS
================================================================================

Step 1 — Install Python
------------------------
  If Python is not already installed, download it from python.org.
  During installation, check the box labeled "Add Python to PATH."

  Verify the installation:
      python --version

  Tkinter is included with the standard Python Windows installer. No
  additional packages are needed.

Step 2 — Copy the program files
---------------------------------
  Place the flagpintool folder in a convenient location, for example:

      C:\Users\<username>\flagpintool

Step 3 — Create a desktop shortcut
-------------------------------------
  Windows does not use .desktop launcher files. To create a shortcut:

  1. Right-click the Desktop and select New > Shortcut.
  2. In the Location field, enter (adjust the path to match your install):
         python "C:\Users\<username>\flagpintool\flagpintool.py"
  3. Click Next, name it "Flag Pin Tool", and click Finish.
  4. To add the icon: right-click the shortcut > Properties > Change Icon…,
     browse to:
         C:\Users\<username>\flagpintool\FlagPinTool.png
     Note: Windows shortcut icons require .ico format. If the PNG does not
     display correctly, skip this step — the shortcut will still work.

  Alternatively, create a batch file (flagpintool.bat) with these contents
  and create a shortcut to it:
      @echo off
      python "C:\Users\<username>\flagpintool\flagpintool.py"

Step 4 — Launch the program
-----------------------------
  Double-click the desktop shortcut, or from a Command Prompt:
      python C:\Users\<username>\flagpintool\flagpintool.py


================================================================================
4.  THE DESKTOP LAUNCHER (LINUX / RASPBERRY PI)
================================================================================

What Is a .desktop File?
--------------------------
  On Linux desktops (including Raspberry Pi OS with LXDE, as well as GNOME,
  KDE, XFCE, and others), a .desktop file is the standard way to define a
  clickable application launcher. It tells the desktop environment the
  program name, the command to run, and which icon to display.

  Windows uses shortcut (.lnk) files for the same purpose. See Section 3
  for Windows shortcut creation.

The flagpintool.desktop File
------------------------------
  The file flagpintool/flagpintool.desktop is pre-configured for an
  installation at /home/stephen/flagpintool. If you installed to a different
  username or location, edit the Exec= and Icon= lines before copying:

      Exec=/home/<username>/flagpintool/run.sh
      Icon=/home/<username>/flagpintool/FlagPinTool.png

The run.sh Launcher Script
----------------------------
  The run.sh script in the flagpintool folder is the launch command used
  by the .desktop file. It performs a quick tkinter availability check and
  shows a user-friendly error dialog (via zenity) if tkinter is missing,
  rather than silently failing.

  run.sh does not set up a virtual environment — no venv is needed because
  Flag Pin Tool has no external dependencies.

Installing the Launcher
------------------------
  Copy the (adjusted) .desktop file to two locations:

    ~/.local/share/applications/flagpintool.desktop
        Makes Flag Pin Tool appear in the application menu.

    ~/Desktop/flagpintool.desktop
        Places a clickable icon on the Desktop (only if ~/Desktop/ exists).

  After copying, refresh the application database:
      update-desktop-database ~/.local/share/applications

  Full one-line install (adjust path if needed):
      cp /home/<username>/flagpintool/flagpintool.desktop \
          ~/.local/share/applications/ && \
      cp /home/<username>/flagpintool/flagpintool.desktop ~/Desktop/ && \
      chmod +x ~/Desktop/flagpintool.desktop && \
      update-desktop-database ~/.local/share/applications

If the Desktop Icon Did Not Appear
-------------------------------------
  1. Verify the Exec= and Icon= paths in the .desktop file match your actual
     installation location and that flagpintool.py exists there.

  2. Verify run.sh is executable:
         chmod +x /home/<username>/flagpintool/run.sh

  3. Mark the Desktop copy as executable:
         chmod +x ~/Desktop/flagpintool.desktop

  4. Some GNOME configurations hide .desktop file icons on the Desktop by
     default. Right-click the Desktop and look for "Allow Launching."

  5. Try logging out and back in to force a full desktop refresh.

  6. Check that ~/Desktop/ exists. Flag Pin Tool will still appear in the
     application menu even if no Desktop icon was created.

Running Without a Desktop Icon
--------------------------------
  Flag Pin Tool can always be launched from a terminal:
      python3 /home/<username>/flagpintool/flagpintool.py

  Or via the launcher script:
      bash /home/<username>/flagpintool/run.sh


================================================================================
5.  STARTING THE PROGRAM
================================================================================

Linux / Raspberry Pi
---------------------
  Double-click the Flag Pin Tool icon on the Desktop or in the application menu.

  Or from a terminal:
      python3 /home/<username>/flagpintool/flagpintool.py

Windows
--------
  Double-click the Flag Pin Tool shortcut on the Desktop.

  Or from a Command Prompt:
      python C:\Users\<username>\flagpintool\flagpintool.py

First-Time Use
---------------
  On first launch the pin list is empty. Use Add… in the toolbar or the
  Quick Add strip at the bottom to create new pins, or use Import CSV/TSV…
  to import existing data.

  The station callsign and default color can be set in the options bar at
  the top of the window or in Settings > Settings…

Data Storage
-------------
  All data is stored in the flagpintool/data/ directory:

      data/settings.json       Application settings (auto-saved on exit)
      data/imports/            Default folder for imported CSV/TSV files
      data/exports/            Default folder for exported .flags.json files

  Flag pin data is NOT auto-saved to a fixed file as in MH Grid Mapper.
  In Flag Pin Tool, you control which file pins are saved to via File > Save
  or File > Save As. This gives you full control over multiple pin datasets.


================================================================================
6.  TROUBLESHOOTING
================================================================================

"ModuleNotFoundError: No module named 'tkinter'"
-------------------------------------------------
  Tkinter is not installed. On Raspberry Pi OS, Ubuntu, or Debian:
      sudo apt install python3-tk

  On Fedora / RHEL / Rocky Linux:
      sudo dnf install python3-tkinter

  On Windows: tkinter is bundled with the standard Python installer from
  python.org. If it is missing, re-run the Python installer and ensure the
  "tcl/tk and IDLE" component is checked.

Program launches but the window appears blank or very small
-----------------------------------------------------------
  This can happen if a saved window geometry from a previous session is
  incompatible with the current display resolution. Reset it by deleting:
      /home/<username>/flagpintool/data/settings.json
  The program will recreate it with defaults on next launch.

Desktop icon does not appear after installation (Linux / Raspberry Pi)
-----------------------------------------------------------------------
  See "If the Desktop Icon Did Not Appear" in Section 4 above.

Desktop shortcut not visible after creation (Windows)
------------------------------------------------------
  The most common cause on Windows 11 is a OneDrive Desktop redirect.
  When OneDrive is active, the Desktop folder may be at:
      C:\Users\<username>\OneDrive\Desktop
  rather than:
      C:\Users\<username>\Desktop
  Create the shortcut directly in the OneDrive Desktop folder, or look for
  it in C:\Users\<username>\Desktop and move it.

Application menu entry does not appear (Linux)
-----------------------------------------------
  Refresh the desktop application database:
      update-desktop-database ~/.local/share/applications
  Then check the application menu. If it still does not appear, try logging
  out and back in.

Tools > Grid Converter… shows an error or does nothing
------------------------------------------------------
  The Grid Converter requires the mgrs package. Install it:
      pip3 install mgrs          (Linux / Raspberry Pi)
      pip  install mgrs          (Windows)
  Then restart Flag Pin Tool.

"Check for Updates Now" shows "Check Failed"
--------------------------------------------
  The version check URL is unreachable. Confirm you have an active internet
  connection. The URL can be verified or changed in Settings > Settings… >
  Auto-Update tab. Leaving the URL blank disables all update checks.

Imported CSV data shows 0 pins imported
-----------------------------------------
  Every imported row must have either a valid Grid value (Maidenhead locator
  such as EL99hc) or both Latitude and Longitude values. Rows where neither
  is valid are skipped. Check the column mapping in the import dialog and
  confirm the source data has recognizable grid or coordinate values.

Saved .flags.json file is not recognized by JS8Reporter or MH Grid Mapper
--------------------------------------------------------------------------
  Verify the file was saved or exported using File > Save / Save As / Export
  .flags.json…. The file must have "format": "sitrep_flags" in its header.
  Opening the file in a text editor and checking the first few lines will
  confirm this. If the file was created by another program or has a different
  format, use Import CSV/TSV… or Merge Flag Pins… to load and re-export it.

Config file location
---------------------
  Settings are saved to:
      Linux / Raspberry Pi:  /home/<username>/flagpintool/data/settings.json
      Windows:               C:\Users\<username>\flagpintool\data\settings.json

  Deleting this file resets all settings to defaults. Flag pin data is not
  affected — it is stored in whichever .flags.json file you last saved.


================================================================================
  End of Flag Pin Tool Installation Guide
  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================
